UberForm
Uber form is a library with the purpose of making form submission a breeze. It provides a simple way to validate and submit forms without needing to give up control when you need it. This is achieved with a set of form events, and set of customizable options with sensible defaults. It also integrates with jQuery if available on the page.
Hello
uberFormel;
Or with jQuery
var $hello = ; $hello;
Creating an Uber Form
There are a few ways to create uber forms; with a form attribute, using the UberForm constructor, and with the uberForm jQuery method.
To create an uber form automatically with simply add the attribute data-uber-form
. On DOM ready uberForm will search for form elements with the data-uber-form
attribute and automatically initialize and instance of uber form upon the element in question. Note that this behavior can be changed by changing the selector used to search for forms. The selector is set on UberForm.formSelector
.
<!-- This form will automatically be setup as an uber form --> ...
Uber forms can also be initialized manually. This is the recommended way to setup uber forms if you need to set custom options, and you aren't using jQuery. Simply pass the form element you wish to turn into an uber form to the UberForm constructor.
// This will setup a form element as an uber formvar myForm = document;var uberForm = myForm /* opts */;
If you are using jQuery the same can be achieved as follows.
;
Capturing Uber Form Events
One of the main reasons you may wish to use uber form is to handle the validation for your form fields. Uber form has built in validation, however it's extremely easy to add your own to any field.
var secretField = uberForm;secretField;
Or with jQuery
var $myField = ;$myField;
Documentation
All you need to how about the UberForm API is below.
UberForm
Creates a new uber from instance for a given form element. It will also attach itself to the form element as a property called uberForm.
HTMLFormElement el Object options UberForm uberForm // Attaches the instance to the elementeluberForm UberForm uberForm options String bodyFormat ||= UberFormbodyFormat String formClass ||= UberFormformClass String formErrorClass ||= UberFormformErrorClass String fieldGroupErrorClass ||= UberFormfieldGroupErrorClass String fieldErrorClass ||= UberFormfieldErrorClass String formErrorsSelector ||= UberFormformErrorsSelector String fieldGroupSelector ||= UberFormfieldGroupSelector String fieldErrorsSelector ||= UberFormfieldErrorsSelector String formMethodAttribute ||= UberFormformMethodAttribute String formActionAttribute ||= UberFormformActionAttribute String formTargetAttribute ||= UberFormformTargetAttribute String formNoValidateAttribute ||= UberFormformNoValidateAttribute String errorsContainerTemplate ||= UberFormerrorsContainerTemplate String errorTemplate ||= UberFormerrorTemplate Function errorFormatter ||= UberFormerrorFormatter
Uber Form Events
Uber form implements a set of events emitted from form elements that have been passed to the UberForm constructor. These events are meant to allow for control over form validation and submission.
'uber:validate'
Fired from uber form elements prior to validation. You may want to check for errors that are dependent on multiple fields here. It is recommended you listen for a specific field with the uber:validate:[fieldName]
event instead if you want to check a single field. Calling preventDefault will stop submission, and validation will not complete.
formEl undefined e Function // Prevents the form from validating HTMLFormElement target // The form element
'uber:validate:[fieldName]'
Fired from uber form elements prior to validation. This is where you should validate individual fields. Calling preventDefault will stop submission, and validation will not complete. Note that you need to replace [fieldName] with the name of the field you wish to target.
formEl undefined e Function // Prevents the form from validating HTMLFormElement target // The form element
'uber:validate:*'
Fired from uber form elements prior to validation. This event will fire for every field element that has a name in your uber form. Calling preventDefault will stop submission, and validation will not complete.
formEl undefined e Function // Prevents the form from validating HTMLFormElement target // The form element
'uber:submit'
Fired from uber form elements after validation, prior to submission. If you need to block form submission for any reason this is the recommended event to block on. Calling preventDefault will stop submission.
formEl undefined e Function // Prevents the form from submitting HTMLFormElement target // The form element
'uber:submit:[fieldName]'
Fired from uber form elements after validation, prior to submission. If you need to block form submission for any reason, related to a given field, this is the recommended event to block on. Calling preventDefault will stop submission. Note that you need to replace [fieldName] with the name of the field you wish to target.
formEl undefined e Function // Prevents the form from submitting HTMLFormElement target // The form element
'uber:submit:*'
Fired from uber form elements after validation, prior to submission. If you need to block form submission for any reason, related to one of any of the fields contained, this is the recommended event to block on. Calling preventDefault will stop submission.
formEl undefined e Function // Prevents the form from submitting HTMLFormElement target // The form element
'uber:abort'
Indicates form submission was aborted. Fired after either validate or submit events. If e.preventDefault is called during validation then it will fire after validate events have fired. If e.preventDefault is called during submission then it will fire after the submit event
formEl undefined e HTMLFormElement target // The form element
'uber:success'
Fired from uber form elements after the data has been successfully sent to the server.
formEl undefined e String body // is a string with text responses Object body // is object if responseType is json null error // always null in success XMLHttpRequest xhr // the xhr object used to make the request HTMLFormElement target // The form element
'uber:error'
Fired from uber form elements in the event of an error during submission to the server.
formEl undefined e String body // is a string with text responses Object body // is object if responseType is json Error error // an error object describing the error XMLHttpRequest xhr // the xhr object used to make the request HTMLFormElement target // The form element
Uber Form Field Element Events
Field elements within an uber form element also implement a set of events. It is recommended you use the form element events, but these are provided for ease of use.
'uber:validate'
Fired from field elements after validation, prior to submission. Calling preventDefault will stop submission.
fieldEl undefined e Function // Prevents the form from validating HTMLElement target // The field element
'uber:submit'
Fired from field elements after validation, prior to submission. Calling preventDefault will stop submission.
fieldEl undefined e Function // Prevents the form from submitting HTMLElement target // The field element
UberForm.init
Runs automatically upon when the DOM is ready. Crawls the given document or element for all forms matching the given selector. It then creates an UberForm instance for each.
UberForm undefinedUberForm undefined formSelector ||= UberFormformSelector
UberForm.bindJQuery
Adds methods to jQuery selections for creating and working with UberForm instances. See 'jQuery Selection Methods' below for documentation.
UberForm
UberForm[optionName]
If you wish to change default options they are available on the UberForm constructor. Changing these values with change the defaults for any new UberForm instances created.
String UberFormbodyFormat ||= 'url-encoded'String UberFormformClass ||= 'uber-form'String UberFormformErrorClass ||= 'uber-form-error'String UberFormfieldGroupErrorClass ||= 'uber-form-field-group-error'String UberFormfieldErrorClass ||= 'uber-form-field-error'String UberFormformSelector ||= 'form[data-uber-form]'String UberFormformErrorsSelector ||= '[data-uber-form-errors]'String UberFormfieldGroupSelector ||= '[data-uber-form-field-group]'String UberFormfieldErrorsSelector ||= '[data-uber-form-field-errors]'String UberFormformMethodAttribute ||= 'method'String UberFormformActionAttribute ||= 'action'String UberFormformTargetAttribute ||= 'target'String UberFormformNoValidateAttribute ||= 'data-uber-form-novalidate'String UberFormfieldTypeAttribute ||= 'type'String UberFormerrorsContainerTemplate ||= '<div class="uber-form-error-messages">{{errors}}</div>'String UberFormerrorTemplate ||= '<div class="uber-form-error-message">{{errorMessage}}</div>'Function UberForm ||= => String errorHTML
UberForm#[optionName]
If you wish to access or modify any options on an UberForm instance they are available directly on the instance itself as properties. Changing these values will directly effect the instance behavior.
String uberFormbodyFormat ||= UberFormbodyFormatString uberFormformClass ||= UberFormformClassString uberFormformErrorClass ||= UberFormformErrorClassString uberFormfieldGroupErrorClass ||= UberFormfieldGroupErrorClassString uberFormfieldErrorClass ||= UberFormfieldErrorClassString uberFormformErrorsSelector ||= UberFormformErrorsSelectorString uberFormfieldGroupSelector ||= UberFormfieldGroupSelectorString uberFormfieldErrorsSelector ||= UberFormfieldErrorsSelectorString uberFormformMethodAttribute ||= UberFormformMethodAttributeString uberFormformActionAttribute ||= UberFormformActionAttributeString uberFormformTargetAttribute ||= UberFormformTargetAttributeString uberFormformNoValidateAttribute ||= UberFormformNoValidateAttributeString uberFormerrorsContainerTemplate ||= UberFormerrorsContainerTemplateString uberFormerrorTemplate ||= UberFormerrorTemplateFunction uberFormerrorFormatter ||= UberFormerrorFormatter
UberForm#el
If you wish to access the form element the UberForm instance is bound to it is available via the el property. Changing the value of this property is not recommended.
HTMLFormElement uberFormel
UberForm#submit
Submits the form to the server. If you want to submit your form programmatically you should call this method.
UberForm undefined
UberForm#filter
Registers a filter function for modifying data before it's sent to the server.
UberForm undefined
UberForm#removeFilter
Removes a filter function for modifing data before it's sent to the server.
UberForm undefined
UberForm#setError
Applies custom errors to a field by name.
uberForm undefineduberForm undefined
UberForm#clearErrors
Clears errors on a specific field, or all errors on the form.
uberForm undefined
UberForm#showErrors
Shows errors for the form.
uberForm undefined
UberForm#hideErrors
Hides errors for the form.
uberForm undefined
UberForm#getFieldElements
Gets a all field elements. Only field elements with a name attribute are included.
uberForm HTMLElement fieldElements
UberForm#getFieldElement
Gets a field element by name.
uberForm HTMLElement fieldElement
UberForm#serialize
Serializes the form data, returning it in either as a url-encoded string an object. The format can be 'url-encoded'
or 'json'
.
uberForm String urlEncodedDatauberForm Object formData
UberForm#toObject, UberForm#toJSON
Returns an object containing the form's data
uberForm Object formData
jQuery Selection Methods
$selection.uberForm
Creates a new or modifies and existing uberForm instance on a form element contained within a jQuery selection.
$selection jQuerySelection $selection options String bodyFormat ||= UberFormbodyFormat String formClass ||= UberFormformClass String formErrorClass ||= UberFormformErrorClass String fieldGroupErrorClass ||= UberFormfieldGroupErrorClass String fieldErrorClass ||= UberFormfieldErrorClass String formErrorsSelector ||= UberFormformErrorsSelector String fieldGroupSelector ||= UberFormfieldGroupSelector String fieldErrorsSelector ||= UberFormfieldErrorsSelector String formMethodAttribute ||= UberFormformMethodAttribute String formActionAttribute ||= UberFormformActionAttribute String formTargetAttribute ||= UberFormformTargetAttribute String formNoValidateAttribute ||= UberFormformNoValidateAttribute String fieldTypeAttribute ||= UberFormfieldTypeAttribute
$selection.uberFormSubmit
Submits the form to the server. You should call this method if you want to submit your form programmatically.
$selection jQuerySelection $selection
$selection.uberFormSetError
Sets errors on uber form fields. If called on a selection containing an uber form, a fieldName must be given. If called on a selection containing a field element from within an uber form element, the fieldName can be omitted.
// $selection containing a form element$selection jQuerySelection $selection$selection jQuerySelection $selection // $selection containing a form field element$selection jQuerySelection $selection
$selection.uberFormClearErrors
Clears errors from uber form fields. If called on a selection containing an uber form, a field name can be passed. If a field name is given then only errors for the that field will be cleared. Otherwise all errors for the form are cleared. If called on a selection containing a field element from within an uber form element, the fieldName can be omitted.
// $selection containing a form element$selection jQuerySelection $selection$selection jQuerySelection $selection // $selection containing a form field element$selection jQuerySelection $selection
$selection.uberFormShowErrors
Shows errors on uber form fields. Must be called on a a selection containing a uber form element.
// $selection containing a form element$selection jQuerySelection $selection
$selection.uberFormHideErrors
Hides errors on uber form fields. Must be called on a a selection containing a uber form element.
// $selection containing a form element$selection jQuerySelection $selection
$selection.uberFormGetField
Gets a field element from an uber form.
// $selection containing a form element$selection jQuerySelection $field
$selection.uberFormGetFields
Gets all field elements from an uber form.
// $selection containing a form element$selection jQuerySelection $fields
$selection.uberFormSerialize
Serializes the form data, returning it in either as a url-encoded string an object. The format can be 'url-encoded'
or 'json'
.
$selection String urlEncodedData$selection Object formData