guards.js

View the Project on GitHub on-site/guards.js

Guard Type

using

signature: guard.using(name | customFunction)

available since: 1.0.0

Guard inputs with the specified name guard, or with a custom function. If the first argument provided is a string, it must correspond to a named guard. This may be one of the default named guards, or a guard named via $.guards.name(name). Additional arguments may be given as options to the named guard. All attributes specified by the named guard will be copied over when the using method is invoked.

Alternatively, a function may be provided as the custom guard function. This function is invoked when guards are being tested with the value of the element guarded, and the element being guarded. If the guard is grouped, it will be an array of values with the corresponding array of elements.


Required field


Field must not be 'invalid'



One must be 'test'

precondition

signature: guard.precondition(preconditionFunction)

available since: 1.0.0

Specify a precondition for this guard. A parameter is required with the precondition function. This function accepts the element and element value as the parameters, like a custom guard function. The precondition is executed before the guard when any given input is about to be guarded. If the precondition returns false explicitly, the guard will not be executed and the field will be considered valid. Any other return value means the precondition passed (even no return). If the guard is grouped, the parameters will be the array of values and elements (like for a custom guard function).



Guarded with required if the checkbox is checked

grouped

signature: guard.grouped([true | false])

available since: 1.0.0

Mark this guard as being grouped. A grouped guard will guard all affected elements at once, instead of individually. Each guarded element with an error will still be marked as an error, but only one error message will be added. Custom guard functions will receive all elements and their values at once instead of individually. By default, a guard is not considered grouped. Name guards, however, carry their grouped status on, so a guard using oneRequired, different, and same will be grouped by default.

If no argument is given, the guard will be marked as grouped, otherwise the parameter is exoected to be a boolean indicating whether the guard should be grouped.



These are effectively guarded with 'required' now



One must be 'test'

tag

signature: guard.tag(htmlTag)

available since: 1.0.0

Change the tag type that surrounds the error message. By default, a span tag is used.

messageClass

signature: guard.messageClass(cssClass)

available since: 1.0.0

Change what class is used for error messages added due to failed guards. By default, the error element has the class error-message, but that class will not be userd if a different one is specified with this method.

message

signature: guard.message(errorMessage)

available since: 1.0.0

Customize the error message displayed if the guard fails. The default named guards have messages already defined, but they may be changed with this method.

invalidClass

signature: guard.invalidClass(cssClass)

available since: 1.0.0

Change what class is added to invalid fields. By default, the invalid class added is invalid, but that class will not be added if a different one is specified with this method.

target

signature: guard.target(selector | targetingFunction)

available since: 1.0.0

Specify where the error will be placed in the DOM when this guard fails. The argument can be a jQuery selector, element, set of elements, jQuery selected set of elements, or a function. If the argument is anything except a function, it will be passed to the jQuery function and the first element will be retrieved and used as the place to append the error message. If it is a function, the function may either insert the error message itself, or return the location to place the error message.

When provided a function, the function will be called when an error has happened. The function's this reference will be set to the error element (or set of elements in the case of a grouped guard) that had the error. The argument will be the error message element that will be appended. When false is returned, the function is expected to have inserted the provided error message in the DOM. Otherwise, the return value is expected to be a jQuery selector, element, set of elements or jQuery selected set of elements of which the first will have the error element appended to it.

The default behavior is to append the error message after the last error element that is guarded. If the last element is a radio button or checkbox, it will be appended after the first sibling of the radio button or checkbox, which is expected to be the label for the radio button or checkbox. If there is already a guard error message there, it will be appended after the last guard error message (so guard messages show up in the proper order as they are specified).

Error message targeted with selector:

Error message targeted with function:

Error message inserted manually:

onGuardError

signature: guard.onGuardError(callback)

available since: 1.4.0

When a guard triggers an error, the callback provided to this function will be called with an event object. This event can also be captured by binding for jQuery events on the individual form fields with the "guardError" event.

If preventDefault() is called on the event, then the error will be prevented. If stopPropagation() or stopImmediatePropagation() is called on the event, then no other event handlers will receive the event (including jQuery event handlers).


Alerts on error.

onGuardFormError

signature: guard.onGuardFormError(callback)

available since: 1.4.0

When a guard triggers an error, the callback provided to this function will be called with an event object. This event can also be captured by binding for jQuery events on the top level form element with the "guardFormError" event.

If preventDefault() is called on the event, then the error will be prevented. If stopPropagation() or stopImmediatePropagation() is called on the event, then no other event handlers will receive the event (including jQuery event handlers).


Alerts on error.

onAfterGuardError

signature: guard.onAfterGuardError(callback)

available since: 1.4.0

When a guard triggers an error, the callback provided to this function will be called with an event object. This event can also be captured by binding for jQuery events on the individual form fields with the "afterGuardError" event. This event is triggered after the error has been applied, unlike the guardError and guardFormError events.

Calling preventDefault() has no effect. If stopPropagation() or stopImmediatePropagation() is called on the event, then no other event handlers will receive the event (including jQuery event handlers).


Alerts on error.

onAfterGuardFormError

signature: guard.onAfterGuardFormError(callback)

available since: 1.4.0

When a guard triggers an error, the callback provided to this function will be called with an event object. This event can also be captured by binding for jQuery events on the top level form element with the "afterGuardFormError" event. This event is triggered after the error has been applied, unlike the guardError and guardFormError events.

Calling preventDefault() has no effect. If stopPropagation() or stopImmediatePropagation() is called on the event, then no other event handlers will receive the event (including jQuery event handlers).


Alerts on error.

onClearGuardError

signature: guard.onClearGuardError(callback)

available since: 1.4.0

When a guard error is cleared, the callback provided to this function will be called with an event object. This event can also be captured by binding for jQuery events on the individual form fields with the "clearGuardError" event.

If preventDefault() is called on the event, then the error will not be cleared. If stopPropagation() or stopImmediatePropagation() is called on the event, then no other event handlers will receive the event (including jQuery event handlers).


Alerts when errors are cleared.

onClearGuardFormError

signature: guard.onClearGuardFormError(callback)

available since: 1.4.0

When a guard error is cleared, the callback provided to this function will be called with an event object. This event can also be captured by binding for jQuery events on the top level form element with the "clearGuardFormError" event.

If preventDefault() is called on the event, then the error will not be cleared. If stopPropagation() or stopImmediatePropagation() is called on the event, then no other event handlers will receive the event (including jQuery event handlers).


Alerts when errors are cleared.

onAfterClearGuardError

signature: guard.onAfterClearGuardError(callback)

available since: 1.4.0

When a guard error is cleared, the callback provided to this function will be called with an event object. This event can also be captured by binding for jQuery events on the individual form fields with the "afterClearGuardError" event. This event is triggered after the error has been cleared, unlike the clearGuardError and clearGuardFormError events.

Calling preventDefault() has no effect. If stopPropagation() or stopImmediatePropagation() is called on the event, then no other event handlers will receive the event (including jQuery event handlers).


Alerts when errors are cleared.

onAfterClearGuardFormError

signature: guard.onAfterClearGuardFormError(callback)

available since: 1.4.0

When a guard error is cleared, the callback provided to this function will be called with an event object. This event can also be captured by binding for jQuery events on the top level form element with the "afterClearGuardFormError" event. This event is triggered after the error has been cleared, unlike the clearGuardError and clearGuardFormError events.

Calling preventDefault() has no effect. If stopPropagation() or stopImmediatePropagation() is called on the event, then no other event handlers will receive the event (including jQuery event handlers).


Alerts when errors are cleared.

triggerError

signature: guard.triggerError([selector])

available since: 1.0.0

Exlicitly trigger an error for this guard on all elements provided to this function. The argument provided is wrapped as a jQuery object, so it may be a selector, jQuery object, element, or array of elements (or anything valid for a jQuery object). Note that the elements provided will have the guard applied, regardless of whether they match the guard selector.

This method may alternatively be invoked with no arguments. If this is done, the selector used with the guard is used to select the elents to trigger the guard error.


Triggered with a different selector


Triggered using the guard's selector