Fork me on GitHub

Garlic.js allows you to automatically persist your forms' text field values locally, until the form is submitted. This way, your users don't lose any precious data if they accidentally close their tab or browser.

It strives to have a javascript agnostic interface for UI/UX developers that might want to use it. Just add some data-persist="garlic" in your form tags, and you're good to go!

1 - Simple form





Submit and Reset buttons will destroy the fields stored data. Try it out!

Top
2 - Form with non-persisted fields
This field will be locally persisted while submit button is not triggered

Thise textarea will never be persisted since it has the data-storage="false" attribute

Top
3 - Custom javascript or ajax validation

4 - Auto expiration
5 - Manage database and localStorage conflict



Top
6 - "Infinite" persistency



You still can destroy localStorage data on custom javascript events, try this action and then refresh the page to see the difference ;)
Top
Garlic is delivered to you in different builds (in the Github dist/ directory), here they are:

  • Garlic.min.js: ~5K, requires jQuery or Zepto (with data module builded for Zepto, see changelog 0.0.6

  • Garlic-standalone.min.js: ~25K, with minimum Zepto config builded inside. Requires nothing more. Only use that one if you don't already have jQuery or Zepto on your website, could make conflicts

  • Native localStorage compatible only with "modern" browsers: IE8+, Chrome 4+, FF 4+, Safari 4+, Opera 11+. See more here.
    Here is an awesome plugin that extends storage for IE6 and IE7!: https://github.com/mattpowell/localstorageshim
    Use it that way with Garlic:
    <!--[if lte IE 7]>
        <script src="https://raw.github.com/mattpowell/localstorageshim/master/localstorageshim.min.js" type="text/javascript"></script>
    <![endif]-->
    
    <script src="http://code.jquery.com/jquery-1.8.2.min.js"></script>
    <script src="garlic.js"></script>
Top
  • Include jQuery or Zepto (if not already here) and garlic.js
    <script src="jquery.js">
    <script src="garlic.js">
  • Add data-persist="garlic" to the forms you want to auto-persist
    <form data-persist="garlic" method="POST">

That's all! ;)

Top

Hey, all doc is not fully here. There are some useful config parameters in Garlic code, better directly have a look there! ;)

  • Want to protect all your forms on the same page, without having to add for each one of them data-persist="garlic"?
    <script type="text/javascript">
      $( 'form' ).garlic();
    </script>
  • Want to specifically chart fields persisted by Garlic? Use the auto-added class="garlic-auto-save" class!
  • Never destroy localStorage for a form: use data-destroy="false" (don't work on inputs separately, only on whole form inputs)
  • Store form localStorage across all domain (by default, storage is specific to each pages), use data-domain="true"
  • Manually call garlic in javascript
    <script type="text/javascript">
      $( '[rel=persist]' ).garlic();
    </script>
  • Destroy storage for an element (don't work on an entire form yet, only input by input)
    <script type="text/javascript">
      $( 'input.no_good' ).garlic( 'destroy' );
    </script>
  • Be notified when Garlic retrieve a field val by a custom overridable onRetrieve callback:
    <script type="text/javascript">
      $( 'input.no_good' ).garlic( {
          onRetrieve: function ( elem, retrievedValue ) {
              console.log( 'The retrieved value for ' + elem.name() + ' is : ' + retrievedValue );
          }
      } );
    </script>
  • Be notified when Garlic persists a field val by a custom overridable onPersist callback:
    <script type="text/javascript">
      $( 'input.no_good' ).garlic( {
          onPersist: function ( elem, storedValue ) {
              console.log( 'The persisted value for ' + elem.name() + ' is : ' + storedValue );
          }
      } );
    </script>
  • Generate your own key-storage fields policy to avoid conflicts:
    <script type="text/javascript">
      $( '#form' ).garlic( {
          getPath: function ( $elem ) {
              return $elem.attr( 'id' );
          }
      } );
    </script>
Top
Here is the test suite, have a look!

Please, feel free to fork and contribute to this plugin, or just discuss ideas, enhancement requests in an issue.

You could also fix my english mistakes, add some more tests in the test suite, and much more! :)
Top
1.2.3 - MIT - See changelog Top

© @guillaumepotier 2012 @wisembly