userprops.js

So you're a Synchronet JavaScript module author or modder and you've got some per-user 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.

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);

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.

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 a section but no key argument is provided by the caller
• a specific property key from a specified section of the user's property file and return its value or the specified deflt value if the property key does not exist

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.

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.

• JavaScript libraries