JStorage Contrib Package
Store/cache data locally in the browser using JavaScript
Introduction
jStorage is a cross-browser key-value store database to store data locally in the browser - jStorage supports all major browsers, both in desktop (yes - even Internet Explorer 6) and in mobile. This JStorageContrib package packages the
jstorage.js
JavaScript library and a dependent
json2.js
library.
jStorage home:
http://www.jstorage.info/
Documentation
The usage is best described with a use case:
Use case: You want to periodically refresh content in a sidebar or a header via an
Ajax call, such as once every minute. If the Ajax call is slow it takes a toll on every page load when browsing the site.
Solution: Store the result of the Ajax call locally in the browser. Use the locally stored data if it is fresh enough, else do another Ajax call to refresh it. This should work across pages when browsing the TWiki site.
Example
The following example is somewhat silly, but it serves as an example to study and understand how the local storage works. The example shows a box with the current GMT time. The time is stored locally in the browser. If this page is reloaded within a minute, the locally stored time is shown. If over a minute, or if you let the page sit for over a minute, two Ajax calls are made. The first one sets the current GMT time in a
SetGetPlugin variable on the server, the second call reads it back from the server; on success the time is stored locally in the browser, so that a page reload can get the time without an Ajax call.
Working example - box with current GMT time:
|
Underlying HTML and JavaScript:
<div id="exampleID" style="border: solid gray 1px;">
</div>
%INCLUDE{%SYSTEMWEB%.JStorageContrib}%
<script type='text/javascript'>
function refreshExampleData(id) {
var exampleData = $.jStorage.get(id);
if(exampleData){
updateExampleData(exampleData);
} else {
var loading = '%ICON{processing-bg}% refreshing...';
$('#exampleID').html(loading);
var now = new Date().toJSON().slice(11, 19);
var exData = 'Example time: ' + now + ' GMT';
var ajaxPostUrl = '%SCRIPTURL{rest}%/SetGetPlugin/set';
var ajaxGetUrl = '%SCRIPTURL{rest}%/SetGetPlugin/get';
$.ajax({
type: "POST",
url: ajaxPostUrl,
data: { 'name': id, 'value': exData, 'remember': 1 },
success: function(data) {
$.ajax({
type: "GET",
url: ajaxGetUrl,
data: { 'name': id },
success: function(result) {
$.jStorage.set(id, result);
// set 60 sec TTL (time to live)
$.jStorage.setTTL(id, 60000);
updateExampleData(result);
}
});
}
});
}
}
function updateExampleData(exampleData) {
$('#exampleID').html(exampleData);
}
$(document).ready(function() {
refreshExampleData('exampleVar');
var refreshId = setInterval(function() {
refreshExampleData('exampleVar');
}, 10000); // 10 sec refresh time
});
</script>
| |
Explanation:
The div tag with id "exampleID" is empty - its content is set dynamically via JavaScript code.
The %INCLUDE{%SYSTEMWEB%.JStorageContrib}% includes the necessary JavaScript libraries for browser local storage.
The jQuery ready() function at the bottom does two things:
- Refresh the example data by calling
refreshExampleData() .
- Set up a timer that refreshes the example data once every 10 seconds.
The refreshExampleData function first gets the local storage by ID: $.jStorage.get(id) . If the data exists and is not too old, the "exampleID" div is updated - this is fast because the data is retrieved from a local browser storage.
If not, two nested Ajax calls are made. The first one sets a SetGetPlugin variable with the current GMT time. On success, a second Ajax call is done to read the same SetGetPlugin variable. The following actions are done on success of the second call:
-
$.jStorage.set(id, result); - store the result in the browser for later use.
-
$.jStorage.setTTL(id, 60000); - set 60 sec TTL (time to live).
-
updateExampleData(result); - update the "exampleID" div.
In a real use you likely just have one Ajax call to read the data, not two calls.
Using this setup, the user sees the example data without delay, except when the data is too old; in which case it is refreshed with an Ajax call to the server.
| |
Section for Include
This section defines the JavaScript include. To use JStorage in JavaScript code you first need to include the library:
%INCLUDE{%SYSTEMWEB%.JStorageContrib}%
Installation Instructions
You do not need to install anything on the browser to use this extension. These instructions are for the administrator who installs the package on the server where TWiki is running.
- For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.
- Or, follow these manual installation steps:
- Download the ZIP file from the package home (see below).
- Unzip
JStorageContrib.zip
in your twiki installation directory. Content: File: | Description: |
data/TWiki/JStorageContrib.txt | Contrib documentation topic |
pub/TWiki/JStorageContrib/*.js | JavaScript files |
lib/TWiki/Contrib/JStorageContrib.pm | Contrib Perl module |
- Set the ownership of the extracted directories and files to the webserver user.
Contrib Info
- One line description, is shown in the TextFormattingRules topic:
- Set SHORTDESCRIPTION = Store/cache data locally in the browser using JavaScript
Related Topics: TWikiContribs,
TWikiPreferences