# Input 101

This page shows how to get started with Wijmo's Input controls.

## Getting Started

Steps for getting started with Input controls in KnockoutJS applications:

1. Add references to KnockoutJS, Wijmo, and Wijmo's KnockoutJS bindings.
2. Add a view model to provide data and logic.
3. Add a Wijmo Input control to the page and bind it to your data.
4. (Optional) Add some CSS to customize the input control's appearance.

<!DOCTYPE html> <html> <head> <link rel="stylesheet" type="text/css" href="css/bootstrap.css"/> <link rel="stylesheet" type="text/css" href="css/wijmo.css" /> <link rel="stylesheet" href="styles/app.css" /> <script src="scripts/knockout.js" type="text/javascript"></script> <script src="scripts/wijmo.js" type="text/javascript"></script> <script src="scripts/wijmo.input.js" type="text/javascript"></script> <script src="scripts/wijmo.knockout.js" type="text/javascript"></script> <script src="scripts/bindings/appBindings.js"></script> <script src="scripts/app.js"></script> <script src="scripts/viewmodels/appVM.js"></script> </head> <body> <!-- this is the InputNumber binding --> <div data-bind="wjInputNumber: { value: price, format: 'n', step: .5 }"></div></body> </html>
// create and apply application view model function viewModel1() { // value to bind to this.price = ko.observable(3.5); ............. }; (function () { ko.applyBindings(new viewModel1()); })();

#### Result (live):

## AutoComplete

The AutoComplete control is an auto-complete control that allows you to filter its item list as you type, as well as select a value directly from its drop-down list.

To use the AutoComplete control, you must minimally set the itemsSource property to an array of data in order to populate its item list. The AutoComplete control also offers several other properties to alter its behavior, such as the cssMatch property. The cssMatch property allows you to specify the CSS class that is used to highlight parts of the content that match your search terms.

The example below uses an array of strings to populate the AutoComplete control's item list using the itemsSource property. To see a list of suggestions, type "ab" or "za" in the AutoComplete controls below.

<div class="app-input-group"> <label>itemsSource Only</label> <div data-bind="wjAutoComplete: {itemsSource: countries}"></div> </div> <div class="app-input-group"> <label>itemsSource & cssMatch</label> <div data-bind="wjAutoComplete: { itemsSource: countries, cssMatch: 'highlight'}"></div> </div>
.highlight { background-color: #ff0; color: #000; }

#### Result (live):

itemsSource Only
itemsSource & cssMatch

## ComboBox

The ComboBox control is very similar to the AutoComplete control, but rather than providing a list of suggestions as you type, the ComboBox will automatically complete and select the entry as you type.

Like the AutoComplete control, you must minimally set the ComboBox's itemsSource property to an array of data in order to populate its item list. You may also want to specify whether the ComboBox is editable via the isEditable property. The isEditable property determines whether or not a user can enter values that do not appear in the ComboBox's item list.

The example below uses two ComboBoxes bound to the same data source as the AutoComplete control above. The first ComboBox's isEditable property is set to false, while the second ComboBox's isEditable property is set to true.

<div class="app-input-group"> <label>Non-Editable</label> <div data-bind="wjComboBox: { itemsSource: countries, isEditable: false}"> </div> </div> <div class="app-input-group"> <label>Editable</label> <div data-bind="wjComboBox: { itemsSource: countries, isEditable: true }"> </div> </div>

#### Result (live):

Non-Editable
Editable

## InputDate & Calendar

The InputDate control allows you to edit and select dates via a drop-down calendar, preventing you from entering an incorrect value. The InputDate's drop-down calendar was developed as a separate control and can be used be used independently from the InputDate control.

Both InputDate and Calendar, specify several properties to alter the controls' behavior. The most commonly used properties include:

- value: Specifies the date value for the control.
- min: Specifies the minimum date value that can be entered in the control.
- max: Specifies the maximum date value that can be entered in the control.

The example below demonstrates how to use each of these properties.

<div class="app-input-group"> <label>Bound InputDate with min & max</label> <div data-bind="wjInputDate: { value: today, min: minDate, max: maxDate }"> </div> </div> <div class="app-input-group"> <label>Bound Calendar with min & max</label> <div data-bind="wjCalendar: { value: today, min: minDate, max: maxDate }" style="width:300px;"> </div> </div> <p> <b>Selected Date: <span data-bind="text: format(today, 'd')"></span></b> </p> <p> <b>Valid Range: <span data-bind="text: format(minDate, 'd')"></span> to <span data-bind="text: format(maxDate, 'd')"></span></b> </p>
var today = new Date(); this.today = ko.observable(today); this.minDate = ko.observable(new Date(today.getFullYear(), 0, 1)); this.maxDate = ko.observable(new Date(today.getFullYear(), 11, 31));

#### Result (live):

Bound InputDate with min & max
Bound Calendar with min & max

Selected Date:

Valid Range: to

## InputDate, InputTime and InputDateTime Controls

Similar to the InputDate control, the InputTime control allows you to modify the time portion of a JavaScript date. The InputTime control shares many of the same properties as the InputDate control, including format, min, max, and value. The InputTime control also offers a step property that allows you to specify the number of minutes between entries in its drop-down list.

The InputDateTime control combines the InputDate and InputTime controls, allowing you to set the date and time portions of a JavaScript date. The The InputDateTime control has two drop-downs: a Calendar for picking dates, and a list for picking times.

The example below illustrates how to use the InputTime control in conjunction with the InputDate control. Notice that these controls work together to edit the same JavaScript Date object and only update the part of the DateTime that they are responsible for.

The example also shows an InputDateTime that updates both the date and time parts of the JavaScript Date object.

<div class="app-input-group"> <label>Bound InputDate with min, max, & format</label> <div data-bind="wjInputDate: { value: today, min: minDate, max: maxDate, format: 'MMM dd, yyyy' }"> </div> </div> <div class="app-input-group"> <label>Bound InputTime with min, max, & step</label> <div data-bind="wjInputTime: { value: today, step: 15, min: '07:00', max: '19:00' }"> </div> </div> <div class="app-input-group"> <label>Bound InputDateTime with min, max, format, and step</label> <div data-bind="wjInputDateTime: { value: today, format: 'MMM dd, yyyy hh:mm tt', min: minDate, max: maxDate, timeStep: 15, timeMin: '09:00', timeMax: '17:00' }"> </div> </div> <p> <b>Selected Date & Time: <span data-bind="text: format(today, 'G')"></span></b> </p>
var today = new Date(); this.today = ko.observable(today); this.minDate = ko.observable(new Date(today.getFullYear(), 0, 1)); this.maxDate = ko.observable(new Date(today.getFullYear(), 11, 31));

#### Result (live):

Bound InputDate with min, max, & format
Bound InputTime with min, max, & step
Bound InputDateTime with min, max, format, and step

Selected Date & Time:

## ListBox

The ListBox control displays a list of items and allows you to select items using your mouse and keyboard. Like the AutoComplete and ComboBox controls, you must specify the ListBox's itemsSource property in order to use the control.

The example below allows you to select an item within the ListBox control, and also displays the control's selectedIndex and selectedValue properties.

<div class="app-input-group"> <div data-bind="wjListBox: { itemsSource: cities, control: listBox, selectedIndex: listBoxIndex, selectedValue: listBoxValue }" style="height:150px;width:250px;"> </div> </div> <p> <b>selectedIndex: <span data-bind="text: listBoxIndex"></span></b> </p> <p> <b>selectedValue: <span data-bind="text: listBoxValue"></span></b> </p>
this.listBox = ko.observable(undefined); this.listBoxIndex = ko.observable(undefined); this.listBoxValue = ko.observable(undefined);

#### Result (live):

selectedIndex:

selectedValue:

## InputNumber

The InputNumber control allows you to edit numbers, preventing you from entering invalid data and optionally formatting the numeric value as it is edited. The InputNumber can be used without specifying any of its properties; however, you'll typically want to bind it to some data using the value property.

In addition to the value property, the InputNumber control offers several other properties that can be used to alter its behavior, such as:

- min: Specifies the minimum numeric value that can be entered.
- max: Specifies the maximum numeric value that can be entered.
- step: Specifies the amount to add or subtract from the current value when the spinner buttons are clicked.
- format: Specifies the numeric format used to display the number being edited. The format property uses a .NET-style numeric format string.

The example below demonstrates how to use all of these properties.

<div class="app-input-group"> <label>Unbound with "n0" format</label> <div data-bind="wjInputNumber: { format: 'n0' }"></div> </div> <div class="app-input-group"> <label>Bound with "n" format</label> <div data-bind="wjInputNumber: { value: pi, format: 'n' }"> </div> </div> <div class="app-input-group"> <label>Bound with min (0), max (10), step, and "c2" format</label> <div data-bind="wjInputNumber: { value: price, format: 'c2', step: .5, min: 0, max: 10 }"> </div> </div> <div class="app-input-group"> <label>Unbound with placeholder and isRequired="false"</label> <div data-bind="wjInputNumber: { placeholder: 'enter a number...', isRequired: false, value: null }"> </div> </div>
this.pi = ko.observable(Math.PI); this.price = ko.observable(3.5);

#### Result (live):

Unbound with "n0" format
Bound with "n" format
Bound with min (0), max (10), step, and "c2" format
Unbound with placeholder and isRequired="false"

## Menu

The Menu control allows you to create a simple drop-down list with clickable items. The Menu's items can be defined directly or by using the itemsSource property similar to the ComboBox. To specify the text displayed on the Menu, you can set the header property.

The Menu control offers two ways to handle user selections, specifying a command on each menu item and the itemClicked event. Unlike the itemClicked event, commands are objects that implement two methods:

- executeCommand(param): A method that executes the command.
- canExecuteCommand(param): A method that returns a Boolean value specifying whether or not the command can be executed. If the return value is false, the menu item is disabled automatically.

The example below demonstrates how to use both approaches.

<div class="app-input-group"> <label>itemClicked Event</label> <div data-bind="wjMenu: { header: 'File', itemClicked: menuItemClicked}"> <span data-bind="wjMenuItem: {}"><i class="fa fa-file-o"></i> <b>New</b><br><small><i>create a new file</i></small></span> <span data-bind="wjMenuItem: {}"><i class="fa fa-folder-open-o"></i> <b>Open</b><br><small><i>open an existing file or folder</i></small></span> <span data-bind="wjMenuItem: {}"><i class="fa fa-save"></i> <b>Save</b><br><small><i>save the current file</i></small></span> <span data-bind="wjMenuSeparator: {}"></span> <span data-bind="wjMenuItem: {}"><i class="fa fa-times"></i> <b>Exit</b><br><small><i>exit the application</i></small></span> </div> <div data-bind="wjMenu: { header: 'Edit', itemClicked: menuItemClicked}"> <span data-bind="wjMenuItem: {}"><i class="fa fa-cut"></i> <b>Cut</b><br><small><i>move the current selection to the clipboard</i></small></span> <span data-bind="wjMenuItem: {}"><i class="fa fa-copy"></i> <b>Copy</b><br><small><i>copy the current selection to the clipboard</i></small></span> <span data-bind="wjMenuItem: {}"><i class="fa fa-paste"></i> <b>Paste</b><br><small><i>insert clipboard content at the cursor position</i></small></span> </div> </div> <div class="app-input-group"> <label>Commands</label> <div data-bind="wjMenu: { header: 'Change Tax' }"> <span data-bind="wjMenuItem: { cmd: menuCommand, cmdParam: .25 }">+ 25%</span> <span data-bind="wjMenuItem: { cmd: menuCommand, cmdParam: .10 }">+ 10%</span> <span data-bind="wjMenuItem: { cmd: menuCommand, cmdParam: .05 }">+ 5%</span> <span data-bind="wjMenuItem: { cmd: menuCommand, cmdParam: .01 }">+ 1%</span> <span data-bind="wjMenuSeparator: {}"></span> <span data-bind="wjMenuItem: { cmd: menuCommand, cmdParam: -.01 }">- 1%</span> <span data-bind="wjMenuItem: { cmd: menuCommand, cmdParam: -.05 }">- 5%</span> <span data-bind="wjMenuItem: { cmd: menuCommand, cmdParam: -.10 }">- 10%</span> <span data-bind="wjMenuItem: { cmd: menuCommand, cmdParam: -.25 }">- 25%</span> </div> <div data-bind="wjInputNumber: { value: tax, format: 'p0', min: 0, max: 1, step: .05 }"></div> </div>
this.tax = ko.observable(.07); this.menuItemClicked = function (data, sender, args) { alert('You\'ve selected option ' + sender.selectedIndex + ' from the ' + sender.header + ' menu!'); }; this.menuCommand = { executeCommand: function (arg) { self.tax(self.tax() + arg); }, canExecuteCommand: function (arg) { if (wijmo.isNumber(arg)) { var val = self.tax() + arg; return val >= 0 && val <= 1; } return false; } };

#### Result (live):

itemClicked Event
New
create a new file Open
open an existing file or folder Save
save the current file Exit
exit the application
Cut
move the current selection to the clipboard Copy
copy the current selection to the clipboard Paste
insert clipboard content at the cursor position
Commands
+ 25% + 10% + 5% + 1% - 1% - 5% - 10% - 25%