Docs Module SharedObject

SharedObject

SharedObjects enable us to write data from our application and to persist the data on the user's machine, much in the same way as a cookie behaves.

Note: SharedObjects is an abstracted wrapper around indexedDB, and uses localStorage where applicable.

Contents:

• API Summary
• Creating a SharedObject
• Saving a SharedObject
• Deleting a SharedObject
• Manipulating SharedObject Data

API Summary:

Properties of SharedObject Module

Name	Description
driver	Current driver used by SharedObject readonly
*clear()	Purges all the data from the named shared object file and deletes the shared object from the browser.
*flush()	Immediately writes all locally persistent shared objects to a local file.
*getLocal()	Returns a reference to a locally persistent shared object that is available only to the current application.

Methods in bold* are asynchronous functions.

Properties inherited by shared object instances

Name	Description
*clear()	Purges all the data from the shared object and deletes the shared object from the browser.
data	A container used to store user data.
*flush()	Immediately writes a locally persistent shared object to a local file.
getSize()	Gets the current size of the shared object, in bytes.

Methods in bold* are asynchronous functions.

Creating a SharedObject:

To create a SharedObject, we do not call the constructor of the object. Instead we call the getLocal() static method. The getLocal() method determines if an object exists and if it does, opens it for reading; if it doesn't exist, it creates a new one. Then, a shared object instance is returned. By default, variables with the same shared object instances inherit the same properties and methods, unless the object was created with the persist parameter set to false;

const SharedObject = flevar.SharedObject;
const mySharedObject = await SharedObject.getLocal("my_sharedobject");

Note: getLocal() is an asynchronous method.

All SharedObjects have a property called data . This property is an object, and is used to store user data. The variables that we want to save in our application are added as properties of the SharedObject's data container:

mySharedObject.data.username = "Bob";
mySharedObject.data.age = 23;
mySharedObject.data.hobbies = ["brawling", "building", "reading", "mining"];

Note: Common JavaScript datatypes such as Number, Boolean, String, Object can be saved. Functions cannot be saved.

Saving a SharedObject:

Although the SharedObject has been created in the application, it hasn't yet been saved to the browser. You must explicitly choose to save the SharedObject to the browser using the flush() method.

await mySharedObject.flush();

Note: flush() is an asynchronous method.

However, to automatically save the SharedObject to the browser when the page is closed, pass in the autosave: true option upon Engine Initializing. Autosave is false by default.

Caveat: Due to browser limitations, indexedDB cannot save upon browser close. Passing autosave: true will force the SharedObject to use the localStorage API, which will inherit all the disadvantages, such as limited space (5MB max). If you want to use the indexedDB driver, keep autosave false. Additionally, the localStorage driver is automatically used on browsers that do not support indexedDB.

Deleting a SharedObject:

The SharedObject can be deleted using the clear() method. clear() purges all the data from the shared object and deletes the shared object from the browser.

const mySharedObject = await SharedObject.getLocal("my_sharedobject");
await mySharedObject.clear();
//The reference to `mySharedObject` is still active, and `mySharedObject` is now empty.

Note: clear() is an asynchronous method.

Alternatively, the SharedObject Module's static clear() method can be called to delete the object directly, without first obtaining an instance of it.

await SharedObject.clear("my_sharedobject");
//The reference to `my_sharedobject` is still active, and `my_sharedobject` is now empty.

Note: clear() is an asynchronous method.

Manipulating SharedObject Data:

By default, variables with the same shared object instances inherit the same properties and methods:

// both my_so_1 and my_so_2 use the my_so shared object instance.
const my_so_1 = await SharedObject.getLocal("my_so");
const my_so_2 = await SharedObject.getLocal("my_so");

trace(my_so_1.data === my_so_2.data);
// true

Unless the object was created with the persist parameter set to false:

// both my_so_1 and my_so_2 use the my_so shared object instance.
const my_so_1 = await SharedObject.getLocal("my_so", false);
const my_so_2 = await SharedObject.getLocal("my_so", false);

trace(my_so_1.data === my_so_2.data);
// false

Do not assign values directly to the data property of a shared object, as in my_so.data = someValue;. FlevaR ignores these assignments.

To delete attributes for local shared objects, use code such as delete my_so.data.attributeName;. Setting an attribute to null or undefined for a local shared object does not delete the attribute.

To create private values for a shared object (values that are available only to the shared object instance while the object is in use and are not stored with the object when it is flushed) create properties that are not named data to store them, as shown in the following example:

const my_so = await SharedObject.getLocal("foo");
my_so.color = "green";
my_so.team = "The Green Machine";
my_so.artist = "Green Day";
trace(my_so);
// { color: "green", team: "The Green Machine", artist: "Green Day", data: [object Object] }

Note: Variables with the same shared object instances do not inherit the same private properties.