add preferences to your widget

If you want the user to be able to change settings or preferences for your widget, you can design a simple menu that contains text entries, checkboxes, and lists that the user can access when setting up the widget. This menu is similar to an HTML form, just a bit more limited. For example, an RSS feed reader may provide a text entry field for the RSS feed URL and a checkbox for allowing notifications, or a world clock may provide a list of time zones that the user can pick from. All of the controls you want to provide in your widget's settings menu are defined in the myloConfig.xml file.

create a myloConfig.xml file

Here's an example myloConfig.xml file:

<?xml version="1.0" encoding="utf-8"?>
<config xmlns="http://xmlns.sony.net/mylo/widget" version="1.0">
	<item title="Select" name="test_select" type="select" comment="Select one of these options">
		<option>One</option>
		<option>Two</option>
		<option>Three</option>
		<value>One</value>
		<default>One</default>
	</item>
	
	<item title="Optional Text" name="test_opt_text" type="text" comment="Enter some text here (optional)">
		<value>This may be left blank</value>
		<default>This may be left blank</default>
	</item>
	
	<item title="Required Text" name="test_reqd_text" type="text" comment="This text is required" required="on">
		<value>This is required</value>
		<default>This is required</default>
	</item>
	
	<item title="Checkbox" name="test_checkbox" type="checkbox" comment="Check or uncheck this box">
		<value>off</value>
		<default>off</default>
	</item>
</config>

Copy and paste the above text into a new myloConfig.xml file, then modify the contents of the <config> tag to create your desired controls.

the <item> tag

Each control is defined by an <item> tag:

<item title="Label" name="control_name" type="text" comment="Description" required="on">

The attributes of the <item> tag define the control's name and type:

title - The label of the control that's shown to the user.
name - Your widget's JavaScript code uses this name to access the text/value entered into this control.
type - The type of the control, which can be "select", "text", or "checkbox".
comment - A more detailed description of the control that can be shown to the user. (optional)
required="on" - If included, the user cannot leave this text entry blank. (optional, for "text" controls only)

Each <item> can also contain <value> and <default> tags to define the default state (selected item, entered text, or checkbox state) of the control. The contents of the <value> tag are used when the widget is first created, while the contents of the <default> tag are used when the user presses the Reset button in the preferences menu.

the "select" control

The select control allows the user to select one option from a predefined list of options. For example, a world clock may use a select control to provide a list of time zones that the user can pick from.

<item title="Select" name="test_select" type="select" comment="Select one of these options">
	<option>One</option>
	<option>Two</option>
	<option>Three</option>
	<value>One</value>
	<default>One</default>
</item>

The options that the user can select from are defined by <option> tags. These tags may optionally contain a value attribute, which holds extra data for each option that can be retreived by your JavaScript code.

the "text" control

The text control provides a text entry field that the user may type arbitrary text in. For example, an RSS feed reader widget may provide a text control for the user to enter an RSS feed URL into.

<item title="Optional Text" name="test_opt_text" type="text" comment="Enter some text here (optional)">
	<value>This may be left blank</value>
	<default>This may be left blank</default>
</item>

Optionally, a text control may be marked as required by adding the required="on" attribute to its item tag. This prevents the user from being able to save their preferences if they leave this field blank.

<item title="Required Text" name="test_reqd_text" type="text" comment="This text is required" required="on">
	<value>This is required</value>
	<default>This is required</default>
</item>

the "checkbox" control

The checkbox control provides a simple on/off switch that the user can toggle by tapping it. This can be used to enable or disable optional features on your widget that not all users may be interested in. For example, an RSS feed reader widget may flash the Mylo's LED to indicate when a new post has appeared in the RSS feed. Some users may find that distracting, so a checkbox control can be provided to give them the option to enable or disable that feature.

<item title="Checkbox" name="test_checkbox" type="checkbox" comment="Check or uncheck this box">
	<value>off</value>
	<default>off</default>
</item>

The <value> and <default> tags define whether the checkbox is on (checked) or off (cleared) by default.

access preferences with javascript

Now that you've created your preferences menu, you need to be able to actually read the preferences that the user has specified. First, you must include the mylo screen libraries by adding the following code to the <head> of your index.html, above any other <script> tags present.

<script type="text/javascript" src="/js/lib/WidgetLibrary.js"></script>
<script type="text/javascript" src="/js/lib/PreferencesLibrary.js"></script>
<script type="text/javascript" src="/js/lib/ExtensionLibrary.js"></script>

Next, include the following boilerplate code in your widget's JavaScript:

var extension = new Extension();
var prefObject = new Preferences(prefCallback);

function prefCallback()
{
	//handle new preference values here
	
	notifyReadyWidget();
	return prefObject;
}

function getPreferenceObject()
{
	return prefObject;
}

function changePreference(prefObject, updateFlag)
{
	if(updateFlag)
	{
		extension.saveFile(Extension.fileType.CONFIG, savePrefCallback, prefObject.save());  
		prefCallback();
	}
}

function savePrefCallback() {}

prefObject contains a list of all the preference items/controls you defined in myloConfig.xml, along with the values that the user has specified for them.
prefCallback() is called when the preferences object is first loaded or updated. Replace the "//handle new preference values here" comment with your code for reading and handling the new preference values (see the next section for how to read these values).
changePreference() is called when the user accesses the preferences menu. updateFlag will be true if they changed any values. The extension.saveFile() call will save the user's entered values back into myloConfig.xml by modifying the contents of the <value> tags for each control.
savePrefCallback() is called when extension.saveFile() has finished saving the user's entered values into myloConfig.xml. You usually don't need to do anything here.

how to read preference values

You can read preference values anywhere in your widget's code - both inside and outside of prefCallback(). The prefObject contains an array of each control defined in myloConfig.xml, and each control can be accessed either by accessing that array directly or by looking up a control by its name attribute.

var prefItem = prefObject.prefsItems[index];      //access a control by index number

var prefItem = prefObject.getItemByName("name");  //look up a control by its name attribute

Now that you have the control that you want to read as prefItem, you may read its value with prefItem.value or read its name attribute with prefItem.name.

TODO: Describe how to access the options list of a "select"-type control.

how to modify preference values

Preference values aren't read-only - they can be modified as well. Just assign a new value to prefItem.value, then save the new value with the extension.saveFile() function:

prefObject.getItemByName("name").value = "new value";
extension.saveFile(Extension.fileType.CONFIG, savePrefCallback, prefObject.save());

example widget

Download prefstest.mylow - This widget provides a simple preferences menu that contains an example of every type of control. The value of each control is displayed on the widget itself.