Using UWA preferences

What is UWA preferences?

When you create an UWA application, you may want to let the user change some settings like the number of visible element per listing, some search filter, etc...

To let you expose application settings UI with native look and feel from the environment where your UWA apllication is running, UWA application allow the developer to declare a set of preferences that will be expose to the user using the native environment UI.

How to use UWA preferences?

To define preferences that the user will be able to edit. you need to use the UWA's <widget:preferences> element.

Example of preference declaration:

<!-- UWA application preferences -->
<widget:preferences>
    <widget:preference
        type="text"
        name="feedUrl"
        label="RSS/Atom feed to use"
        defaultValue="https://blog.netvibes.com/rss.php">
    </widget:preference>
</widget:preferences>

You can get the preference value using UWA's JavaScript function widget.getValue(name) and set the value of the preference using widget.setValue(name, val) function.

Values are stored on the Netvibes server or in a cookie for example, depending of the environment.

Example of preference manipulation:

Get feedUrl preference value

var feedUrl = widget.getValue('feedUrl');

Set feedUrl preference value

var feedUrl = "http://example.com";
widget.setValue('feedUrl', feedUrl);

Get feedUrl preference schema
```
widget.getPreference('feedUrl');
```

Return following object

{
   type: "text",
   name: "feedUrl",
   label: "RSS/Atom feed to use",
   defaultValue: "https://blog.netvibes.com/rss.php",
   value: "https://blog.netvibes.com/rss.php"
}

Following method allow preferences manipulation:

UWA.Widget.getValue: Gets the value of the given preference.
UWA.Widget.setValue: Sets the value of the given preference.
UWA.Widget.deleteValue: Delete value of the given preference.
UWA.Widget.getPreference: Get a preference with its name.
UWA.Widget.addPreference: Adds a single preference to the existing preferences of the widget.

To be valid, UWA application XHTML preferences declarations should follow these requirements:

There MUST be only one <widget:preferences> tag per UWA application.
The <widget:preferences> tag and its content MUST be well-formed XML. Notably, XHTML entities SHOULD be escaped.
The <widget:preferences> tag MUST be placed within the XHTML file's <head> tag.
The <widget:preference> tag MUST be within a <widget:preferences> tag.
Each preference MUST be defined within a single widget:preference tag within the widget:preferences tag.
Each preference SHOULD use a unique value for its name attribute.
Each preference tag <widget:preference> MUST be closed with </widget:preference> element.
Each preference tag <widget:option> MUST be closed with </widget:option> element.

Sample application with preferences

This sample UWA application demonstrate preferences manipulation and include all types supported preferences, for details about preference types check "Prefences types" section below.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:widget="http://www.netvibes.com/ns/">
    <head>
        <!-- Application Metas -->
        <title>UWA.Widget preferences sample</title>

        <!-- UWA Environment -->
        <link rel="stylesheet" type="text/css" href="//uwa.netvibes.com/lib/c/UWA/assets/css/standalone.css" />
        <script type="text/javascript" src="//uwa.netvibes.com/lib/c/UWA/js/UWA_Standalone_Alone.js"></script>

        <!-- Application Preferences -->
        <widget:preferences>
            <widget:preference name="my_text" type="text" label="My text pref" defaultValue=""></widget:preference>
            <widget:preference name="my_password" type="password" label="My password pref" defaultValue=""></widget:preference>
            <widget:preference name="my_checkbox" type="boolean" label="My checkbox pref" defaultValue=""></widget:preference>
            <widget:preference name="my_hidden" type="hidden" label="" defaultValue=""></widget:preference>
            <widget:preference name="my_range" type="range" label="My range pref" defaultValue="10" step="5" min="5" max="15"></widget:preference>
            <widget:preference name="my_list" type="list" label="My list" defaultValue="Value1">
                <widget:option label="Label1" value="Value1"></widget:option>
                <widget:option label="Label2" value="Value2"></widget:option>
                <widget:option label="Label3" value="Value3"></widget:option>
                <widget:option label="EmptyValue" value=""></widget:option>
            </widget:preference>
            <widget:preference name="my_empty_list" type="list" label="My Empty list" defaultValue="Value1">
            </widget:preference>
        </widget:preferences>

        <!-- Application JavaScript Source -->
        <script type="text/javascript">
        //<![CDATA[

            /*
                We create the global MyWidget object (it could be any other name).
                This object will be used to store variables and functions.
            */
            var MyWidget = {

                /*
                    The onLoad() function is the first one,
                    it will be triggered by widget "onLoad" event.
                */
                onLoad: function() {

                    // Get text based preferences values
                    var myText = widget.getValue('my_text'),
                        myPassword = widget.getValue('my_password'),
                        myHidden = widget.getValue('my_hidden'),
                        myList = widget.getValue('my_list');

                    // Get boolean based preference value
                    var myCheckbox = widget.getBool('my_checkbox');

                    // Get integer based preference value
                    var myRange = widget.getInt('my_range');

                    // Add a new preference
                    widget.addPreference({
                        name: "paging",
                        type: "boolean",
                        label: "Enable pagination",
                        defaultValue: "false"
                    });

                    // Replace an existing preference
                    widget.addPreference({
                        name: "my_text",
                        type: "text",
                        label: "My updated text pref",
                        defaultValue: ""
                    });

                    // Display all preferences
                    var prefsElement = widget.createElement('dl'),
                        prefElements = [];

                    widget.getPreferences().forEach(function (preference) {

                        prefElements.push(widget.createElement('dt', {
                            text: 'name: "' + preference.name + '" type: "' + preference.type + '"'
                        }));

                        prefElements.push(widget.createElement('dd', {
                            text: 'value: "' + (preference.value || 'undefined') + '"'
                        }));
                    });

                    prefsElement.setContent(prefElements);
                    prefsElement.inject(widget.body.empty());
                }
            };

            /*
                The "onLoad" event is the very first event triggered when
                the widget is fully loaded or when the preferences are validated.
            */
            widget.addEvents({
                onLoad: MyWidget.onLoad
            });

        //]]>
        </script>
    </head>
    <body>
        <p>Loading...</p>
    </body>
</html>

Prefences types

This section describe the differents UWA preference types.

The sample rendering is only here to explain the possible environment preference rendering, UWA application developers SHOULD not try to customize the preferences rendering since it's controlled by the plateform (e.g Netvibes Dashboard, Android) that render UWA application.

Text preference

Simple text input.

XHTML Syntax:

<widget:preference type="text" name="url" label="User Name" defaultValue="John Doe" ></widget:preference>

Expected rendering: SHOULD be rendered as a standard <input> tag of type "text", or the platform's equivalent rendering.

Sample rendering:

<label for="m_userName">User Name:
<input id="m_userName" type="text" name="userName" value="John Doe" /></label>

Boolean preference

Simple checkbox input.

XHTML Syntax:

<widget:preference type="boolean" name="displayImg" label="Display images" defaultValue="true" ></widget:preference>

Expected rendering: SHOULD be rendered as a standard <input> tag of type "checkbox", or the platform's equivalent rendering.

Sample rendering:

<label for="m_displayImg">Display images:
<input id="m_displayImg" type="checkbox" name="displayImg" checked="checked" /></label>

Hidden preference

Hidden input, that will be not expose to the final application user.

XHTML Syntax:

<widget:preference type="hidden" name="lastSearchQuery" defaultValue="" ></widget:preference>

Expected rendering: SHOULD be rendered as a standard <input> tag of type "hidden", or the platform's equivalent rendering. It may also be not rendered at all, and be handled directly by the platform using JavaScript or the platform's own methods.

Sample rendering:

<input id="m_lastSearchQuery" type="hidden" name="lastSearchQuery" />

Password preference

Simple password input.

XHTML Syntax:

<widget:preference type="password" name="authPass" label="User password" ></widget:preference>

Expected rendering: SHOULD be rendered as a standard <input> tag of type "password", or the platform's equivalent rendering.

Sample rendering:

<label for="m_authPass">User password:
<input id="m_authPass" type="password" name="authPass" value="" /></label>

List preference

Simple select input.

XHTML Syntax:

<widget:preference type="list" name="category" label="Category" defaultValue="1st">
    <widget:option value="all" label="all"></widget:option>
    <widget:option value="1st" label="First category"></widget:option>
    <widget:option value="2nd" label="Second category"></widget:option>
    <widget:option value="3rd" label="Third category"></widget:option>
</widget:preference>

Expected rendering: SHOULD be rendered as a standard <select> tag with standard <option> inner tags, or the platform's equivalent rendering.

Sample rendering:

<label for="m_category">Category:</label>
<select id="m_category" name="category">
    <option value="all">all<option/>
    <option value="1st" selected="selected">First category<option/>
    <option value="2nd">Second category<option/>
    <option value="3rd">Third category<option/>
</select>

Range preference

Simple range input.

XHTML Syntax:

<widget:preference type="range" name="limit" step="1" min="1" max="7" defaultValue="5" label="Number of items to display"></widget:preference>

Expected rendering: SHOULD be rendered as a standard <select> tag with standard <option> inner tags, or the platform's equivalent rendering. In case the platform implements an HTML5-enabled web engine (with Web Forms 2.0 support), the Range preference should be rendered as a standard HTML5 <input> tag of type "number".

Sample HTML 4 / XHTML 1 rendering:

<label for="m_limit">Number of items to display:
<select id="m_limit" name="limit">
    <option value="1" />1</option>
    <option value="2" />2</option>
    <option value="3" />3</option>
    <option value="4" />4</option>
    <option value="5" selected="selected" />5</option>
    <option value="6" />6</option>
    <option value="7" />7</option>
</select>
</label>

Sample Web Forms 2.0 rendering:

<label for="m_limit">Number of items to display:
<input id="m_limit" name="limit" type="number" step="1" min="1" max="7" defaultValue="5" /></label>