Adding preferences

Application Mashup (WireCloud) course @ http://edu.fiware.org

Use ← and → to move around. Press h for getting more info

Presenter Notes

Adding preferences

Introduction

Presenter Notes

Introduction

This widget represents the reference implementation of the "Adding preferences" tutorial. This tutorial is based on previous tutorials were we have used a hardcoded value of the API key for the weather underground service. This may be good enough for a basic version of the widget, but in the real world this would be better implemented as a preference.

For this tutorial, we're are going to use the proposed solution from the "[Making requests and wiring][prev_tutorial]" tutorial as base. You can download the code of the widget using this link.

[prev_tutorial]: 3.1.3_Making\ requests\ and\ wiring

Presenter Notes

Adding preferences

Adding preferences to the config.xml

Presenter Notes

Adding preferences to the config.xml

The first step for adding a preference is declaring it in the config.xml file. This can be accomplished by adding a preference element into the preferences element. The final result should look like:

...

    <preferences>
        <preference
            name="api_key"
            type="text"
            description="Weather Underground API key"
            label="API key"
        />
    </preferences>

...

Presenter Notes

Adding preferences to the config.xml

Description of the attributes:

  • The name attribute will be use to reference this preference when using the javascript API
  • The type attribute indicates the type of data this preference is going to store. Valid values are: boolean, list, number, password and text
  • The label attribute will be used, for example, in the user interface to ask the user for a value for this preference. Also, this attribute can be translated whereas the name attribute not
  • The description attribute is used to provided a more description about the preference

Presenter Notes

Adding preferences to the config.xml

This is the same declaration but using RDF (turtle):

...
    wire:hasPlatformPreference [ a wire:PlatformPreference ;
            rdfs:label "API key" ;
            dcterms:description "Weather Underground API key" ;
            dcterms:title "api_key" ;
            wire:index "0" ;
            wire:type "text" ] ;
...

Presenter Notes

Adding preferences to the config.xml

Preferences of type list need to provide the list of options to be provided in the user interface. This is accomplished by means of using the option element. This element requires two attributes:

  • The value attribute is the value that will be returned if the user selects this option.
  • The label attribute will be used in the user interface when referencing this option/value. This attribute can be translated.

Presenter Notes

Adding preferences to the config.xml

This is an example of how to declare a list preference:

...
    <preferences>
        <preference name="list" type="list" label="list" description="list preference" default="default">
            <option value="default" label="Default value"/>
            <option value="1" label="value1"/>
            <option value="2" label="value2"/>
        </preference>
    </preferences>
...

Presenter Notes

Adding preferences

Basic usage

Presenter Notes

Basic usage

Once declared the users preference in the widget or operator descriptor, you will be able to read the current value of the preference using the MashupPlatform.prefs.get method. This method will return a value using the type associated with the type of the preference:

  • string for preferences of type text, password and list
  • number for preferences of type number
  • and boolean for boolean preferences

Presenter Notes

Basic usage

For example, taking into account the code used in previous tutorials:

var getForecastByCoord = function getForecastByCoord(coord, onSuccess, onError) {

    ...

    url = 'http://api.wunderground.com/api/' + API_KEY + '/conditions/forecast/q/';
    url += coord.lat + ',' + coord.lon;
    url += '.json';

    MashupPlatform.http.makeRequest(url, {

    ...
};

Presenter Notes

Basic usage

Should be transformed to:

var getForecastByCoord = function getForecastByCoord(coord, onSuccess, onError) {

    ...

    url = 'http://api.wunderground.com/api/' + MashupPlatform.prefs.get('api_key') + '/conditions/forecast/q/';
    url += coord.lat + ',' + coord.lon;
    url += '.json';

    MashupPlatform.http.makeRequest(url, {

    ...
};

After this change, the API_KEY constant is not used anymore, so you can safely remove it from the source code.

Presenter Notes

Adding preferences

Reacting to preference changes

Presenter Notes

Reacting to preference changes

Some times widgets need to react to changes in the preferences. This can be accomplished using the MashupPlatform.prefs.registerCallback method. For example, we can make use of this support for displaying an alert message to the user just in case the new value for the api-key preference is not valid:

var updateMissingAPIKeyAlert = function updateMissingAPIKeyAlert() {
    if (MashupPlatform.prefs.get('api_key').trim().length !== 16) {
        document.getElementById('api-key-alert').classList.remove('hide');
    } else {
        document.getElementById('api-key-alert').classList.add('hide');
    }
};

MashupPlatform.prefs.registerCallback(function (new_values) {
    if ('api_key' in new_values) {
       updateMissingAPIKeyAlert();
    }
});

Presenter Notes

Reacting to preference changes

Evidently, this only check the value of the preference when this is changed, so you need to call manually the updateMissingAPIKeyAlert function when the widget is loaded. This can be accomplished using the following code:

window.addEventListener('load', function () {
    updateMissingAPIKeyAlert();
}, true);

Presenter Notes

Adding preferences

Testing it

Presenter Notes

Testing it

Once implemented our new widget we should test if it works as expected. This widget has the same functionallity provided by the widget created by following the steps of the "[Making requests and wiring][prev_tutorial]"

You can download both our implementation of the widget as the mashup example.

Presenter Notes

Thanks!

Presenter Notes