Lightning Components Developer Guide

What is the Lightning Component Framework?
Quick Start
Creating Components
Using Components
Communicating with Events
Creating Apps
Debugging
Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Using Storage Service

After you've initialized your custom storage, you can add and retrieve items from your storage. To do so, use the JavaScript put and get API of AuraStorage.

Storage Service uses ES6 Promises. For more information about promises, see www.html5rocks.com/en/tutorials/es6/promises/.

AuraStorage calls are asynchronous and return a Promise object that is resolved when the operation completes, or rejected if an error occurred.

Promises execute their resolve and reject functions asynchronously so the code is outside the Lightning event loop and normal rerendering lifecycle. If the resolve or reject code makes any calls to the Lightning Component framework, such as setting a component attribute, use $A.getCallback() to wrap the code. For more information, see Modifying Components Outside the Framework Lifecycle.

Note

The framework-provided actions storage for server-side actions automatically adds and retrieves items from storage and doesn't require you to call put and get explicitly. See Storable Actions.

Using get() and put()

This example shows how to use a storage object to explicitly store items. For information on initializing a storage object, see Initializing Storage Service.

The call to put takes a key that is used to uniquely identify the stored item, and returns a Promise that resolves when the operation is complete.

1var value1 = 67;
2// returns a Promise object that is not used here
3storage.put("score", value1);
4
5storage.put("name", "joe smith")
6  .then(function() { console.log("name is stored"); },
7        function(err) { console.log("named failed to store: " + err) }
8  );

The first function in then() is called when the Promise resolves. The second function is called when the Promise rejects.

You can retrieve stored items by using the get method. The get method takes as a parameter the key of the object you wish to retrieve. It returns a Promise that resolves to the retrieved value or undefined if the key is not found.

1storage.get("score")
2  .then(function(value) { console.log("score is " + value); })
3  .then(function() { return storage.get("name"); })
4  .then(function(value) { console.log("name is " + value); },
5        function(err) { console.log("failed: " + err); }
6  );

Using Other AuraStorage Methods

You can obtain any initialized named storage by calling getStorage() and by passing it the storage name. For example:

1var storage = $A.storageService.getStorage("MyStorage");

The getName() method returns the type of storage selected, not the name of the storage.

Note

There are other methods available in the JavaScript API. For example, you can get the current and max size:

1var storage = $A.storageService.getStorage("MyStorage");
2storage.getSize().then(
3  function(size) { return size; },
4  function(err) { return "unknown"; }
5).then(function(size) { 
6  var max = storage.getMaxSize();
7  console.log("size is " + size + " KB of max " + max + " KB");
8});

To clear the storage:

1var storage = $A.storageService.getStorage("MyStorage";
2storage.clear().then(
3  function() { console.log("storage has cleared"); },
4  function(err) { console.log("storage failed to clear: " + err); }
5);