| Next revision | Previous revision |
| custom:javascript:lib:userprops.js [2019/01/07 23:12] – created digital man | custom:javascript:lib:userprops.js [2019/08/14 00:30] (current) – [userprops.js] typo digital man |
|---|
| ====== userprops.js ====== | ====== userprops.js ====== |
| FIXME | |
| | 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 ''[[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 return-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. |
| | |
| | ==== 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. |
| ===== See Also ===== | ===== See Also ===== |
| * [[:custom:javascript:lib:|JavaScript libraries]] | * [[:custom:javascript:lib:|JavaScript libraries]] |
