ch.String

Description

String creates a new instance of Validation to validate a given value as string.

How-to

// Create a new String Validation.
var strValidation = new ch.String($el, [options]);

// Create a new String validation with jQuery or Zepto.
var strValidation = $(selector).string([options]);

// Create a new String validation with custom options.
var strValidation = $(selector).string({
    'message': 'This field must be a string.',
    'offsetX': 0,
    'offsetY': 10,
    'side': 'bottom',
    'align': 'left'
});

// Create a new String validation using the shorthand way (message as parameter).
var strValidation = $(selector).string('This field must be a string.');

Parameters

• $el - jQuerySelector | ZeptoSelector : A jQuery or Zepto Selector to create an instance of ch.Validation.
• options - Object : Options to customize an instance.
  • message - String : The given error message to the condition.
  • reference - jQuerySelector | ZeptoSelector : It's a reference to position and size of element that will be considered to carry out the position.
  • side - String : The side option where the target element will be positioned. Default: "right".
  • align - String : The align options where the target element will be positioned. Default: "top".
  • offsetX - Number : Distance to displace the target horizontally. Default: "10px".
  • offsetY - Number : Distance to displace the target vertically. Default: "0px".
  • position - String : The type of positioning used. Default: "absolute".

Extends

• ch.Validation

Properties

.$trigger jQuerySelector | ZeptoSelector

The validation trigger.

.bubble Bubble

Is the little sign that popover showing the validation message. It's a Popover widget, so you can change it's content, width or height and change its visibility state.

.conditions Object

The collection of conditions.

.error Object

The current error. If the validations has not error is "null".

.form form

Reference to a Form instance. If there isn't any, the Validation instance will create one.

.Str#name String

The name of the widget.

.uid Number

A unique id to identify the instance of a widget.

.Validation#name String

The name of the widget.

.Widget#name String

The name of a widget.

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

Methods

.disable(condition) → {validation}

Disables an instance of a validation or a specific condition.

• condition - String : A given number of fold to disable.

// Disabling an instance of Validation.
validation.disable();

// Disabling the "email" condition.
validation.disable('email');

.enable(condition) → {validation}

Enables an instance of validation or a specific condition.

• condition - String : A given number of fold to enable.

// Enabling an instance of Validation.
validation.enable();

// Enabling the "max" condition.
validation.enable('max');

.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);

.refreshPosition() → {validation}

Sets or gets positioning configuration. Use it without arguments to get actual configuration. Pass an argument to define a new positioning configuration.

// Change validaton bubble's position.
validation.refreshPosition({
    offsetY: -10,
    side: 'top',
    align: 'left'
});

.constructor()

Returns a reference to the constructor function.

.and() → {jQuerySelector|ZeptoSelector}

Returns the jQuerySelector or ZeptoSelector to chaining more validations.

// Concatenates another validation.
validation.and().validation();

.clear() → {validation}

Clear active error.

// Clear active error.
validation.clear();

.constructor()

Returns a reference to the constructor function.

.destroy()

Destroys a Validation instance.

// Destroying an instance of Validation.
validation.destroy();

.hasError() → {Bollean}

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

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

.isShown() → {Boolean}

Indicates if the validation is shown.

// Execute a function if the validation is shown.
if (validation.isShown()) {
    fn();
}

.message() → {validation|String}

Sets or gets messages to specifics conditions.

// Gets a message from a condition
validation.message('required');

// Sets a new message
validation.message('required', 'New message for required validation');

.validate() → {validation}

Validates the value of $el.

.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

'clear'

It emits an event when a validation is cleaned.

// Subscribe to "clear" event.
validation.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 validation hasn't got an error.

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

'ready'

It emits an event when a validation is ready to use.

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

'success'

It emits an event when a validation hasn't got an error.

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