src/data/proxy/LocalStorage.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @author Ed Spencer
  17  * @class Ext.data.proxy.LocalStorage
  18  * @extends Ext.data.proxy.WebStorage
  19  *
  20  * <p>The LocalStorageProxy uses the new HTML5 localStorage API to save {@link Ext.data.Model Model} data locally on
  21  * the client browser. HTML5 localStorage is a key-value store (e.g. cannot save complex objects like JSON), so
  22  * LocalStorageProxy automatically serializes and deserializes data when saving and retrieving it.</p>
  23  *
  24  * <p>localStorage is extremely useful for saving user-specific information without needing to build server-side
  25  * infrastructure to support it. Let's imagine we're writing a Twitter search application and want to save the user's
  26  * searches locally so they can easily perform a saved search again later. We'd start by creating a Search model:</p>
  27  *
  28 <pre><code>
  29 Ext.define('Search', {
  30     fields: ['id', 'query'],
  31     extend: 'Ext.data.Model',
  32     proxy: {
  33         type: 'localstorage',
  34         id  : 'twitter-Searches'
  35     }
  36 });
  37 </code></pre>
  38  *
  39  * <p>Our Search model contains just two fields - id and query - plus a Proxy definition. The only configuration we
  40  * need to pass to the LocalStorage proxy is an {@link #id}. This is important as it separates the Model data in this
  41  * Proxy from all others. The localStorage API puts all data into a single shared namespace, so by setting an id we
  42  * enable LocalStorageProxy to manage the saved Search data.</p>
  43  *
  44  * <p>Saving our data into localStorage is easy and would usually be done with a {@link Ext.data.Store Store}:</p>
  45  *
  46 <pre><code>
  47 //our Store automatically picks up the LocalStorageProxy defined on the Search model
  48 var store = new Ext.data.Store({
  49     model: "Search"
  50 });
  51
  52 //loads any existing Search data from localStorage
  53 store.load();
  54
  55 //now add some Searches
  56 store.add({query: 'Sencha Touch'});
  57 store.add({query: 'Ext JS'});
  58
  59 //finally, save our Search data to localStorage
  60 store.sync();
  61 </code></pre>
  62  *
  63  * <p>The LocalStorageProxy automatically gives our new Searches an id when we call store.sync(). It encodes the Model
  64  * data and places it into localStorage. We can also save directly to localStorage, bypassing the Store altogether:</p>
  65  *
  66 <pre><code>
  67 var search = Ext.ModelManager.create({query: 'Sencha Animator'}, 'Search');
  68
  69 //uses the configured LocalStorageProxy to save the new Search to localStorage
  70 search.save();
  71 </code></pre>
  72  *
  73  * <p><u>Limitations</u></p>
  74  *
  75  * <p>If this proxy is used in a browser where local storage is not supported, the constructor will throw an error.
  76  * A local storage proxy requires a unique ID which is used as a key in which all record data are stored in the
  77  * local storage object.</p>
  78  *
  79  * <p>It's important to supply this unique ID as it cannot be reliably determined otherwise. If no id is provided
  80  * but the attached store has a storeId, the storeId will be used. If neither option is presented the proxy will
  81  * throw an error.</p>
  82  */
  83 Ext.define('Ext.data.proxy.LocalStorage', {
  84     extend: 'Ext.data.proxy.WebStorage',
  85     alias: 'proxy.localstorage',
  86     alternateClassName: 'Ext.data.LocalStorageProxy',
  87
  88     //inherit docs
  89     getStorageObject: function() {
  90         return window.localStorage;
  91     }
  92 });