MooTools Formular

MooTools FormCheck + Form.Validator = Formular

Last Updated

This page was last updated on July 28th 2011 and was first published on May 19th 2011

On one hand you have the MooTools FormCheck plugin, which is a useful plugin for inline form validation by offering a validation experience that is different from most other plugins/tools. The major feature is that the plugin provides fancy scalable tooltips that provide detail about the exact input field where the validation failed. Despite providing tons of functionality, the plugin functionality itself is difficult to extend.

The Form.Validator plugin on the other hand (found in the MooTools more library) provides a lot of useful methods and functions for extending form validation. There is also a Form.Validator.Inline plugin which provides useful inline form input validation (much like FormCheck) but is also very difficult to extend or customize.

Formular … The best of both worlds

Luckily, the MooTools Formular.js plugin offers the sleek and trendy features of FormCheck mixed in with the robust features of the MooTools Form.Validator plugin.

Features

All the existing validation features provided by the MooTools Form.Validator plugin
Fancy inline field validation with errorBox tool tips
Six tooltip themes to choose from
Field error animations
Enable / Disable Form Fields and Buttons

How it Works

Simple, it extends the Form.Validator class and uses the graphics and implements the features that the MooTools FormCheck plugin offers.

Once applied to a form, you can set a theme to create really crisp and effective looking form validation error boxes:


	Awesome Tool Tips!


	Create error tool tips with Formular


	Sweet ToolTips!!!


	Scalable tool tips work effectively


	Six awesome themes to choose from!


	All themes provided from the MooTools FormCheck plugin

To Top Demos Download

Requirements

- MooTools 1.3 Core
- MooTools 1.3 More (Form.Validator, Fx.Scroll)

To Top Demos Download

Usage

window.addEvent('domready',function() {
  new Formular('form',{
    //options
  });
});

To Top Demos Download

Options & Events

All the existing options from Form.Validator plus the following options listed below:

Option	Value	Description
theme	String (default = ‘red’).	This string acts as the theme for the errorBox elements within the form. Theme options include red, blue, black, green
tipOffset	Object (x : number, y : number).	Acts as the offset value for the errorBox element.
fieldSelectors	String (used by Form.Validator … default = ‘.required’).	Acts as the CSS selector for finding the elements within the form that will be processed in the validation.
allFieldSelectors	String (default = ‘input[type="text"],textarea,select’).	Acts as the CSS selector for finding the all the input elements within the form.
errorClassName	String (default = ‘formular-inline’).	The className value that will be applied to each of the errorBox tips.
disableClassName	String (default = ‘disabled’)	The className value that will be applied to each input field when the disableFields() method is executed.
warningPrefix	String (default=’There was an error:’)	The prefix string that will be applied to every errorBox before the error message.
submitFormOnSuccess	Boolean (default = true)	Whether or not the form will be submitted automatically when the validation is successful.
disableFieldsOnSuccess	Boolean (default = true)	Whether or not the form the disableFields() method will be called after the form is successfully validated (and/or submitted).
disableButtonsOnSuccess	Boolean (default = true)	Whether or not the form the disableButtons() method will be called after the form is successfully validated (and/or submitted).
inputEscapeKeyEvent	Boolean (default = true)	When an input field has an error and the cursor is focussed on the input field, if the user presses the ESC key then it will remove the errorBox.
repositionBoxesOnWindowResize	Boolean (default = true)	When the window is resized, the currently visible error boxes will be repositioned.
serial	Boolean (default = true)	Used in Form.Validator. This property ensures that the input fields are validated in serial order (so that if one fails the validation stops there).
oneErrorAtATime	Boolean (default = true)	Same idea as the serial property, however this ensures that no more than one errorBox is displayed at once.
scrollToFirstError	Boolean (default = true)	Whether or not to scroll the window to the first visible error when validation fails.
focusOnFirstError	Boolean (default = true)	Whether or not to focus on the first visible error input field when validation fails.
stopSubmissionRequestOnCancel	Boolean (default = true)	Stops the browser form submission if it has already started (this option does not apply to when formular does not submit the form after validation).
boxZIndex	Boolean (default = 1000)	The ZIndex value for the error boxes.
onBeforeSubmit	Event (no arguments)	This event is fired before validation is performed and when the form is submitted (only occurs if submitFormOnSuccess).
onAfterSubmit	Event (no arguments)	This event is fired after validation is successful and is only performed and when the form is submitted (only occurs if submitFormOnSuccess).
onSuccess	Event (no arguments)	This event is fired after validation is successful.
onFailure	Event (no arguments)	This event is fired if the validation itself fails at any time.
onFieldSuccess	Event (fieldElement, validatorsArray)	This event is fired when a field has been successfully validated.
onFieldFailure	Event (fieldElement)	This event is fired when a field has failed validations.
onFocus	Event (fieldElement)	This event is fired when a field is focussed upon (applies to the allFields selector).
onBlur	Event (fieldElement)	This event is fired when a field is blurred upon (applies to the allFields selector).

To Top Demos Download

Methods

The following methods are accessible in a formular instance and are provided as an extension from the Form.Validator base class

Method	Description
formular.setBoxZIndex(zIndex)	Sets the ZIndex for each of the error boxes (this also updates all the existing/visible error boxes if created).
formular.getBoxZIndex(zIndex)	Gets the current boxZIndex option for all the error boxes.
formular.setTheme(theme)	Sets the theme of the errorBox graphics. Theme options are outlined in the previous section.
formular.getTheme()	Returns the currently set theme for the errorBox tips.
formular.repositionBoxes()	Repositions all the boxes visible to their targetted input field (useful for when a window is resized or a form element is moved due to added content).
formular.getForm()	Returns the form that the vaildation is based on.
formular.getFields()	Returns all the fields that are selected/matched for validation based on the fieldSelectors selector string.
formular.getAllFields()	Returns all the fields in the form (even the ones that are not matched for validation).
formular.getButtons()	Returns all the buttons in the form (button elements, input button elements, submit and reset buttons)
formular.disableButtons()	Disables all buttons in the form (sets the HTML disabled attribute equal to 1).
formular.enableButtons()	Enables all buttons in the form.
formular.disableFields()	Disables ALL fields in the form (sets the HTML readonly attribute equal to 1 and adds a disabledClassName string to the className property of each field).
formular.enableFields()	Removes (enables) the disabled attribute values on all fields.
formular.validateField()	An overloaded method used from the Form.Validator plugin. This method will not validate a field if the options.oneErrorAtATime property is set to true and a visible error box already exists within the form.
formular.createErrorBox(inputField)	Private method used to create the errorBox element for the given inputField element that will display the error message.
formular.getErrorBox(inputField)	Private method used to return the errorBox for the given input field.
formular.getFirstVisibleErrorBox()	Returns the first error box that is visible within the form.
formular.setErrorBoxMessage(errorBox,message)	Private method for setting the error message for the given error box.
formular.positionErrorBox(errorBox,inputElement)	Private method for positioning the errorBox for the given inputElement.
formular.destroyAllBoxes()	Destroys (removes) all the created error boxes within the form (useful for resetting a form).
formular.showError(errorBox,message)	Reveals an errorBox and applies the given message as the errorBox’s error message.
formular.hideError(errorBox)	Hides the given errorBox.
formular.anyErrorBoxesVisible()	A boolean method which returns true if one or more of errorBoxes are visible (displayed) in the given form. In other words if an error exists.
formular.hideAllErrors()	Hides all the currently visible errorBoxes in the given form.
formular.scrollToFirstVisibleError()	Scrolls the window to the first visible error box.
formular.focusOnFirstVisibleError()	Sets the browser to focus on the first element that contains an error.
formular.validateFieldset(fieldset)	This method groups all of the inputs that exist within the given fieldset within the form that is being validated. The fieldset paramater may be a fieldset element, id of a fieldset within the form, or the name of the fieldset within the form. This method returns true if all of the input fields within the fieldset pass the validation
formular.validateFields(fields)	This method will validate all the fields provided one by one and return true if all of the fields were successfully validated. The fields parameter must be an array consisting of input field elements that exist within the form.
formular.isSubmitting()	Returns true if the form is validated and has started to submit its contents.
formular.submit()	An alias for formular.validate().
formular.cancel()	Stops the form submission (if on going) and resets the form errors and fields (this will enable all the fields if any of them are disabled).
formular.destroy()	Removes the formular instance from the form and destroys the form as well (useful for ajax applications).