For all their complexity, the function forms serve in admins is often very repetitive. Form.js takes an existing <form>
element and adds useful events hooks for serialization, deserialization and submitting.
Most forms are fairly simple, and can be expressed with a serialized JSON object. Form.js lets you populate forms based on that JSON. This comes in handy when you have multiple items on a page that you may want to edit. Instead of rendering the form dynamically for each one, or populating the fields manually in JavaScript, you can populate the form automatically based on a source object.
Forms are most useful when they are associated with a collection of items, for example a form that can edit any item in a list.
It uses the data available at the trigger's data-serialized
attribute by default, but you can override that with any data attribute key. Because Index.js stores each item's data on it's rendered element, you're able to link forms to lists without JavaScript.
Specify data-source="adcom.index.item"
on a trigger element within an Index.js item to populate a form with that item's data.
ID | Name |
---|
ID | Name |
---|
You must hook into the submitted.adcom.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 Index.js list, you'll want to make sure the changes you've made are persisted to the index, and that those changes are rendered. Trigger the update.adcom.index
event on the item's container element to do so:
ID | Name |
---|
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
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. |
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('adcom.form.sourceElement')
returns the element the source data was stored on.
$('#myForm').data('adcom.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 %}Event Type | Description |
---|---|
show.adcom.index | This event is fired immediately when the show instance method has been called. The serialized data to be displayed is available as the serialized property of the event. |
shown.adcom.index | This event is fired when the serialized data has been inserted into the form. The data is available as the serialized property of the event. |
submitted.adcom.index | This data is fired when the form has been submitted. data-control="form" must be present on the form element in order for Form.js to override the default submit handling of the form and fire this event instead. 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 . |