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.
  • Method returns object
  • 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 object

    • Checkboxes 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

    EventTargetDescription
    form:todataForm Element<form>Event will be triggered on form when calling app.form.convertToData
    form:fromdataForm 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:

    EventTargetArgumentsDescription
    formToDataapp(form, data)Event will be triggered on app.form.convertToData call
    formFromDataapp(form, data)Event will be triggered on app.form.fillFromData call

    Form Data Example

    form-data.f7.html
    <template>
      <div class="page">
        <div class="navbar">
          <div class="navbar-bg"></div>
          <div class="navbar-inner">
            <div class="title">Form To Data</div>
          </div>
        </div>
        <div class="page-content">
          <form class="list list-strong-ios list-dividers-ios list-outline-ios" 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="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 grid grid-cols-2 grid-gap">
            <a class="button button-fill convert-form-to-data" href="#">Get Data</a>
            <a class="button button-fill fill-form-from-data" href="#">Fill Form</a>
          </div>
        </div>
      </div>
    </template>
    <script>
      export default (props, { $, $on, $f7 }) => {
        $on('pageInit', () => {
          $('.convert-form-to-data').on('click', function () {
            var formData = $f7.form.convertToData('#my-form');
            alert(JSON.stringify(formData));
          });
    
          $('.fill-form-from-data').on('click', function () {
            var formData = {
              'name': 'John',
              'email': 'john@doe.com',
              'gender': 'female',
              'toggle': ['yes'],
            }
            $f7.form.fillFromData('#my-form', formData);
          });
        });
    
        return $render;
      }
    </script>

    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:

    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.
  • Method returns object with form data
  • 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

    EventTargetDescription
    form:storedataForm Element<form>Event will be triggered right after form data saved

    App Events

    Form Storage api emit events on app instance as well:

    EventTargetArgumentsDescription
    formStoreDataapp(form, data)Event will be triggered right after form data saved

    Form Storage Example

    form-storage.f7.html
    <div class="page">
      <div class="navbar">
        <div class="navbar-bg"></div>
        <div class="navbar-inner">
          <div class="title">Form Storage</div>
        </div>
      </div>
      <div class="page-content">
        <div class="block">Just fill up the form below and then go to any other page, or try to close this site, and
          when you will back here form fields will keep your data.</div>
        <form class="list list-strong-ios list-dividers-ios list-outline-ios 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="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>
      </div>
    </div>

    Ajax Form Submit

    Framework7 allows automatically send form data using Ajax.

    It could be done in two ways

    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 attribute

    • Request method will be the same as specified in form's method attribute

    • Content type will be the same as specified in form's enctype attribute. By default (if not specified), it is application/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

    EventTargetDescription
    formajax:successForm Element<form class="form-ajax-submit">Event will be triggered after successful Ajax request
    formajax:completeForm Element<form class="form-ajax-submit">Event will be triggered after Ajax request completed
    formajax:beforesendForm Element<form class="form-ajax-submit">Event will be triggered right before Ajax request
    formajax:errorForm 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

    EventTargetArgumentsDescription
    formAjaxSuccessapp(formEl, data, xhr)Event will be triggered after successful Ajax request
    formAjaxCompleteapp(formEl, data, xhr)Event will be triggered after Ajax request completed
    formAjaxBeforeSendapp(formEl, data, xhr)Event will be triggered right before Ajax request
    formAjaxErrorapp(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
    });