Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/moreonion/formprefill
Prefill forms based on URL-parameters, cookies or the sessionStore.
https://github.com/moreonion/formprefill
Last synced: about 1 month ago
JSON representation
Prefill forms based on URL-parameters, cookies or the sessionStore.
- Host: GitHub
- URL: https://github.com/moreonion/formprefill
- Owner: moreonion
- License: lgpl-3.0
- Created: 2017-03-09T07:47:28.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2023-01-09T05:58:37.000Z (almost 2 years ago)
- Last Synced: 2024-11-14T01:03:16.547Z (about 2 months ago)
- Language: JavaScript
- Homepage:
- Size: 475 KB
- Stars: 5
- Watchers: 7
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Form prefill plugin for jQuery
Built by [more onion](https://www.more-onion.com) as a part of [Campaignion](https://www.campaignion.org).
## Installation
```javascript
import { formPrefill } from "path/to/formprefill.min.js";
```
Note: Promises and other ES6 features might need polyfilling 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).
```javascript
formPrefill(document.querySelector('form'));
```
For each field that you want to prefill or save you have to set the keys in the markup:
```html
```
In case you’re not in control of the markup, you can pass custom logic to set the keys for a field:
```javascript
formPrefill(document.querySelector('form'), {
storageKeys: function($element) {
// Guess the keys from $element...
return {
read: "first_name",
write: "first_name"
};
},
});
```
## API
The form’s API is accesible via the return value of `formPrefill(form)`.
```javascript
// Prefill all fields that have values saved in the stores (this is done automatically when you call the plugin on a form):
let api = formPrefill(document.querySelector('form'))
api.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).
api.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:
api.removeAll()
// Clear each field’s values from the stores, leave the current field values untouched:
api.removeAll({resetFields: false})
```
Each field exposes its own API object in the `apiRegistry`: `apiRegistry.get(form.querySelector('input[name=first_name]'))`
```javascript
let firstName = form.querySelector('input[name=first_name]')
// Read this field’s value from the stores and fill the field in:
apiRegistry.get(firstName).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.
apiRegistry.get(firstName).write();
// Clear this field’s value from the stores:
apiRegistry.get(firstName).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
| Option | Type | Default | Description |
|-------------------|----------|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `prefix` | String | `formPrefill` | All entries in the stores are prefixed with this. |
| `storageKeys` | Function | | A function that sets the storage keys for a given field (passed in as a jQuery object). The function must return an object with a `read` and a `write` key. |
| `map` | Object | `{}` | A map of aliases that are used when looking up keys in the stores. In the case of `{'first_name': ['firstname', 'firstName', 'fname']}`, a field with the attribute `data-form-prefill-keys="first_name"` gets prefilled from the `firstName` entry in any of the stores if neither a `first_name` nor a `firstname` entry exist. |
| `exclude` | String | `[data-form-prefill-exclude]` | Selector for fields or containers in the form that should be excluded from prefilling. |
| `include` | String | `[data-form-prefill-include]` | Selector for fields or containers inside excluded containers that should be included nevertheless. |
| `stringPrefix` | String | `s` | Entries in the stores describing strings are prefixed with this string. |
| `listPrefix` | String | `l` | Entries in the stores describing lists are prefixed with this string. |
| `stores` | Array | `['sessionStorage']` | An array of custom store instances or names of predefined stores. A store instance has to expose a `setItems`, a `removeItems`, and a `getFirst` method, each of which should return a Promise. This way your store could make an XHR request, resolving the promise and thus prefilling the form only when the data arrives. Pre-defined stores are: `cookie`, `sessionStorage` and `localStorage` |
| `cookieDomain` | String | `''` | The domain from which cookies can be accessed. Defaults to the current domain, not including (other) subdomains. |
## Events
By default, the stores are updated when fields fire the `change` event.
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.
## Running the tests
The test-suite is written using Qunit. You can run it by starting a development server (eg. using `php -S localhost:8000`) and then navigating to `qunit.html` (http://localhost:8000/tests/qunit.html).