Wijmo

Input 101

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

Getting Started

Steps for getting started with Input controls in AngularJS applications:

  1. Add references to AngularJS, Wijmo, and Wijmo's AngularJS directives.
  2. Include the Wijmo directives in the app module:
    var app = angular.module('app', ['wj']);
  3. Add a controller to provide data and logic.
  4. Add a Wijmo Input control to the page and bind it to your data.
  5. (Optional) Add some CSS to customize the input control's appearance.
HTML
<!DOCTYPE html> <html> <head> <link rel="stylesheet" href="css/bootstrap.css"/> <link rel="stylesheet" href="css/wijmo.css"/> <link href="css/app.css" rel="stylesheet"/> <script src="scripts/angular.js"></script> <script src="scripts/wijmo.js"></script> <script src="scripts/wijmo.input.js"></script> <script src="scripts/wijmo.angular.js"></script> <script src="scripts/app.js"></script> </head> <body ng-app="app" ng-controller="appCtrl"> <!-- this is the InputNumber directive --> <wj-input-number value="someValue" format="n2" step=".5"> </wj-input-number> </body> </html>
JS
// declare app module var app = angular.module('app', ['wj']); // app controller provides data app.controller('appCtrl', function appCtrl($scope) { // value to bind to $scope.someValue = 3.5; });

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.

HTML
<div> <label>itemsSource Only</label> <wj-auto-complete items-source="countries"> </wj-auto-complete> </div> <div> <label>itemsSource &amp; cssMatch</label> <wj-auto-complete items-source="countries" css-match="highlight"> </wj-auto-complete> </div>
CSS
.highlight { background-color: #ff0; color: #000; }

Result (live):

MultiAutoComplete

The MultiAutoComplete control allows users to pick items from lists that contain custom objects or simple strings.

To use the MultiAutoComplete control, you must set the itemsSource property to an array containing the data used to populate its item list.

User can set the maxSelectedItems property to limit the maximum number of items that can be selected.

HTML
<div> <label>maxSelectedItems setting is 4</label> <wj-multi-auto-complete control="mac1" items-source="countries" max-selected-items="4" selected-items="selectedCountries" placeholder="country"> </wj-multi-auto-complete> <ol> <li ng-repeat="item in selectedCountries"> {​{item}} </li> </ol> </div>
JS
$scope.selectedCountries = ['Belgium', 'Vietnam'];

Result (live):

  1. {{item}}

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.

HTML
<div> <label>Non-Editable</label> <wj-combo-box items-source="countries" is-editable="false"> </wj-combo-box> </div> <div> <label>Editable</label> <wj-combo-box items-source="countries" is-editable="true"> </wj-combo-box> </div>

Result (live):

InputDate and 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 these properties.

In addition to these basic properties, the Calendar control has a formatItem event that you can use to customize the display of specific days in the calendar. The sample below uses this event to customize the appearance of weekends and holidays.

HTML
<div> <label>Bound InputDate with min &amp; max</label> <wj-input-date value="today" min="{​{ minDate | date:'yyyy-MM-dd' }}" max="{​{ maxDate | date:'yyyy-MM-dd' }}"> </wj-input-date> </div> <div> <label>Bound Calendar with min &amp; max</label> <wj-calendar style="width:300px;" value="today" min="{​{ minDate | date:'yyyy-MM-dd' }}" max="{​{ maxDate | date:'yyyy-MM-dd' }}" format-item="formatItem(s,e)"> </wj-calendar> </div> <p> <b>Selected Date: {​{ today | date }}</b> </p> <p> <b>Valid Range: {​{ minDate | date }} to {​{ maxDate | date }}</b> </p>
JS
// apply special styles to weekends and holidays var today = new Date(); $scope.today = today; $scope.minDate = new Date(today.getFullYear(), 0, 1); $scope.maxDate = new Date(today.getFullYear(), 11, 31); // apply special styles to weekends and holidays $scope.formatItem = function (s, e) { var weekday = e.data.getDay(), holiday = getHoliday(e.data); wijmo.toggleClass(e.item, 'date-weekend', weekday == 0 || weekday == 6); wijmo.toggleClass(e.item, 'date-holiday', holiday); e.item.title = holiday; } // gets the holiday for a given date function getHoliday(date) { var day = date.getDate(), month = date.getMonth() + 1; switch (month + '/' + day) { // simple holidays (fixed dates) case '1/1': return 'New Year\'s Day'; case '6/14': return 'Flag Day'; case '7/4': return 'Independence Day'; case '11/11': return 'Veteran\'s Day'; case '12/25': return 'Christmas Day'; } var weekDay = date.getDay(), weekNum = Math.floor((day - 1) / 7) + 1; switch (month + '/' + weekNum + '/' + weekDay) { case '1/3/1': return 'Martin Luther King\'s Birthday'; // third Monday in January case '2/3/1': return 'Washington\'s Birthday'; // third Monday in February case '5/3/6': return 'Armed Forces Day'; // third Saturday in May case '9/1/1': return 'Labor Day'; // first Monday in September case '10/2/1': return 'Columbus Day'; // second Monday in October case '11/4/4': return 'Thanksgiving Day'; // fourth Thursday in November } return ''; // no holiday today }
CSS
.wj-calendar .date-holiday { /* holidays in calendar */ color: #008f22; outline: 2px solid #008f22; } .wj-calendar .date-weekend:not(.wj-state-selected) { /* weekends in calendar */ background-color: #d8ffa6; }

Result (live):

Selected Date: {{ today | date }}

Valid Range: {{ minDate | date }} to {{ maxDate | date }}

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 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.

HTML
<div> <label>Bound InputDate with min, max, &amp; format</label> <wj-input-date value="today" min="{​{ minDate | date:'yyyy-MM-dd' }}" max="{​{ maxDate | date:'yyyy-MM-dd' }}" format="MMM dd, yyyy"> </wj-input-date> </div> <div> <label>Bound InputTime with min, max, &amp; step</label> <wj-input-time value="today" step="15" min="09:00" max="17:00"> </wj-input-time> </div> <p> <b>Selected Date &amp; Time: {​{ today | date: 'medium' }}</b> </p> <div> <label>Bound InputDateTime with min, max, format, and step</label> <wj-input-date-time value="today" format="MMM dd, yyyy hh:mm tt" min="{​{ minDate | date:'yyyy-MM-dd' }}" max="{​{ maxDate | date:'yyyy-MM-dd' }}" time-step="15" time-min="09:00" time-max="17:00"> </wj-input-date-time> </div>
JS
var today = new Date(); $scope.today = new Date(today.getFullYear(), today.getMonth(), today.getDate(), 13, 30); $scope.minDate = new Date(today.getFullYear(), 0, 1); $scope.maxDate = new Date(today.getFullYear(), 11, 31);

Result (live):

Selected Date & Time: {{ today | date: 'medium' }}

InputDate and Validation

The InputDate control automatically parses dates typed in by the user using the format specified by the format property. Invalid dates are ignored and the original value is preserved. The InputDate control also checks the range and ensures that date values are between the values specified by the min and max properties.

But in many cases, not all dates between the min and max properties are valid. For example, you may be creating an appointment scheduler application and want to ensure that users don't schedule appointments for weekends, holidays, or dates that already have a certain number of appointments scheduled.

To handle these situations, the InputDate (and the Calendar) have an itemValidator property. This property represents a function that takes a date as a parameter and returns true if the date is valid for selection, or false otherwise. Invalid dates will automatically be disabled and users will not be able to select them in the calendar or to enter them by typing.

The example below demonstrates this with an InputDate that has an itemValidator function that returns false for weekends and US federal holidays. The example also uses an itemFormatter function to add some special formatting and a tooltip with the name of the holidays.

HTML
<div class="app-input-group"> <label>Select a date that is not a weekend or a holiday:</label> <wj-input-date value="theDate" item-formatter="itemFormatter" item-validator="itemValidator"> </wj-input-date> </div> <p> <b>Selected Date: {{ theDate | date }}</b> </p>
JS
$scope.itemFormatter = function (date, element) { var weekday = date.getDay(), holiday = getHoliday(date); wijmo.toggleClass(element, 'date-weekend', weekday == 0 || weekday == 6); wijmo.toggleClass(element, 'date-holiday', holiday); element.title = holiday; } $scope.itemValidator = function (date, element) { switch (date.getDay()) { case 0: case 6: return false; // no appointments on weekends } if (getHoliday(date)) { return false; // no appointments on holidays } return true; // not a weekend or a holiday, this date is OK } // gets the holiday for a given date function getHoliday(date) { var day = date.getDate(), month = date.getMonth() + 1; switch (month + '/' + day) { // simple holidays (fixed dates) case '1/1': return 'New Year\'s Day'; case '6/14': return 'Flag Day'; case '7/4': return 'Independence Day'; case '11/11': return 'Veteran\'s Day'; case '12/25': return 'Christmas Day'; } var weekDay = date.getDay(), weekNum = Math.floor((day - 1) / 7) + 1; switch (month + '/' + weekNum + '/' + weekDay) { case '1/3/1': return 'Martin Luther King\'s Birthday'; // 3rd Mon/Jan case '2/3/1': return 'Washington\'s Birthday'; // 3rd Mon/Feb case '5/3/6': return 'Armed Forces Day'; // 3rd Sat/May case '9/1/1': return 'Labor Day'; // 1st Mon/Sep case '10/2/1': return 'Columbus Day'; // 2nd Mon/Oct case '11/4/4': return 'Thanksgiving Day'; // 4th Thu/Nov } return ''; // no holiday today }
CSS
.wj-calendar .date-holiday { color: #008f22; outline: 2px solid #008f22; }

Result (live):

Selected Date: {{ theDate | date }}

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.

An arbitrary item content can be optionally defined using the wj-item-template directive, where the $item and $itemIndex variables representing a data item and its index respectively can be used in Angular bindings.

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

HTML
<wj-list-box style="height:150px;width:250px;" items-source="cities" control="listBox"> </wj-list-box> <p> <b>selectedIndex: {​{listBox.selectedIndex}}</b> </p> <p> <b>selectedValue: {​{listBox.selectedValue}}</b> </p>

Result (live):

selectedIndex: {{listBox.selectedIndex}}

selectedValue: {{listBox.selectedValue}}

This second example demonstrates how you can use templates to populate ListBox controls. It uses an item template to show items with a complex layout, including images when available.

HTML
<wj-list-box style="max-height:300px;width:250px;" items-source="musicians"> <wj-item-template> {​{$itemIndex + 1}}. <b>{​{$item.name}}</b> <div ng-if="$item.photo"> <img ng-src="{​{$item.photo}}" height="100" /> <br /> <a href="https://www.google.ru/#newwindow=1&q=The+Beatles+{​{$item.name}}" target="_blank" style="color:red">go there!</a> </div> </wj-item-template> </wj-list-box>

Result (live):

{{$itemIndex + 1}}. {{$item.name}}

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.

HTML
<div> <label>Unbound with "n0" format</label> <wj-input-number format="n0"> </wj-input-number> </div> <div> <label>Bound with "n" format</label> <wj-input-number value="pi" format="n"> </wj-input-number> </div> <div> <label>Bound with min (0), max (10), step, and "c2" format</label> <wj-input-number value="price" format="c2" step=".5" min="0" max="10"> </wj-input-number> </div> <div> <label>Unbound with placeholder and isRequired="false"</label> <wj-input-number placeholder="Enter a number..." is-required="false" value="nullVal"> </wj-input-number> </div>
JS
$scope.pi = Math.PI; $scope.price = 3.5; $scope.nullVal = 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.

HTML
<div> <label>Social Security Number</label> <wj-input-mask mask="000-00-0000" title="Mask: 000-00-0000"> </wj-input-mask> </div> <div> <label>Phone Number</label> <wj-input-mask mask="(999) 000-0000" title="Mask: (999) 000-0000"> </wj-input-mask> </div> <div> <label>Try your own</label> <wj-input-mask value="customMask" is-required="false" placeholder="Enter an input mask..."> </wj-input-mask> <wj-input-mask mask="{​{ customMask }}" title="Mask: {​{ customMask || 'N/A' }}"> </wj-input-mask> </div> <div> <label>InputDate with mask</label> <wj-input-date value="maskToday" format="MM/dd/yyyy" mask="99/99/9999" title="Mask: 99/99/9999"> </wj-input-date> </div> <div> <label>InputTime with mask</label> <wj-input-time value="maskToday" format="hh:mm tt" is-editable="true" step="15" mask="00:00 >LL" title="Mask: 00:00 >LL"> </wj-input-time> </div>
JS
$scope.customMask = null; $scope.maskToday = today;

Result (live):

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.

HTML
<div> <label>itemClicked Event</label> <wj-menu header="File" item-clicked="menuItemClicked(s)"> <wj-menu-item><i class="fa fa-file-o"></i>&nbsp;&nbsp;<b>New</b><br><small><i>create a new file</i></small></wj-menu-item> <wj-menu-item><i class="fa fa-folder-open-o"></i>&nbsp;&nbsp;<b>Open</b><br><small><i>open an existing file or folder</i></small></wj-menu-item> <wj-menu-item><i class="fa fa-save"></i>&nbsp;&nbsp;<b>Save</b><br><small><i>save the current file</i></small></wj-menu-item> <wj-menu-separator></wj-menu-separator> <wj-menu-item><i class="fa fa-times"></i>&nbsp;&nbsp;<b>Exit</b><br><small><i>exit the application</i></small></wj-menu-item> </wj-menu> <wj-menu header="Edit" item-clicked="menuItemClicked(s)"> <wj-menu-item><i class="fa fa-cut"></i>&nbsp;&nbsp;<b>Cut</b><br><small><i>move the current selection to the clipboard</i></small></wj-menu-item> <wj-menu-item><i class="fa fa-copy"></i>&nbsp;&nbsp;<b>Copy</b><br><small><i>copy the current selection to the clipboard</i></small></wj-menu-item> <wj-menu-item><i class="fa fa-paste"></i>&nbsp;&nbsp;<b>Paste</b><br><small><i>insert clipboard content at the cursor position</i></small></wj-menu-item> </wj-menu> </div> <div> <label>Commands</label> <wj-menu header="Change Tax"> <wj-menu-item cmd="menuCommand" cmd-param=".25">+ 25%</wj-menu-item> <wj-menu-item cmd="menuCommand" cmd-param=".10">+ 10%</wj-menu-item> <wj-menu-item cmd="menuCommand" cmd-param=".05">+ 5%</wj-menu-item> <wj-menu-item cmd="menuCommand" cmd-param=".01">+ 1%</wj-menu-item> <wj-menu-separator></wj-menu-separator> <wj-menu-item cmd="menuCommand" cmd-param="-.01">- 1%</wj-menu-item> <wj-menu-item cmd="menuCommand" cmd-param="-.05">- 5%</wj-menu-item> <wj-menu-item cmd="menuCommand" cmd-param="-.10">- 10%</wj-menu-item> <wj-menu-item cmd="menuCommand" cmd-param="-.25">- 25%</wj-menu-item> </wj-menu> <wj-input-number value="tax" format="p0" min="0" max="1" step=".05"></wj-input-number> </div>
JS
$scope.tax = .07; $scope.menuItemClicked = function(menu) { alert('You\'ve selected option ' + menu.selectedIndex + ' from the ' + menu.header + ' menu!'); }; $scope.menuCommand = { executeCommand: function (arg) { $scope.tax += arg; }, canExecuteCommand: function (arg) { if (wijmo.isNumber(arg)) { var val = $scope.tax + arg; return val >= 0 && val <= 1; } return false; } };

Result (live):

  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
+ 25% + 10% + 5% + 1% - 1% - 5% - 10% - 25%

The Popup control can be used to display arbitrary content as dialogs (AKA modals, centered on the screen, without an owner element), or as popups (AKA popovers, located relative to an owner element).

Dialogs

Click the buttons below to see dialogs:

HTML
<p> Click to see a modal dialog: <button type="button" class="btn" ng-click="modalDialog.show()"> Click </button> </p> <wj-popup control="modalDialog" modal="true" hide-trigger="None"> <ng-include src="'includes/dialog.htm'"></ng-include> </wj-popup> <p> Click to see a modeless dialog: <button type="button" class="btn" ng-click="modelessDialog.show()"> Click </button> </p> <wj-popup control="modelessDialog" modal="false"> <ng-include src="'includes/dialog.htm'"></ng-include> </wj-popup>
JS
// no code required

Click to see a modal dialog:

Click to see a modeless dialog:

Popups/popovers

Click the buttons below to see popovers:

HTML
<p> Click to open, move focus away to close: <button id="btn1" type="button" class="btn"> Click </button> </p> <wj-popup class="popover" owner="#btn1" show-trigger="Click" hide-trigger="Blur"> <ng-include src="'includes/popup.htm'"></ng-include> </wj-popup> <p> Click to open, click again to close: <button id="btn2" type="button" class="btn"> Click </button> </p> <wj-popup class="popover" owner="#btn2" show-trigger="Click" hide-trigger="Click"> <ng-include src="'includes/popup.htm'"></ng-include> </wj-popup> <p> Click to open, click close button on popup to close: <button id="btn3" type="button" class="btn"> Click </button> </p> <wj-popup class="popover" owner="#btn3" show-trigger="Click" hide-trigger="None"> <ng-include src="'includes/popup.htm'"></ng-include> </wj-popup>
JS
// no code required

Click to open, move focus away to close:

Click to open, click again to close:

Click to open, click close button on popup to close: