Wijmo 5

Input 101

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

Getting Started

Steps for getting started with Input controls in JavaScript applications:

  1. Add references to Wijmo.
  2. Add markup to serve as the Wijmo control's host.
  3. Initialize the Wijmo control(s) via JavaScript.
  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 href="css/app.css" rel="stylesheet" type="text/css" /> <script src="scripts/wijmo.js" type="text/javascript"></script> <script src="scripts/wijmo.input.js" type="text/javascript"></script> <script src="scripts/app.js" type="text/javascript"></script> </head> <body> <input id="gsInputNumber" type="text" /> </body> </html>
var inputNumber = new wijmo.input.InputNumber('#gsInputNumber'); inputNumber.value = 3.5; inputNumber.step = 0.5; inputNumber.format = 'n';

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> <label>itemsSource Only</label> <div id="acAutoComplete1"></div> </div> <div> <label>itemsSource &amp; cssMatch</label> <div id="acAutoComplete2"></div> </div>
var autoComplete1 = new wijmo.input.AutoComplete('#acAutoComplete1'); var autoComplete2 = new wijmo.input.AutoComplete('#acAutoComplete2'); autoComplete1.itemsSource = data.countries; autoComplete2.itemsSource = data.countries; autoComplete2.cssMatch = 'highlight'; // CSS class for custom highlighting
.highlight { background-color: #ff0; color: #000; }

Result (live):

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> <label>Non-Editable</label> <div id="cbComboBox1"></div> </div> <div> <label>Editable</label> <div id="cbComboBox2"></div> </div>
var comboBox1 = new wijmo.input.ComboBox('#cbComboBox1'); var comboBox2 = new wijmo.input.ComboBox('#cbComboBox2'); comboBox1.itemsSource = data.countries; comboBox1.isEditable = false; comboBox2.itemsSource = data.countries; comboBox2.isEditable = true;

Result (live):

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:

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

<div> <label>Bound InputDate with min &amp; max</label> <input id="idcInputDate" type="text" /> </div> <div> <label>Bound Calendar with min &amp; max</label> <input id="idcCalendar" type="text" style="width:300px;" /> </div> <p> <b>Valid Range: <span id="idcMinDate"></span> to <span id="idcMaxDate"></span></b> </p>
var inputDate = new wijmo.input.InputDate('#idcInputDate'); var calendar = new wijmo.input.Calendar('#idcCalendar'); var today = new Date(); var minDate = new Date(today.getFullYear(), 0, 1); var maxDate = new Date(today.getFullYear(), 11, 31); var format = 'MMM d, yyyy'; inputDate.value = today; inputDate.min = minDate; inputDate.max = maxDate; calendar.value = today; calendar.min = minDate; calendar.max = maxDate; // set current date range values below the example document.getElementById('idcMinDate').innerHTML = wijmo.Globalize.format(minDate, format); document.getElementById('idcMaxDate').innerHTML = wijmo.Globalize.format(maxDate, format);

Result (live):

Valid Range: to

InputDate & InputTime

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 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 DateTime JavaScript Object and only update the part of the DateTime that they are responsible for.

<div> <label>Bound InputDate with min, max, &amp; format</label> <input id="iditInputDate" type="text" /> </div> <div> <label>Bound InputTime with min, max, &amp; step</label> <input id="iditInputTime" type="text" /> </div>
var inputDate = new wijmo.input.InputDate('#iditInputDate'); var inputTime = new wijmo.input.InputTime('#iditInputTime'); var today = new Date(); var minDate = new Date(today.getFullYear(), 0, 1); var maxDate = new Date(today.getFullYear(), 11, 31); var minTime = new Date(0, 0, 0, 7, 0, 0, 0); var maxTime = new Date(0, 0, 0, 19, 0, 0, 0); inputTime.valueChanged.addHandler(valueChanged); inputDate.valueChanged.addHandler(valueChanged); inputDate.value = today; inputDate.min = minDate; inputDate.max = maxDate; inputDate.format = 'MMM dd, yyyy'; inputTime.value = today; inputTime.min = minTime; inputTime.max = maxTime; inputTime.step = 15; // valueChanged event handler function valueChanged() { // get new date from the two controls using Wijmo utility functions var val = wijmo.DateTime.fromDateTime(inputDate.value, inputTime.value); // format and display the new date document.getElementById('iditSelectedValue').innerHTML = wijmo.Globalize.format(val, 'MMM dd, yyyy h:mm:ss tt'); }

Result (live):

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> <div id="lbListBox" style="height:150px;width:250px;"></div> </div> <p> <b>selectedIndex: <span id="lbSelIdx"></span></b> </p> <p> <b>selectedValue: <span id="lbSelVal"></span></b> </p>
var listBox = new wijmo.input.ListBox('#lbListBox'); listBox.selectedIndexChanged.addHandler(selectedIndexChanged); listBox.itemsSource = data.cities; // selectedIndexChanged event handler function selectedIndexChanged(sender) { // set selectedIndex and selectedValue text document.getElementById('lbSelIdx').innerHTML = sender.selectedIndex; document.getElementById('lbSelVal').innerHTML = sender.selectedValue; }

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:

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

<div> <label>Unbound with "n0" format</label> <input id="inInputNumber1" type="text" /> </div> <div> <label>Bound with "n" format</label> <input id="inInputNumber2" type="text" /> </div> <div> <label>Bound with min (0), max (10), step, and "c2" format</label> <input id="inInputNumber3" type="text" /> </div> <div> <label>Unbound with placeholder and required="false"</label> <input id="inInputNumber4" type="text" /> </div>
var inputNumber1 = new wijmo.input.InputNumber('#inInputNumber1'); var inputNumber2 = new wijmo.input.InputNumber('#inInputNumber2'); var inputNumber3 = new wijmo.input.InputNumber('#inInputNumber3'); var inputNumber4 = new wijmo.input.InputNumber('#inInputNumber4'); inputNumber1.value = 0; inputNumber1.format = 'n0'; inputNumber2.value = Math.PI; inputNumber2.format = 'n'; inputNumber3.value = 3.5; inputNumber3.format = 'c2'; inputNumber3.step = 0.5; inputNumber3.min = 0; inputNumber3.max = 10; inputNumber4.placeholder = 'Enter a number...'; inputNumber4.required = false; inputNumber4.value = null;

Result (live):

InputMask

The InputMask control allows you to validate and format user input as it is entered, preventing invalid data. The InputMask control can be used without specifying any of its properties; however, you will typically set its value and mask properties. Like the other Wijmo input controls, the value property specifies the value for the InputMask control. The mask property specifies the control's mask and supports a combination of the following characters:

0
Digit.
9
Digit or space.
#
Digit, sign, or space.
L
Letter.
l
Letter or space.
A
Alphanumeric.
a
Alphanumeric or space.
.
Localized decimal point.
,
Localized thousand separator.
:
Localized time separator.
/
Localized date separator.
$
Localized currency symbol.
<
Converts characters that follow to lowercase.
>
Converts characters that follow to uppercase.
|
Disables case conversion.
\
Escapes any character, turning it into a literal.
All others
Literals.

The examples below demonstrates how to use the value and mask properties with the InputMask, InputDate, and InputTime controls.

<div> <label>Social Security Number</label> <input id="imSocial" type="text" title="Mask: 000-00-0000" /> </div> <div> <label>Phone Number</label> <input id="imPhone" type="text" title="Mask: (999) 000-0000" /> </div> <div> <label>Try your own</label> <input id="imCustomInput" type="text" /> <input id="imCustomTrial" type="text" /> </div> <div> <label>InputDate with Mask</label> <input id="imInputDate" type="text" title="Mask: 99/99/9999" /> </div> <div> <label>InputTime with Mask</label> <input id="imInputTime" type="text" title="Mask: 00:00 >LL" /> </div>
var socialSecurity = new wijmo.input.InputMask('#imSocial'), phoneNumber = new wijmo.input.InputMask('#imPhone'), customMaskInput = new wijmo.input.InputMask('#imCustomInput'), customMaskTrial = new wijmo.input.InputMask('#imCustomTrial'), inputDate = new wijmo.input.InputDate('#imInputDate'), inputTime = new wijmo.input.InputTime('#imInputTime'), today = new Date(); socialSecurity.mask = '000-00-0000'; phoneNumber.mask = '(999) 000-0000'; // valueChanged event handler customMaskInput.valueChanged.addHandler(function(sender) { customMaskTrial.mask = sender.value; customMaskTrial.hostElement.title = 'Mask: ' + (sender.value || 'N/A'); }); customMaskInput.required = false; customMaskInput.placeholder = 'Enter an input mask...'; customMaskInput.value = null; customMaskTrial.required = false; customMaskTrial.placeholder = 'Try your input mask...'; inputDate.value = today; inputDate.format = 'd'; inputDate.mask = '99/99/9999'; inputTime.value = today; inputTime.format = 't'; inputTime.step = 15; inputTime.isEditable = true; inputTime.mask = '00:00 >LL';

Result (live):

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:

The example below demonstrates how to use both approaches.

<div> <label>itemClicked Event</label> <select id="mFileMenu"> <option>New: create a new document</option> <option>Open: load an existing document from a file</option> <option>Save: save the current document to a file</option> <option></option> <option>Exit: save changes and exit the application</option> </select> <select id="mEditMenu"> <option>Cut: move the current selection to the clipboard</option> <option>Copy: copy the current selection to the clipboard</option> <option>Paste: insert the clipboard content at the cursor position</option> <option></option> <option>Find: search the current document for some text</option> <option>Replace: replace occurrences of a string in the current document</option> </select> <div> <label>Commands</label> <select id="mCmdMenu"> <option cmd-param=".25">+ 25%</option> <option cmd-param=".10">+ 10%</option> <option cmd-param=".05">+ 5%</option> <option cmd-param=".01">+ 1%</option> <option></option> <option cmd-param="-.01">- 1%</option> <option cmd-param="-.25">- 25%</option> <option cmd-param="-.05">- 5%</option> <option cmd-param="-.10">- 10%</option> </select> <input id="mInputNumber" type="text" /> </div>
var fileMenu = new wijmo.input.Menu('#mFileMenu'); var editMenu = new wijmo.input.Menu('#mEditMenu'); var cmdMenu = new wijmo.input.Menu('#mCmdMenu'); var inputNumber = new wijmo.input.InputNumber('#mInputNumber'); fileMenu.header = 'File'; fileMenu.itemClicked.addHandler(itemClicked); editMenu.header = 'Edit'; editMenu.itemClicked.addHandler(itemClicked); cmdMenu.header = 'Change Tax'; // set command object for the command menu cmdMenu.command = { executeCommand: function (arg) { // convert argument to Number arg = wijmo.changeType(arg, wijmo.DataType.Number); // check if the conversion was successful if (wijmo.isNumber(arg)) { // update the value inputNumber.value += arg; } }, canExecuteCommand: function (arg) { // convert argument to Number arg = wijmo.changeType(arg, wijmo.DataType.Number); // check if the conversion was successful if (wijmo.isNumber(arg)) { var val = inputNumber.value + arg; // check if the value is valid return val >= 0 && val <= 1; } return false; } }; inputNumber.value = 0.07; inputNumber.step = 0.05; inputNumber.format = 'p0'; inputNumber.min = 0; inputNumber.max = 1; // itemClicked event handler for File and Edit menus function itemClicked(sender) { alert('You\'ve selected option ' + sender.selectedIndex + ' from the ' + sender.header + ' menu!'); }

Result (live):