index.mustache revision 71652747cffdc14cc110674ceab537c0367a819b
aaa47eea1899f62eb14a8744d794e9604cab579fJenny Donnelly<div class="intro">
71652747cffdc14cc110674ceab537c0367a819bLuke Smith <p>The Cache Utility provides a basic caching mechanism for storing key/value pairs in local JavaScript memory. As a subclass of Plugin, it is designed to seamlessly integrate with other components (such as <a href="../datasource/" title="YUI 3: DataSource">DataSource</a>).</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<h2 id="upgrade">Upgrade Notes</h2>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dt>Cache as a plugin has changed</dt>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dd>Implementers upgrading from version 3.1.1 or earlier who are using Cache as a plugin now need to point to Y.Plugin.Cache instead of Y.Cache.</dd>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly{{>getting-started}}
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<h2 id="using">Using the {{displayName}}</h2>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>This section describes how to use the {{displayName}} in further detail.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<h3 id="base">Basic caching</h3>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>Basic caching allows you to store frequently used data in local JavaScript memory. In cases where data is retrieved over the wire from a server, you can store the response in a local cache and eliminate future trips to the server for better performance and reduced server load.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>Use the following Attributes to configure your Cache instance:</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th>Attribute</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th>Default</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th>Description</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`max`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>The maximum number of entries the cache can hold. <strong>The cache is disabled by default!</strong> Set this value to a number greater than zero to turn on caching.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`size`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>Read-only. Returns the number of entries currently stored in the cache.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`entries`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>Read-only. Returns an array of the entries currently stored in the cache.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`expires`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>By default, expiration is disabled. To enable expiration of data, set this value to the Date when the data should expire, or the relative number of milliseconds from collection that the data should expire.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`uniqueKeys`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`false`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>When calling add() with an entry, checks to see if the key is already stored in the cache. Enforcing unique keys requires iterating through all stored entries, so setting this attribute to `false` is more performant. Note: If expiration is enabled, you should probably set uniqueKeys to `false` to avoid problems if data is cached multiple times with conflicting expirations.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>Here are the ways you can set the `max` value</strong> of a cache. <strong>You must set a `max` value to turn on caching.</strong></p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Configure Cache maximum size in the constructor
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnellyvar myCache = new Y.Cache({max:5});
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Set the maximum size at runtime
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p><strong>Cache key/value pairs with the `add()` method.</strong></p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Add entries to the Cache
4e2bc03d0ba795d507670920a0b039982f520e0bJenny DonnellymyCache.add("key1", "value1");
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p><strong>Retrieve cached entries with the `retrieve()` method.</strong> If there is no match for the given key, then `null` will be returned. Cached entries contain the properties `request`, `response`, `cached`, and `expires`.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Retrieve a cached entry
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnellyvar cachedEntry = cache.retrieve("key1");
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>By default, cached entries may contain duplicate keys: if you add an entry for request "foo" with value "bar" and then add another entry for request "foo" with value "bat", the cache will contain both entries. Retrieving an entry for request "foo" will only retrieve the newest value. However, setting `uniqueKeys` to `true` will validate for the uniqueness of keys stored in the cache.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Enforce unique keys in the constructor
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnellyvar myCache = new Y.Cache({max:5, uniqueKeys:true});
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Enforce unique keys at runtime
4e2bc03d0ba795d507670920a0b039982f520e0bJenny DonnellymyCache.set("uniqueKeys", true);
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>A cache may be flushed of all its entries with the `flush()` method.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Flush the cache
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<h3 id="offline">Offline caching</h3>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>The CacheOffline cache extends basic caching functionality by storing data in the <a href="http://stackoverflow.com/questions/2010892/storing-objects-in-html5-localstorage" title="Storing Objects in HTML5 localStorage - Stack Overflow">HTML5 localStorage object</a> on browsers where that is supported, so that data can be available when the browser is offline and can persist across browser sessions. In cases where HTML5 localStorage is not available (i.e., IE 6 and IE 7), the functionality falls back to basic caching in local JavaScript memory.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnellyvar myCache = new Y.CacheOffline();
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>Use the following Attributes to configure your CacheOffline instance:</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th>Attribute</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th>Default</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th>Description</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`sandbox`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`"default"`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>A unique identifier used to sandbox each cache instance's entries from other entries. This string persists across browser sessions so take care that it is not dynamically generated.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`expires`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`86400000`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>By default, data will expire one day after it is cached. This Attribute accepts a Data value, or a number of milliseconds.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`max`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`null`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>Read-only. This Attribute is disabled for CacheOffline — there is no notion of capping the number of entries in a cache. Each browser implements a maximum localStorage byte size.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`uniqueKeys`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`true`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>Read-only. This Attribute is disabled for CacheOffline. All stored keys are unique.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<h3 id="plugin">Cache as a plugin</h3>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>Use the `plug(Y.Plugin.Cache)` method on a host object to enable caching. The Y.Plugin.Cache class is available in the "cache-plugin" submodule.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Define a max value to enable plugging.
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>The Cache plugin also accepts a `cache` value to enable you to point to any number of Cache implementations. Y.Cache and Y.CacheOffline are currently available.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Define a max value to enable plugging.
4e2bc03d0ba795d507670920a0b039982f520e0bJenny DonnellymyWidget.plug(Y.Plugin.Cache, {cache:Y.CacheOffline});
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>The Y.Plugin.DataSourceCache plugin enables seamless caching of DataSource responses.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Use a basic cache
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnellycache: Y.Cache, // this is the default, this line is not needed
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Use the "cache" configuration property to enable offline caching
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnellysandbox: "my3HrCache",
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnellyexpires: 10800000 // 3 hours
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<p>Once the DataSourceCache plugin is enabled, it handles caching and retrieval of values without the need for extra code. Furthermore, all the methods and properties of the Cache instance is available on the host's `cache` namespace.</p>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly// Flush myDataSource's cache.
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly<h3 id="events">Events</h3>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th>Event</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th>When</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <th class="wrap">Properties available on the Event facade passed to handler</th>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`add`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>Entry is added to the cache.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dt>`entry`</dt>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dd>The cached entry.</dd>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`request`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>Entry is requested from the cache.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dt>`request`</dt>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dd>The request value.</dd>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`retrieve`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>Entry is retrieved from the cache.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dt>`entry`</dt>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dd>The retrieved entry.</dd>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`flush`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>Cache is flushed.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>none</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>`error`</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <td>CacheOffline only. Fired when an entry could not be added, most likely due to exceeding the browser quota for the localStorage object.</td>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dt>`error`</dt>
4e2bc03d0ba795d507670920a0b039982f520e0bJenny Donnelly <dd>The error object.</dd>