Supporting widget customization and personalization

When you are developing widgets, consider how users might want to customize and personalize the widgets. You can then provide the appropriate code in the various widget attribute layers.

About this task

When you define a widget, its attributes are its customization points. That is, you can use these attributes to customize the widget for a particular use for all users and also personalize the widget for a single user. There are four layers that expose these widget attributes:

The definition layer sets the default attribute values for all instances of the widget.
The administration layer sets attribute values for all instances of a widget at run time. Superusers set these attributes when the widget is in the config mode.
The instance layer sets the attribute values for a particular instance of a widget. Page editors set these attributes when the widget is in the edit mode.
The user layer sets the attribute values for a particular instances of a widget for a particular user. Page viewers set these attributes explicitly when the widget is in the personalize mode or implicitly when the widget is in view mode.

See Widget attribute layers for information on these layers and how they interact to set attribute values.

Think about the layers when you code each mode. Expose only the attributes that make sense for a particular user. For example, if there is an attribute that only the superuser should be able to change, put the code to support that change in the config mode. If there is a change that superusers and editors can make, put the code to support that change in the config mode and in the edit mode.

When you allow users to personalize a widget, decide whether you want to set attributes explicitly, implicitly, or both.

An explicit personalization occurs when users deliberately decide what they want to see. For example, when a user clicks Personalize from the widget menu, he or she then consciously selects a setting and saves it.
An implicit personalization occurs when users are unaware that they have made a choice about what they want to see. For example, if a widget has a table and an attribute that sets which column sorts the table, you can code the widget to change the attribute when the user selects a column header. The action of selecting the column header implies that the user prefers to sort the data in this way, and the setting is saved automatically

Limit the personalization of a widget to the changes that make sense for individual users. For example, for a weather widget, individual users probably need to personalize the location of the forecast. However, individual users probably do not need to personalize the number of days in the forecast so you would not support changing that attribute in the personalize mode or the view mode. If you do want provide some customization, it might be more appropriate to allow an administrator to customize the number of forecasted days for all users and you would include the appropriate code in the config mode.

Procedure

Define all of the points of customization and personalization for the widget as attributes in the widget definition XML. The values you set here are the default values for the widget.
In the widget definition, specify the modes that you want the widget to support:
```
supportedModes="view edit config personalize"
```
The view mode is mandatory. The edit mode is mandatory for all widgets except for system widgets such as the ones used for customizing a theme.
For each supported mode, add a content section:
```
<iw:content mode="personalize">
<![CDATA[
// content here
]]>;
</iw:content>
```
Use the _WID_ tag as a prefix for attribute elements in the widget content. For example, a weather widget title might look like this: <h1 id="_WID_weatherTitle">Local Weather</h1>. When a browser renders the widget, the code replaces the _WID_ with the ID of the specific widget instance. This means that if there are multiple instances of a widget on a given page, retrieving a particular element using getElementById() does not fail because of multiple elements with the same ID. You should assign a member to store the _WID_ value because the code will frequently reuse it when retrieving attributes.
For each supported mode, define the functionality in JavaScript. For example, in the personalize mode, code for a control with a postal code as an integer value might look like this:
```
onPersonalize: function() {
	var att = this.iContext.getiWidgetAttributes();
	var zipCode = att.getItemValue("zipCode");
	if (zipCode) {
		document.getElementById(this.domID + "zipCode").value = parseInt(zipCode);
	}
}
```
In the example code, the domID is the member storing the _WID_ value. That is, this.domID is equal to "_" + this.iContext.widgetId + "_".
To preserve the personalization, include code that sets the widget attributes and saves that change. Saving the personalization means that when the user revisits the page, the widget will look like it did when the user left the page.
Tip: If other modes are also saving attribute changes, you can create a common save function and call this function from each mode. For example, code using a save function might look like this:
```
var att = this.iContext.getiWidgetAttributes();
	var zipCode = document.getElementById(this.domID + "zipCode");
	att.setItemValue("zipCode", ""+zipCode, false);
	att.save();
```