YUI 3: Cache

Getting Started

Include Dependencies

The easiest way to include the source files for Cache and its dependencies is to add the YUI seed file to your page, using the following script tag, and allow the YUI instance to download any additional files which may be required:

<!-- YUI Seed --> <script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>

The YUI instance will automatically pull down Cache's source files and any missing dependencies when the cache module is used. This helps you avoid having to manually manage the list of files needed on your page to support multiple components while also optimizing your initial page weight by loading files only when they are required.

If you do want to include file dependencies manually on your page, the YUI Dependency Configurator can be used to determine the list of files you need to include in order to use Cache.

The YUI Instance

Once you have the YUI seed file on your page (yui-min.js), you can create a new YUI instance for your application to use and populate it with the modules you need, specified as the first set of arguments to the use method:

// Create new YUI instance, and populate it with the required modules YUI().use("cache", function(Y) { // Cache available, and ready for use. });

The last argument passed to use is a callback function. The callback function will be invoked as soon as the YUI instance is done downloading any required files missing from your page. Once those files are loaded, your local YUI instance will be supplemented with the classes which make up the cache module and any modules it depends on. A reference to the populated YUI instance (Y) is passed back to your callback function. Within your callback, then, you can start writing your application code based on your own custom instance of YUI.

For more information on creating instances of YUI and the use method, see the YUI Global object documentation.

Using the Cache Utility

This section describes how to use the Cache Utility in further detail. It contains these subsections:

• Cache basics
• Cache as a plugin
• Events

Cache basics

Instantiate the cache with a max configuration value. By default, max is set to 0, which effectively disables caching. The max value can also be set at runtime.

// Configure Cache maximum size in the constructor var myCache = new Y.Cache({max:5}); // Set the maximum size at runtime myCache.set("max", 10);

Cache key/value pairs with the add() method.

// Add entries to the Cache myCache.add("key1", "value1"); // Entries may include an optional arbitrary payload myCache.add("key2", "value2", "optional-payload");

Retrieve cached entries with the retrieve() method. If there is no match for the given key, then null will be returned. Cached entries contain the properties request, response, and payload.

// Retrieve a cached entry var cachedEntry = cache.retrieve("key1");

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.

// Enforce unique keys in the constructor var myCache = new Y.Cache({max:5, uniqueKeys:true}); // Enforce unique keys at runtime myCache.set("uniqueKeys", true);

The cache may be flushed of all its entries with the flush() method.

// Flush the cache myCache.flush();

Cache as a plugin

Use the plug() method on the host instance to enable caching.

myDataSource.plug({fn:Y.Plugin.DataSourceCache, cfg:{max:3}});

Once the plugin is enabled, it will handle caching and retrieval of values seamlessly for you without the need for extra code. However, all the methods and properties of the Cache instance is available on the host's cache namespace.

// Flush myDataSource's cache. myDataSource.cache.flush(); // Disable myDataSource's cache myDataSource.cache.set("max", 0);

Events

Event	When	Properties available on the Event Facade passed to handler
add	Entry is added to the Cache.	entry The cached entry.
request	Entry is requested from the Cache.	request The request object.
retrieve	Entry is retrieved from the Cache.	entry The retrieved entry.
flush	Cache is flushed.	none

Support & Community