Lesson 04: Preferences

From VZ Developer Wiki
Jump to: navigation, search

General Guidelines | XML Specification | Features | Views | JavaScript API | REST API | Tutorials | OAuth


Lesson 03: Views and Navigation Back to overview Lesson 05: Fetching content from VZ CDN

Some gadgets need to give users a way of supplying user-specific information. For example, a weather gadget might require users to provide their postal codes. Preferences are always tied to the current owner and installation of the gadget. So they are only available if the gadget is running currently on context of a user or group installation. If you allow multiple installations of your gadget for one user, each gadget has its own preferences. The user preferences (<UserPref>) section in the XML file describes the user input fields that are turned into user interface controls when the gadget runs.

<Module>
    <ModulePrefs title="HelloWorld Gadget">
        <Require feature="opensocial-0.8" />
        <Require feature="views" />
    </ModulePrefs>
    <UserPref name="difficulty" 
	     display_name="Difficulty"
	     datatype="enum"
	     default_value="4">
        <EnumValue value="3" display_value="Easy"/>
        <EnumValue value="4" display_value="Medium"/>
	<EnumValue value="5" display_value="Hard"/>
    </UserPref>
    <UserPref name="name" required="true" />
    <UserPref name="yesno" datatype="bool" />
    <UserPref name="hidden" datatype="hidden" default_value="abcde" />

    ....

</Module>

See Gadgets_XML#User_Preferences for a full list of available datatypes.

Additionally to the user interface preferences can be read and set with the Gadgets API (see Gadgets.Prefs_(v0.8)).

var prefs = new gadgets.Prefs(); 
prefs.set("key", "value");
var name = prefs.getString("name"); 
var lang = prefs.getLang();


  • Lesson 04: Preferences