data-win-options property

Sets the specified properties and values for a Windows Library for JavaScript control.

Syntax

<div 
    data-win-control="control" 
    data-win-options="{ property : value}">
</div>

Property value

Type: String

One or more property-value pairs in JSON syntax.

Remarks

When you create an HTML control, you can set its properties using dedicated attributes. For example, to set the type, min, and max properties of an input control, you can set the type, min, and max attributes in your markup:

<input type="range" min="0" max="20" />

Unlike HTML controls, WinJS controls don't have dedicated element or attribute tags; for example, you couldn't create a Rating control and set its properties using the following markup:

<!-- Not valid markup. -->
<rating maxRating="10" averageRating="6" />

Instead, you use the data-win-options attribute to set a property in markup. The data-win-options attribute uses the following syntax :

To set multiple properties, you separate them with a comma:

The following example creates a ToggleSwitch control and sets its checked and title properties.

<div id="toggle" 
     data-win-control="WinJS.UI.ToggleSwitch"
     data-win-options="{title: 'My switch', checked: true}">
</div>

The data-win-options attribute can support several types of values in JSON syntax:

• A string literal.
• An array of values.
• A property or function within a namespace (a fully-qualified member using dot notation).
• The select function, which is a shortcut to WinJS.UI.scopedSelect.

For a list of properties supported by a given WinJS control, see its reference page.

You can also set the properties of a WinJS control programmatically. You can select the control using document.querySelector and then accessing the winControl property of the returned element.

Referring to functions or event handlers

To use a function as a value in your data-win-options attribute (such as an event handler), the function must be accessible to the global scope, and you must also call WinJS.Utilities.markSupportedForProcessing on the function. You can make the function accessible to the global scope by using WinJS.Namespace.define. For more information about setting event handlers declaratively, see How to set event handlers declaratively.

Requirements

See also

Quickstart: adding WinJS controls