ch.Form

Description

Form is a controller of DOM's HTMLFormElement.

How-to

// Create a new Form.
var form = new ch.Form($el, [options]);

// Create a new Form with jQuery or Zepto.
var form = $(selector).form();

// Create a new Form with custom messages.
var form = $(selector).form({
    'messages': {
         'required': 'Some message!',
         'email': 'Another message!'
    }
});

Parameters

• $el - jQuerySelector | ZeptoSelector : A jQuery or Zepto Selector to create an instance of ch.Form.
• options - Object : Options to customize an instance.
  • messages - Object : A collections of validations messages.
    • required - String : A validation message.
    • string - String : A validation message.
    • url - String : A validation message.
    • email - String : A validation message.
    • maxLength - String : A validation message.
    • minLength - String : A validation message.
    • custom - String : A validation message.
    • number - String : A validation message.
    • min - String : A validation message.
    • max - String : A validation message.
    • price - String : A validation message.

Extends

• ch.Widget

Properties

.$container jQuerySelector | ZeptoSelector

The form container.

.errors Array

A collection of active errors.

.uid Number

A unique id to identify the instance of a widget.

.validations Array

A collection of validations instances.

.Widget#name String

The name of a widget.

// You can reach the instance associated.
var widget = $(selector).data(name);

Methods

.emit(event, var_args)

Execute each item in the listener collection in order with the specified data.

• event - String : The name of the event you want to emit.
• var_args - Object : Data to pass to the listeners.

// Will emit the 'ready' event with 'param1' and 'param2' as arguments.
widget.emit('ready', 'param1', 'param2');

.getListeners(event) → {Array}

Returns all listeners from the collection for a specified event.

• event - String : The event name.

// Returns listeners from 'ready' event.
widget.getListeners('ready');

.off(event, listener) → {Object}

Removes a listener from the collection for a specified event.

• event - String : Event name.
• listener - Function : Listener function.

// Will remove event listener to 'ready' event.
widget.off('ready', listener);

.on(event, listener, once)

Adds a listener to the collection for a specified event.

• event - String : The event name to subscribe.
• listener - Function : Listener function.
• once - Boolean : Indicate if a listener function will be called only one time.

// Will add an event listener to 'ready' event.
widget.on('ready', listener);

.once(event, listener) → {Object}

Adds a listener to the collection for a specified event to will execute only once.

• event - String : Event name.
• listener - Function : Listener function.

// Will add an event handler to 'contentLoad' event once.
widget.once('contentLoad', listener);

.clear() → {form}

Clear all active errors.

// Clear active errors.
form.clear();

.constructor()

Returns a reference to the constructor function.

.destroy()

Destroys a Form instance.

// Destroying an instance of Form.
form.destroy();

.hasError() → {Bollean}

Checks if the form has got errors but it doesn't show bubbles.

// Checks if a form has errors and do something.
if (form.hasError()) {
    // Some code here!
};

.reset() → {form}

Clear all active errors and executes the reset() native mehtod.

// Resets form fields and clears active errors.
form.reset();

.validate() → {form}

Executes all validations.

.constructor()

Returns a reference to the constructor function.

.destroy()

Destroys an instance of Widget and remove its data from asociated element.

// Destroying an instance of Widget.
widget.destroy();

.disable() → {instance}

Disables an instance of Widget.

// Disabling an instance of Widget.
widget.disable();

.enable() → {instance}

Enables an instance of Widget.

// Enabling an instance of Widget.
widget.enable();

.require() → {instance}

Adds functionality or abilities from other classes.

// You can require some abilitiest to use in your widget.
// For example you should require the collpasible abitliy.
var widget = new Widget(element, options);
widget.require('Collapsible');

Events

'beforevalidate'

It emits an event when the form will be validated.

// Subscribe to "beforevalidate" event.
widget.on('beforevalidate', function () {
 // Some code here!
});

'clear'

It emits an event when the form is cleaned.

// Subscribe to "clear" event.
form.on('clear', function () {
 // Some code here!
});

'destroy'

Emits when a widget is destroyed.

// Subscribe to "destroy" event.
widget.on('destroy', function () {
 // Some code here!
});

'disable'

Emits when a widget is disable.

// Subscribe to "disable" event.
widget.on('disable', function () {
 // Some code here!
});

'enable'

Emits when a widget is enable.

// Subscribe to "enable" event.
widget.on('enable', function () {
 // Some code here!
});

'error'

It emits an event when a form has got errors.

// Subscribe to "error" event.
form.on('error', function (errors) {
 console.log(errors.length);
});

'ready'

It emits an event when the form is ready to use.

// Subscribe to "ready" event.
form.on('ready', function () {
    // Some code here!
});

'reset'

It emits an event when a form resets its fields.

// Subscribe to "reset" event.
form.on('reset', function () {
 // Some code here!
});

'success'

It emits an event when a form hasn't got errors.

// Subscribe to "success" event.
form.on("submit",function () {
 // Some code here!
});

// Subscribe to "success" event and prevent the submit event.
form.on("submit",function (event) {
 event.preventDefault();
 // Some code here!
});