Memoria
=======
**Demo:** http://wildhoney.io/memoria/example
Memoria is an extensible form storage for memorising user inputs. Never again will you lose form data!
Install via npm: `npm install memoria-js`
Implementation
-------
Although Memoria is zero configuration, there are a few requirements to get it working using native `input` fields.
* All `form` containers must have a unique `name` attribute per website;
* All `input`/`select`/`textarea` fields must have a unique `name`/`data-memoria-name` attribute per form;
* All `input` fields with `type` of `radio` must be implemented specially.
* All custom input fields must be implemented using the provided hooks.
Unit Tests
-------
All of the unit tests for Memoria are written in Jasmine and can be run with `grunt test`.
Contributions
-------
You're more than welcome to contribute to the Memoria project! Please include unit tests and it'll be more than happily merged in.
Clearing Storage
-------
Since a form submission is no guarantee that the form data was received successfully, Memoria leaves it entirely up to you to clear the stored form data.
Simply invoke `memoria.clear('form-name');` on your form submission, AJAX request `onSuccess` handler, etc... once you're sure the data has been safely received.
```javascript
onSuccess: function(response) {
if (response.valid) {
memoria.clear('contact-form');
}
}
```
Overloading Event Name
-------
Memoria allows for each supported input type to overload the default event name.
For example, on an `input` field that is of `type` text, the default event is `onkeyup`. However, by adding the `data-memoria-event="onclick"` attribute to the `input` node, the `_save` method is now invoked on the `onclick` event instead of `onkeyup`.
```html
```
Problem of Radio Inputs
-------
Since `input` elements with the type `radio` have the same names, they are indistinguishable from one another, which makes it problematic to pinpoint which one the value should be applied to. However, Memoria overcomes this by allowing you to specify a custom name for all of your nodes – for the most part this should be avoided, because the `name` attribute will suffice, but on `radio` inputs it is a must! Simply add the `data-memoria-name` attribute to each `radio` `input` and ensure their names are unique.
```html
```
Ignoring Inputs
-------
By default Memoria will attempt to find all `input`, `select`, `textarea` fields. However, sometimes you not want a particular node to use Memoria. For this you can simply define the `data-memoria-ignore` attribute on any node.
```html
```
HTML5 Input Fields
-------
Memoria supports all HTML5 input fields – the Baker's Dozen as they're endearingly known. As with all native `input` fields, there is zero configuration and they will all work out-of-the-box.
```html
```
HTML5 inputs are: `color`, `date`, `datetime`, `datetime-local`, `email`, `month`, `number`, `range`, `search`, `tel`, `time`, `url` and `week`!
Custom Nodes
-------
By default, Memoria supports all default `input` elements. However, what if you're using a custom JavaScript dropdown? What then? Luckily you're able to indicate a form input by applying the `data-memoria-input` attribute with a value – the value will be used to load your custom delegator object.
```html
Male
Female
```
From the above code – as seen in example/index.html, Memoria will be looking for an `object` called `Memoria.Observer.Choice`.
* `data-memoria-input` – name of the delegator class to handle the callbacks;
* `data-memoria-event` – on which event(s) to respond to the element;
* `data-memoria-name` – name of the input for when it's stored in `localStorage`;
If it's necessary, you can also specify multiple events with `data-memoria-event` by separating them with a comma – don't worry about whitespace, Memoria will trim that for you.
```html
Male
Female
```
Memoria provides two callbacks:
* `setupElement` – invoked when `localStorage` has found a value pertaining to the current custom element (`data-memoria-name`). Should be used to setup your element visually based on the saved value;
* `eventFired` – invoked when the user triggers the event (`data-memoria-event`). Should be used to return the value you wish to save in `localStorage`;
For an example of a custom element, please refer to `Memoria.Observer.MultipleSelect`.
