Form prefill plugin for jQuery

Built by more onion as a part of Campaignion.

Installation

Pull in jquery.formprefill.js after jQuery. Promises have to be polyfilled for IE.

Usage

Call formPrefill() on the form. If values for any fields are present in one of the stores, the fields are prefilled with the corresponding values. You can pass an options object (see below).

$('form').formPrefill();

For each field that you want to prefill or save you have to set the keys in the markup:

<!-- This will read from and write to the first_name key: --> <input type="text" data-form-prefill-keys="first_name">  <!-- You can specify multiple keys separated by spaces: --> <input type="text" data-form-prefill-keys="first_name firstname name">  <!-- You can set different keys to read from and to write to: --> <input type="text" data-form-prefill-read="first_name firstname" data-form-prefill-write="first_name">  <!-- If the data attributes are omitted the keys are parsed from the name attribute, using the last term in brackets by default. --> <input type="text" name="person[first_name]"> <input type="text" name="first_name">

In case you’re not in control of the markup, you can pass custom logic to set the keys for a field:

$('form').formPrefill({   storageKeys: function($element) {     // Guess the keys from $element...     return {       read: "first_name",       write: "first_name"     };   }, });

API

The form’s API is accesible via $('form').data('formPrefill').

// Prefill all fields that have values saved in the stores (this is done automatically when you call the plugin on a form): $('form').data('formPrefill').readAll();  // Write values to the stores for each field in the form: // Use this with caution: Depending on your exclusions this will also include unchanged default values // and hidden-fields used internally by your backend (ie. form tokens). $('form').data('formPrefill').writeAll();  // Clear values from the stores for each field in the form and reset their values to what they were when the plugin was initialized: $('form').data('formPrefill').removeAll();  // Clear each field’s values from the stores, leave the current field values untouched: $('form').data('formPrefill').removeAll({resetFields: false});

Each field exposes an own API: $('form').find('input[name=first_name]').data('formPrefill')

var $firstName = $('form').find('input[name=first_name]');  // Read this field’s value from the stores and fill the field in: $firstName.data('formPrefill').read();  // Write this field’s value to the stores. When called on a checkbox or radio, all checkboxes/radios that have the same keys in their data-form-prefill-write attribute are considered one set of fields. $firstName.data('formPrefill').write();  // Clear this field’s value from the stores: $firstName.data('formPrefill').write({delete: true});

Each of the field API methods returns a Promise.

Populate the stores via url hash

You can pass values in the url’s hash as follows: The hash can be splitted in segments divided by ;, every segment containing values prefixed with p: will be parsed and stripped from the hash. The values are saved into the stores and any corresponfing form fields are filled in. Hash examples:

• Field values are separated with ampersands: #p:first_name=Jane&last_name=Doe
• Pass mulitple values for the same property to populate sets of checkboxes: #p:likes=cats&likes=dogs will result in the checkboxes with value="cats" and value=dogs checked.
• Other parts of the hash remain untouched: #anchor;p:first_name=Jane

Options

Events

By default, the stores are updated when fields fire the change event. You can remove these handlers: $('form').find('*').off('.form-prefill').

When the plugin populates a field, it fires form-prefill:prefilled on the field. When it fails to retrieve a value for a field, it fires form-prefill:failed on the field, providing the cause as the second argument to the handler function. These events bubbles up.

When you call removeAll() on the form’s API, form-prefill:cleared is fired on the form.