Client-Side Data Storage

Uniface dynamic server pages support client-side storage of data in a browser-based database, which makes it possible to save data locally when there is no connection to the server. This can be useful when you want to display read-only information that has previously been downloaded, or to save modified data until it can be synchronized or uploaded to the server.

JavaScript APIs

The Uniface JavaScript API provides a number of functions that make it possible to save data from a DSP to an offline datastore, and retrieve and load it into a specified DSP.

  • uniface.Instance.getData()—serialize data from a component instance into a string with JSON content. The data includes reconnection properties that mark any data that is new, changed, or deleted, so that its state can be restored and eventually synchronized with the server. For more information, see getData().
  • uniface.Instance.setData()—load data from a JSON string into the specified component instance. For more information, see setData().
  • uniface.datastore.put()—create or update the specified document in local storage. For more information, see put() .
  • uniface.datastore.get()—retrieve a specified document from local storage. For more information, see get().
  • uniface.datastore.remove()—delete the specified document from local storage. For more information, see remove().

Offline Storage

The offline data store used by the Uniface JavaScript API is PouchDB, an open-source JavaScript database that is designed to run within the browser. PouchDB is not a self-contained database, but an abstraction layer over other databases, such as IndexedDB, which is the default.

Note: Although adapters for other offline data stores are available, they must be downloaded as a plug-in and configured for use with PouchDB. If you use any configuration other than default, you are responsible for testing and verifying that it works correctly.

For more information, refer to their documentation at https://pouchdb.com.

Note: Client-side data storage is not supported for Internet Explorer 8 or 9.

Data Versions

Data to be stored must be formatted as a JSON document. Whenever a data object is created or updated, a new version of the document is created. It is distinguished from other versions by a revision marker that is automatically added to the document as a field _rev:String. The revision marker contains a unique random number that is updated each time the data object is updated. The revision marker is added to the response and can be used to update the document.

Creating and Updating Data

The following example demonstrates the use of the API to create and update a simple data object, and it shows how you can address specific versions of the document.

webtrigger detail
javascript

  'use strict';

  // Specify the document as JSON data with the mandatory doc id (_id)
  var docId = 'example';
  var document = {
    _id: docId,
	name: 'Bob',
	age: 23,
	profession: 'Designer'
  };

  // to remember the revisions to new or updated documents
  var revisionNewDoc, revisionUpdatedDoc;

  // Create the document (= JSON object) with id: docId
  console.log('Creating new document');
  uniface.datastore.put(document)
  .then(function (response) {
    // Remember the revision from the new document
    revisionNewDoc = response.rev;

    // Update the document with new age, for that use the original revision
    console.log('Updating age in document');
    document.age = 26;
    document._rev = revisionNewDoc;
    return uniface.datastore.put(document);
  }).then(function (response) {
    // Remember the revision of the updated document
    revisionUpdatedDoc = response.rev;

    // Get the first version of the document
    console.log('Getting first version');
    return uniface.datastore.get(docId, {'rev': revisionNewDoc});
  }).then(function (doc1) {
    // Display the age in the console
    console.log('Age in first version: ' + doc1.age);  
    // Result: 23 shows that the first version of the doc was fetched
    
    // Get the second version of the document
    console.log('Getting second version');
    return uniface.datastore.get(docId, {'rev': revisionUpdatedDoc});
  }).then(function (doc2) {
    // Display the age in the console
    console.log('Age in second version: ' + doc2.age);  
    // Result: 26 shows that second version of doc was fetched


  }).catch(function (err) {
    console.log('Error: ' + err);
  });

endjavascript
end

Related Topics