====== 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 ''[[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 =====
  * [[:custom:javascript:lib:|JavaScript libraries]]

{{tag>javascript userprops}}