Forms form.js

Examples

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.

Populate a form

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.

{% highlight html %}
{% endhighlight %}

Use a form with multiple objects

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 List.js stores each item's data on it's rendered element, you're able to link forms to lists without JavaScript.

Use a form with a List

Specify data-source="ac.list.item" on a trigger element within a List.js item to populate a form with that item's data.

{% highlight html %}{% endhighlight %}
ID Name
{% highlight html %}
ID Name
{% endhighlight %}

Update source objects from the form

Submitting a form doesn't do anything

You must hook into the submitted.ac.form event to update your associated record on a server and / or your local copy of that object.

{% highlight js %} $('#myForm').on('submitted.ac.form', function(e) { $.post(myUrl, e.object); }); {% endhighlight %}

Update objects from List.js

When you update an object from an List.js list, you'll want to make sure the changes you've made are persisted to the list, and that those changes are rendered. Call the update method on the index to update the data for that item.

{% highlight js %}$('#myIndex').index('update', itemElement, newData);{% endhighlight %}
ID Name
{% highlight html %} {% endhighlight %}

Usage

Via data attributes

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.

{% highlight html %}
...
{% endhighlight %}

Via JavaScript

Or call the .form() method on the form element. Events triggered on the form will be triggered against this element.

{% highlight js %} $('#myForm').form(options); $('#myForm').on('submitted.ac.form', function(e) { ... }); {% endhighlight %}

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-items="".

The form element

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.

Form triggers

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.

Stored data

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.

Methods

.form('show', object)

Deserializes the passed object into the form's input fields.

{% highlight js %}$('#myForm').form('show', {"id": 1}){% endhighlight %}

.form('validate')

Trigger a browser-level validation of the form. If any errors are detected, the browser's default validation UI will alert the user. Triggers validated.ac.form event with the result.

{% highlight js %}$('#myForm').form('validate'){% endhighlight %}

Events

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 property of the event.
shown.ac.form 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.
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.
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.
submitted.ac.form 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.
{% highlight js %} $('#myForm').on('submitted.ac.form', function (e) { // do something... }) {% endhighlight %}