Wijmo

Custom Elements

This page compares both syntaxes for using Wijmo with KnockoutJS.

Introduction

Wijmo offers two similar, yet different, syntaxes for using the controls within KnockoutJS applications:

If you've worked with KnockoutJS before, you're probably familiar with custom binding syntax. Custom bindings are used with normal HTML elements, typically a <div>, using the data-bind attribute. The binding name corresponds to the control name with a wj prefix. The value of the binding will be a JavaScript object literal containing properties and event handlers that map to the Wijmo control.

As an alternative to the standard KnockoutJS binding syntax, the Wijmo offers the possibility to declare controls in the page markup as custom elements. With custom elements, the tag name corresponds to the control's binding name and the attribute names correspond to the control's property names. The element and parameter names must be lower-case and use dashes instead of using camel-case. It is important to mention that attribute values should be defined using exactly the same JavaScript expressions that are used in the custom binding definitions.

The examples below aim to illustrate both syntaxes for most of the Wijmo controls.

Input

Binding Syntax

<div> <label>InputNumber</label> <input data-bind="wjInputNumber: { value: pi, min: 0, max: 10, step: 1 }" /> </div> <div> <label>AutoComplete</label> <div data-bind="wjAutoComplete: { itemsSource: countries, isEditable: true, cssMatch: 'highlight' }"></div> </div> <div> <label>ComboBox</label> <div data-bind="wjComboBox: { itemsSource: countries, isEditable: true }"></div> </div> <div> <label>InputDate</label> <div data-bind="wjInputDate: { value: today }"></div> </div> <div> <label>Menu</label> <div data-bind="wjMenu: { header: 'File', itemClicked: menuItemClicked }"> <span data-bind="wjMenuItem: {}"> <b>New</b><br><small><i>create a new file</i></small> </span> <span data-bind="wjMenuItem: {}"> <b>Open</b><br><small><i>open an existing file or folder</i></small> </span> <span data-bind="wjMenuItem: {}"> <b>Save</b><br><small><i>save the current file</i></small> </span> <span data-bind="wjMenuSeparator: {}"></span> <span data-bind="wjMenuItem: {}"> <b>Exit</b><br><small><i>exit the application</i></small> </span> </div> </div>
this.pi = ko.observable(Math.PI); this.today = ko.observable(new Date()); this.countries = countries; this.menuItemClicked = function(data, sender, args) { alert('You\'ve selected option ' + sender.selectedIndex + ' from the ' + sender.header + ' menu!'); };
.highlight { background-color: #ff0; color: #000; }
New
create a new file Open
open an existing file or folder Save
save the current file Exit
exit the application

Custom Element Syntax

<div> <label>InputNumber</label> <wj-input-number value="pi" min="0" max="10" step="1"> </wj-input-number> </div> <div> <label>AutoComplete</label> <wj-auto-complete items-source="countries" is-editable="true" css-match="'highlight'"> </wj-auto-complete> </div> <div> <label>ComboBox</label> <wj-combo-box items-source="countries" is-editable="true"> </wj-combo-box> </div> <div> <label>InputDate</label> <wj-input-date value="today"> </wj-input-date> </div> <div> <label>Menu</label> <wj-menu header="'File'" item-clicked="menuItemClicked"> <wj-menu-item> <b>New</b><br><small><i>create a new file</i></small> </wj-menu-item> <wj-menu-item> <b>Open</b><br><small><i>open an existing file or folder</i></small> </wj-menu-item> <wj-menu-item> <b>Save</b><br><small><i>save the current file</i></small> </wj-menu-item> <wj-menu-separator></wj-menu-separator> <wj-menu-item> <b>Exit</b><br><small><i>exit the application</i></small> </wj-menu-item> </wj-menu> </div>
this.pi = ko.observable(Math.PI); this.today = ko.observable(new Date()); this.countries = countries; this.menuItemClicked = function(data, sender, args) { alert('You\'ve selected option ' + sender.selectedIndex + ' from the ' + sender.header + ' menu!'); };
.highlight { background-color: #ff0; color: #000; }
New
create a new file Open
open an existing file or folder Save
save the current file Exit
exit the application

FlexChart

Binding Syntax

<div data-bind="wjFlexChart: { itemsSource: itemsSource, bindingX: 'country' }"> <div data-bind="wjFlexChartSeries: { name: 'Sales', binding: 'sales' }"></div> <div data-bind="wjFlexChartSeries: { name: 'Expenses', binding: 'expenses' }"></div> <div data-bind="wjFlexChartSeries: { name: 'Downloads', binding: 'downloads' }"></div> </div>
this.itemsSource = data;

Custom Element Syntax

<wj-flex-chart items-source="itemsSource" binding-x="'country'"> <wj-flex-chart-series name="'Sales'" binding="'sales'"></wj-flex-chart-series> <wj-flex-chart-series name="'Expenses'" binding="'expenses'"></wj-flex-chart-series> <wj-flex-chart-series name="'Downloads'" binding="'downloads'"></wj-flex-chart-series> </wj-flex-chart>
this.itemsSource = data;

FlexGrid

Binding Syntax

<div style="height:300px" data-bind="wjFlexGrid: { itemsSource: itemsSource, autoGenerateColumns: false }"> <div data-bind="wjFlexGridColumn: { binding: 'id', header: 'ID' }"></div> <div data-bind="wjFlexGridColumn: { binding: 'country', header: 'Country' }"></div> <div data-bind="wjFlexGridColumn: { binding: 'date', header: 'Date' }"></div> <div data-bind="wjFlexGridColumn: { binding: 'amount', header: 'Amount' }"></div> <div data-bind="wjFlexGridColumn: { binding: 'active', header: 'Active' }"></div> </div>
this.itemsSource = data;

Custom Element Syntax

<wj-flex-grid style="height:300px" items-source="itemsSource" auto-generate-columns="false"> <wj-flex-grid-column binding="'id'" header="'ID'"></wj-flex-grid-column> <wj-flex-grid-column binding="'country'" header="'Country'"></wj-flex-grid-column> <wj-flex-grid-column binding="'date'" header="'Date'"></wj-flex-grid-column> <wj-flex-grid-column binding="'amount'" header="'Amount'"></wj-flex-grid-column> <wj-flex-grid-column binding="'active'" header="'Active'"></wj-flex-grid-column> </wj-flex-grid>
this.itemsSource = data;

Gauges

Binding Syntax

<div class="linear-gauge" data-bind="wjLinearGauge: { value: value, min: min, max: max, step: step, format: format, showText: showText, isReadOnly: readOnly}"> </div> <div class="radial-gauge" data-bind="wjRadialGauge: { value: value, min: min, max: max, step: step, format: format, showText: showText, isReadOnly: readOnly}"> </div>
this.value = ko.observable(0.5); this.min = ko.observable(0); this.max = ko.observable(1); this.step = ko.observable(0.05); this.readOnly = ko.observable(false); this.format = ko.observable('p0'); this.showText = ko.observable('All');
.linear-gauge, .radial-gauge { margin: 7px 0 5px; } .radial-gauge { height: 200px; }

Custom Element Syntax

<wj-linear-gauge class="linear-gauge" value="value" min="min" max="max" step="step" format="format" show-text="showText" is-read-only="readOnly"> </wj-linear-gauge> <wj-radial-gauge class="radial-gauge" value="value" min="min" max="max" step="step" format="format" show-text="showText" is-read-only="readOnly"> </wj-radial-gauge>
this.value = ko.observable(0.5); this.min = ko.observable(0); this.max = ko.observable(1); this.step = ko.observable(0.05); this.readOnly = ko.observable(false); this.format = ko.observable('p0'); this.showText = ko.observable('All');
.linear-gauge, .radial-gauge { margin: 7px 0 5px; } .radial-gauge { height: 200px; }

FlexPie

Binding Syntax

<div data-bind="wjFlexPie: { itemsSource: itemsSource, binding: 'value', bindingName: 'name' }"> </div>
this.itemsSource = data;

Custom Element Syntax

<wj-flex-pie items-source="itemsSource" binding="'value'" binding-name="'name'"> </wj-flex-pie>
this.itemsSource = data;