OpenSocial UserPrefs

User preferences (UserPrefs) can be used by app developers to store configuration values for a given user of a particular app. UserPrefs are typically set by the users and persist across a given instance of a gadget. Typical UserPrefs can include things like color or size of gadget, or other personalization options like location information. For example a gadget which searches for materials via WorldCat Search API might allow users to set libraries to limit them search to.

UserPrefs are made up of the following attributes:

• name - The name of the preference. This is used to call the preference when using gadget.Prefs or ${Prefs} variable substitutions
• datatype - Type of data stored in the preference.
  • string - string value (default value)
  • hidden - a non-visible string which can't be edited by the user
  • bool - a boolean True/False value
  • list - a pipe-delimited (|) string of values
  • number - a numeric value
  • enum - list of values defined by the UserPrefs sub-element EnumValue which has value and display_value attributes.
• display_name - name of the preference for use when rendering an editing interface for prefs.
• default_value - default value for this preference
• required - Whether or not a valid value needs to be set for this preference in order for the gadget to function correctly. Valid values are "true" and "false" (default).

Example

<UserPref name="zip_code" display_name="Zip Code" datatype="string" default_value="" required="false" />
<UserPref name="typeOfLibrary" display_name="What kind of libraries are you looking for?" datatype="enum" default_value="" required="false">
      <EnumValue value="public" display_value="Public Library" />
      <EnumValue value="academic" display_value="Academic Library" />
      <EnumValue value="special" display_value="Special Library" />
</UserPref>

Accessing UserPrefs

UserPrefs are accessible via app code in two different ways:

• gadget.Prefs
• ${Prefs}

gadget.Prefs

• getArray
• getBool
• getInt
• getString

Extra Prefs

• getLang
• getCountry
• getModuleId
• getMsg

Example

var prefs = new gadgets.Prefs();
var name = prefs.getString("name");

${Prefs}

${Prefs.[UserPref_name]}

Extra Prefs

• ${Prefs.Lang}
• ${Prefs.Country}
• ${Prefs.ModuleId}
• ${Prefs.Msg}

Example

${Prefs.name}