Form.js takes an existing <form>
element and adds useful event hooks for submitting, serialization / deserialization and validation.
The native submit behavior of the form is not affected by default, and you can use Form.js to populate and serialize form data, but continue to submit the data normally.
If you want to handle the submit yourself, you can disable the native submit behavior, and add a hook for your own code.
You can disable submit by listening to the submit
event on the form:
A shortcut to this is using the action
option over the data or JavaScript APIs:
Any page element with a data-toggle="form"
attribute can populate a form. For example, if you have a form that can edit any item in a list, you can add each item's data into it's container element's data-serialized
attribute. This attribute is checked by default for data to populate the form.
You can also use a different data attribute other than serialized, by specifying data-source="string"
. Because List.js stores each item's data as ac.list.item
on it's rendered element, you're able to link forms to lists without JavaScript.
Specify data-source="ac.list.item"
on a trigger element within a List.js item to populate a form with that item's data.
ID | Name |
---|
ID | Name |
---|
By default, submitting a form will cause the form's native submit action to fire, changing the page. Use the action=false
option on the form to disable the default action.
You can then hook into the submit.ac.form
event to update your associated record on a server and / or your local copy of that object.
When you update an object from an List.js list, you'll want to make sure the changes you've made are A) persisted to the list, and B) rendered. Call the update
method on the index to update the data for that item.
ID | Name | Select | Sel. Mul. | Toggle | Choice |
---|
Form.js encourages you to stay as close to the HTML5 Constraint validation spec as possible. That means using input validation attributes wherever possible (such as adding required
to note a required field) and using the browser's built-in validation feedback.
We've tried to make the functionality that Form.js adds follow the same rules that the browser's default behavior does. Additional functionality follows the same patterns. This includes:
submit.ac.form
events are triggered.novalidate
to the form element.e.preventDefault()
on the form's invalid.ac.form
event, instead of doing so on the individual fields.Form.js adds progressive enhancement by letting you use either the default validation feedback (the browser's native UI and default error messages), or a custom UI or content without changing when the validation occurs.
You should customize the validation of individual fields by adding change event handlers to the field in question, and calling .setCustomValidity()
on the field, with a blank string for a valid field, and an error message for an invalid field.
If you wish to use custom display logic for individual fields, you should intercept the invalid
event on the field and render your markup, optionally calling e.preventDefault()
to prevent the default UI from displaying.
Form-wide error messages should be displayed using the invalid.ac.form
event.
Trigger changes to a form without writing any JavaScript. Set data-control="form"
on your form element, and on a second trigger element, specify the data-toggle
, data-target
and data-serialized
(or data-source
) attributes.
Or call the .form()
method on the form element. Events triggered on the form will be triggered against this element.
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-
, as in data-items=""
.
Name | type | default | description |
---|---|---|---|
serialized | native or serialized object | Populate the form with these attributes on instantiation. | |
show | boolean | true | Renders the Form when initialized. Requires the serialized option to be passed as well. |
Name | type | default | description |
---|---|---|---|
serialized | native or serialized object | Populate the form with these attributes when trigger fires. | |
source | strong | serialized | When the event fires, Form.js must find the data to populate the form with. It will look in trigger element's data using this key. So by default the trigger element will use any data at data-serialized="" . If no data with that key is found on the trigger element, it will look up through the elements parents until it finds one. |
When you display data in a form using the data-api, several helper references are added to the form element. They are there to help you find where the data you're editing came from.
$('#myForm').data('ac.form.sourceElement')
returns the element the source data was stored on.
$('#myForm').data('ac.form.sourceData')
returns the source data that was deserialized into the form.
Deserializes the passed object into the form's input fields.
{% highlight js %}$('#myForm').form('show', {"id": 1}){% endhighlight %}Trigger validation of the form. If any errors are detected, either the browser's default validation UI or your custom events will alert the user. Triggers validated.ac.form
event with the result, and invalid.ac.form
if the form is invalid.
Event Type | Description |
---|---|
show.ac.form | This event is fired immediately when the show instance method has been called. The serialized data to be displayed is available as the serialized.array and serialized.object properties of the event. If the form was triggered via a button, that button will be available as relatedTarget . Call .preventDefault() on the event to stop showing the data. |
shown.ac.form | This event is fired when the serialized data has been inserted into the form. The data is available as the serialized.array and serialized.object properties of the event. If the form was triggered via a button, that button will be available as relatedTarget , the element containing that data is sourceElement , and a reference to the data itself is sourceData . |
validate.ac.form | This event is fired immediately when the validate instance method has been called. The current serialized values in the form are available through the object and array properties of the event. Call .preventDefault() on the event to stop validation. |
invalid.ac.form | This event is fired during attempted submission if the form is not valid. Use this event to display custom validation notices that apply to the form overall. Messages for individual fields should be applied using the invalid event on individual input elements. |
validated.ac.form | This event is fired when the form validation has completed. If any errors were detected, they will have been displayed to the user by this point. The validity of the form is available as the isValid property of the event. |
submit.ac.form | This data is fired when the form has passed validation. It takes place before a native form submit may occur. The form data is available in two ways: serialized into an object as the object property of the event, and as a raw array of input fields as array . |