| Next revisionBoth sides next revision |
custom:javascript:lib:userprops.js [2019/01/07 23:12] – created digital man | custom:javascript:lib:userprops.js [2019/07/17 00:22] – Documented digital man |
---|
====== userprops.js ====== | ====== userprops.js ====== |
FIXME | |
| 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 ''[[dir: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 load-style library, meaning it is intended to be used like so: |
| |
| <code javascript> |
| var userprops = load({}, "userprops.js"); |
| </code> |
| |
| 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: |
| |
| <code javascript> |
| 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); |
| </code> |
| |
| ==== 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 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 |
| |
| |
| === 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. |
| |
| ==== put ==== |
| |
| The ''userprops.js'' ''put'' 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. |
===== See Also ===== | ===== See Also ===== |
* [[:custom:javascript:lib:|JavaScript libraries]] | * [[:custom:javascript:lib:|JavaScript libraries]] |