Form
Form Data
Framework7 comes with some very useful methods, this makes working with forms as simple as possible:
Form Data App Methods
Using the following app methods we can easily convert all form fields values to data object and fill the form from data object:
app.form.convertToData(form)- convert form fields values to data object
- form - HTMLElement or string (with CSS Selector) of form that should be converted to data object. Required.
app.form.fillFromData(form, data)- fill up form according to data object
- form - HTMLElement or string (with CSS Selector) of form that should be converted to data object. Required.
- data - object with from data. Required.
Note that each input should have
name
attribute, otherwise its value will not be presented in data objectCheckboxes and "multiple" selects will be presented as Arrays
Form Data Events
Form data api will fire the following DOM events on form element and app instance:
DOM Events
Event | Target | Description |
---|---|---|
form:todata | Form Element<form> | Event will be triggered on form when calling app.form.convertToData |
form:fromdata | Form Element<form> | Event will be triggered on form when calling app.form.fillFromData |
App Events
Form Data api emit events on app instance as well:
Event | Target | Arguments | Description |
---|---|---|---|
formToData | app | (form, data) | Event will be triggered on app.form.convertToData call |
formFromData | app | (form, data) | Event will be triggered on app.form.fillFromData call |
Form Data Example
<form class="list" id="my-form">
<ul>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-title item-label">Name</div>
<div class="item-input-wrap">
<input type="text" name="name" placeholder="Your name">
</div>
</div>
</div>
</li>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-title item-label">E-mail</div>
<div class="item-input-wrap">
<input type="email" name="email" placeholder="E-mail">
</div>
</div>
</div>
</li>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-title item-label">Gender</div>
<div class="item-input-wrap">
<select name="gender">
<option value="male" selected>Male</option>
<option value="female">Female</option>
</select>
</div>
</div>
</div>
</li>
<li>
<div class="item-content">
<div class="item-inner">
<div class="item-title">Toggle</div>
<div class="item-after">
<label class="toggle toggle-init">
<input type="checkbox" name="toggle" value="yes"><i class="toggle-icon"></i>
</label>
</div>
</div>
</div>
</li>
</ul>
</form>
<div class="block block-strong row">
<div class="col"><a class="button convert-form-to-data" href="#">Get Data</a></div>
<div class="col"><a class="button fill-form-from-data" href="#">Fill Form</a></div>
</div>
var app = new Framework7();
var $$ = Dom7;
$$('.convert-form-to-data').on('click', function(){
var formData = app.form.convertToData('#my-form');
alert(JSON.stringify(formData));
});
$$('.fill-form-from-data').on('click', function(){
var formData = {
'name': 'John',
'email': '[email protected]',
'gender': 'female',
'toggle': ['yes'],
}
app.form.fillFromData('#my-form', formData);
});
Form Storage
With form storage it is easy to store and parse forms data automatically, especially on Ajax loaded pages. And the most interesting part is that when you load this page again Framework7 will parse this data and fill up all form fields automatically!
To enable form storage for specific form, all you need is:
- add
form-store-data
class to form - add
id
attribute to form. It will not work if form doesn't haveid
attribute - make sure that all you inputs have
name
attributes, otherwise they will be ignored
After form storage is enabled with form-store-data
class, then form data will be saved to localStorage
on every form input change.
To ignore inputs for storage you can add no-store-data
or ignore-store-data
class to required input elements.
Otherwise you can use the following app methods to store/get/remove stored form data:
Form Storage App Methods
app.form.getFormData(formId)- get form data for the form with specified id
attribute
- formId - string - "id" attribute of required form. Required.
app.form.storeFormData(formId, data)- store form data for the form with specified id
attribute
- formId - string - "id" attribute of required form. Required.
- data - object - JSON data to store
app.form.removeFormData(formId)- remove form data for the form with specified id
attribute
- formId - string - "id" attribute of required form. Required.
Form Storage Events
Form Storage api will fire the following DOM events on form element and app instance:
DOM Events
Event | Target | Description |
---|---|---|
form:storedata | Form Element<form> | Event will be triggered right after form data saved |
App Events
Form Storage api emit events on app instance as well:
Event | Target | Arguments | Description |
---|---|---|---|
formStoreData | app | (form, data) | Event will be triggered right after form data saved |
Form Storage Example
<form class="list form-store-data" id="my-form">
<ul>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-title item-label">Name</div>
<div class="item-input-wrap">
<input type="text" name="name" placeholder="Your name">
</div>
</div>
</div>
</li>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-title item-label">E-mail</div>
<div class="item-input-wrap">
<input type="email" name="email" placeholder="E-mail">
</div>
</div>
</div>
</li>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-title item-label">Ignore form storage</div>
<div class="item-input-wrap">
<input class="no-store-data" type="text" name="text" placeholder="This value won't be stored">
</div>
</div>
</div>
</li>
<li>
<div class="item-content item-input">
<div class="item-inner">
<div class="item-title item-label">Gender</div>
<div class="item-input-wrap">
<select name="gender">
<option value="male" selected>Male</option>
<option value="female">Female</option>
</select>
</div>
</div>
</div>
</li>
<li>
<div class="item-content">
<div class="item-inner">
<div class="item-title">Switch</div>
<div class="item-after">
<label class="toggle">
<input type="checkbox" name="switch" value="yes"><i class="toggle-icon"></i>
</label>
</div>
</div>
</div>
</li>
</ul>
</form>
Ajax Form Submit
Framework7 allows automatically send form data using Ajax.
It could be done in two ways
- when user submits it (when he clicks on "submit" button) or when "submit" event triggered on form programmatically
- when user change any form field or when "change" event triggered on form (or form field) programmatically
Send form data on submit
To enable Ajax form and send data automatically on submit, we just need to add form-ajax-submit
class to form:
<form action="send-here.html" method="GET" class="form-ajax-submit">
...
</form>
And when user will submit this form, it automatically will be sended using Ajax with the following rules:
Form data will be sended to the file/url specified in form's
action
attributeRequest method will be the same as specified in form's
method
attributeContent type will be the same as specified in form's
enctype
attribute. By default (if not specified), it isapplication/x-www-form-urlencoded
Send form data on input change
Mostly we don't use "submit" buttons in apps, so in this cases we need to submit form data when user changes any form fields. For this case we need to use form-ajax-submit-onchange
class:
<form action="send-here.html" method="GET" class="form-ajax-submit-onchange">
...
</form>
And when user will change any form filed, form data automatically will be sended using Ajax with the same rules as in previous case.
Ajax Form Submit Events
Sometimes we need to get actual XHR repsonse from the file/url where we send form data with Ajax. We can use special events for that:
Dom Events
Event | Target | Description |
---|---|---|
formajax:success | Form Element<form class="form-ajax-submit"> | Event will be triggered after successful Ajax request |
formajax:complete | Form Element<form class="form-ajax-submit"> | Event will be triggered after Ajax request completed |
formajax:beforesend | Form Element<form class="form-ajax-submit"> | Event will be triggered right before Ajax request |
formajax:error | Form Element<form class="form-ajax-submit"> | Event will be triggered on Ajax request error |
var app = new Framework7();
var $$ = Dom7;
$$('form.form-ajax-submit').on('formajax:success', function (e) {
var xhr = e.detail.xhr; // actual XHR object
var data = e.detail.data; // Ajax response from action file
// do something with response data
});
App Events
Event | Target | Arguments | Description |
---|---|---|---|
formAjaxSuccess | app | (formEl, data, xhr) | Event will be triggered after successful Ajax request |
formAjaxComplete | app | (formEl, data, xhr) | Event will be triggered after Ajax request completed |
formAjaxBeforeSend | app | (formEl, data, xhr) | Event will be triggered right before Ajax request |
formAjaxError | app | (formEl, data, xhr) | Event will be triggered on Ajax request error |
var app = new Framework7();
app.on('formAjaxSuccess', function (formEl, data, xhr) {
// do something with response data
});