This is an old revision of the document!
userprops.js
So you're a Synchronet JavaScript module author or modder and you've got some per-values that you would like to store persistently (in a file). This is where the User Properties (userprops.js
) library comes to “Save the day”!
This library manages the data/user/*.ini
files where per-user module-owned property values are stored.
These files are automatically cleaned-up by Synchronet when a user account number is assigned to a new user.
Usage
The userprops.js
library is a return-style library, meaning it is intended to be used like so:
var userprops = load({}, "userprops.js");
This creates a new library object (called userprops
in this example). This library object has the following methods for use by your JavaScript module:
get(section, key, deflt, usernum)
set(section, key, value, usernum)
You can then call these methods like so:
var userprops = load({}, "userprops.js"); var list = userprops.get("yourmodule", "list", []); list.push("new value"); // Add "new value" to list array userprops.set("yourmodule", "list", list);
usernum
By default, these methods operate on the .ini
file for the current user online. So if your module is only concerned with properties associated with the current user, you do not need to specify the usernum
argument when calling these methods. Otherwise, you would specify a valid user number as the usernum
argument value.
get
The userprops.js
get
method can be used to read:
- the entire property file associated with the specified user and return an associative-array of section Objects - this is the behavior when no arguments are provided by the caller
- the specified
section
from the user's property file and return it as an Object of properties - this is the behavior when asection
but nokey
argument is provided by the caller - a specific property
key
from a specifiedsection
of the user's property file and return its value or the specifieddeflt
value if the property key does not exist
Types
To have precise control over the data-types read from a user's property file, you will need to get
one property at a time and specify a default (deflt
) property value argument. Otherwise, you may need to provide special logic to handle String values that have been interpreted as valid Number or Boolean type values.
set
The userprops.js
set
method can be used to write:
- the entire property file associated with the specified user
- the specified
section
within the user's property file - a specific property
key
value within the user's property file
This method returns true
or false
to indicate success or failure.