Version

Migrating to the new igDatePicker

With the 15.2 release of Ignite UI for jQuery™ a new set of editor controls were introduced including a reworked igDatePicker. With a new design focused on simplicity and better UX out-of-the-box some features and their API were revised, removed and new ones added. This topic will cover the differences that will be helpful for developers migrating their applications to the new editors.

Topic overview

This topic aims to help with migration from old date picker to the new one. Different scenarios are viewed and how they were done before and how they can be done now.

In this topic

This topic contains the following sections:

  1. Options changes
  2. New options
  3. API Methods changes
  4. New API methods
  5. Event changes
  6. New events
  7. Requirements

Options changes

API Options changes

Option Previously Now
animationHideDuration animationShowDuration Used to set animation duration when dropdown list is displayed/hidden.
$(".selector").igDatePicker({
animationShowDuration: 500,
animationHideDuration: 500
});
These options are replaced by new option dropDownAnimationDuration that controls the dropdown list animation duration.
$(".selector").igDatePicker({
dropDownAnimationDuration: 500
});
button This option was used to set visibility of spin and dropdown button.
$(".selector").igDatePicker({
button : "dropdown"
});
This option is renamed to buttonType to better communicate what it does.
$(".selector").igDatePicker({
buttonType : "dropdown"
});
display Sets gets style.display for outer html element. This option is removed.
dropDownTriggers Sets gets list of actions which trigger display of drop-down list or calendar. This option is removed. Now Alt+ shows dropdown.
focusOnSpin If that option was disabled and the editor was not focused, then a mouse click on the spin button would keep the text in the editor in not focused format and perform spin actions. This option is removed. Now if the editor is not focused, then a mouse click on the spin button will not focus the editor.
focusOnDropDownOpen Sets gets ability to automatically focus the input, when a calendar is opened. This option is no longer avaliable for the igDatePicker.
height, width Previously supported type: number.
$(".selector").igDatePicker({
width : 200
});
Now supported types are: number, string, null. If using type string, the height can be set in pixels (px) and percentage (%).
$(".selector").igDatePicker({
width : "200px"
});
hideEnterKey Sets gets ability to hide the Enter key from browser.
$(".selector").igDatePicker({
hideEnterKey : false
});
This option is removed. You can use preventSubmitOnEnter option to prevent submitting when pressing Enter.
$(".selector").igDatePicker({
preventSubmitOnEnter : true
});
listAutoComplete Sets gets autocomplete. This option is removed.
listColumns Sets gets number of columns in drop-down list. This option is removed.
listDropDownAsChild Value true created html element for list as a child of main html element. Value false created list as a child of body.
$(".selector").igDatePicker({
listDropDownAsChild : true
});
Renamed to dropDownAttachedToBody. Value true creates list as a child of body. Value false will create html element for list as a child of main html element.
$(".selector").igDatePicker({
dropDownAttachedToBody : true
});
listMatchContains Sets gets list match contains. This option is removed.
listMatchIgnoreCase Sets gets case validation. This option is removed.
listMaxHeight Used to set maximum height of dropdown list in pixels.
$(".selector").igDatePicker({
listMaxHeight : 400
});
This option is removed. You can use the new option visibleItemsCount to set the number of visible list items.
$(".selector").igDatePicker({
visibleItemsCount : 5
});
nullText Used to set text which appears in editor when editor has no focus and "value" in editor is null or empty string.
$(".selector").igDatePicker({
nullText : "Enter Value"
});
This option is renamed to placeHolder to better communicate what it does.
$(".selector").igDatePicker({
placeHolder : "Enter Value"
`});
renderInContainer Sets gets option to wrap input field into SPAN. This option is removed.
required Set gets validation for empty value in editor.
$(".selector").igDatePicker({
required : true
});
This options is removed. You can use the validator options to set the field as required.
$(".selector").igDatePicker({
validatorOptions : {
required: true
}
});
selectionOnFocus Previously supported members: select, -1, start, 0, end, 1, default, 2.
$(".selector").igDatePicker({
selectionOnFocus: 0
});
Now supported members are: selectAll, atStart, atEnd, browserDefault. The default value is selectAll.
$(".selector").igDatePicker({
selectionOnFocus: "atStart"
});
spin1Field Sets gets ability to modify only 1 date field on spin events.
$(".selector").igDatePicker({
spin1Field : true
});
This option is renamed to limitSpinToCurrentField.
$(".selector").igDatePicker({
limitSpinToCurrentField : true
});
spinOnReadOnly This was used to override the "readOnly" option and allow changing "value" of editor on spin events.
$(".selector").igDatePicker({
spinOnReadOnly : true
});
This option is removed. Setting readOnly to true disables the spin buttons.
$(".selector").igDatePicker({
readOnly : true
});
textAlign Default was null Now default is left.
theme Sets gets selector for css classes used by editor. This option is removed.
type Sets type of editor. This option is removed. You can use the corresponding controls.

New options

Option Description
limitSpinToCurrentField Sets gets ability to modify only 1 date field on spin events.
allowNullValue If that option is false, and editor has no value, then value is set to an empty string.
disabled Use to set the disabled attribute. Does not allow editing. Disables all the buttons and iteracitons applied. On submit the current value is not sent into the request: $('#datePicker').igDatePicker({ disabled: true }).
buttonType Sets gets visibility of spin, clear and drop-down button.
dropDownAttachedToBody Gets sets location of drop-down list.
dropDownAnimationDuration Gets sets show/hide drop-down list animation duration in milliseconds.
placeHolder Gets sets text which appears in editor when editor has no focus and "value" in editor is null or empty string.
revertIfNotValid Use to set the editor to revert value to previous value in case of not valid value on blur, or enter key. If set to false clear is called.
preventSubmitOnEnter Use to set the ability of the editor to prevent form submition on enter key pressed: $('#datePicker').igDatePicker({ preventSubmitOnEnter: true }).
dropDownOrientation Use to set drop down opening orientation for the dorp down list when open button is clicked.
suppressNotifications Disables default notifications for basic validation scenarios built in the editors such as required list selection, value wrapping around or spin limits.

See all options

API Methods changes

Method Previously Now
addListItem Used to add the object within item at the location indicated by the index. This method is removed.
addListItems Used to add the objects within the items array at the location indicated by the index. This method is removed.
clearListItems Removed all items from list. This method is removed.
dropDownElement Got reference to jquery object which is used as container of dropdown. This method is removed.
findListItemIndex Found index of list item by text that matches with the search parameters. This method is removed.
getRegionalOption Gets calculated value of regional option used by numeric and date editors. This method in no longer available.
getSelection Used to get left or right edge of selection. This method is replaced by the methods getSelectionStart and getSelectionEnd.
getValueByMode Used to get value in editor by dataMode. This method is not supported.
hasInvalidMessage Used to check if invalid message is displayed. This method is removed as its` functionality is covered by the API for the igNotifier.
mainElement Used to get reference to jquery object which is used as top/outer element of igDatePicker. This method is renamed to editorContainter to better communicate what it does.
paste Used to paste text at location of caret. This is renamed to insert and the txt parameter is renamed to string as it is a string of characters.
remove This was used to remove editor from its parent element, but keeps the rest of functionality. This method is not supported.
removeListItem Used to remove item from list. This method is removed.
removeListItemAt Used to remove item from list at index. This method is removed.
select Used to select text in editor. Valid parameters: sel0, sel1, val sel0 is renamed to start and sel1 is renamed to end to prevent exchanging the two parameters.
setFocus Used to set focus to editor with delay. If parameter was -1, then focus was set without delay. It now supports only positive values for the delay and 0 is default that signifies that it is immediately given the focus.
spin Used to increment (positive delta) or decrement (negative delta) value in editor according to the parameter. This method is replaced by two new methods: spinUp and spinDown.
text Used to get or set text in editor. This is replaced by a getter method displayValue that takes no parameters and returns a string with all the characters shown in the input.
validate Used to trigger validation of editor and show error message. It had a single parameter: noLabel The parameter is renamed to skipErrorMessage.
value Used to get or set value in editor. The parameter is renamed to newValue to better communicate what it does.

New API Methods

Method Description
getSelectedDate Gets selected date.
selectDate Sets selected date.
getCalendar Returns a reference to the jQuery calendar used as a picker selector.
inputName Gets sets name attribute applied to the editor element.
displayValue Returns a string with all the characters shown in the input.
editorContainer Gets reference to jquery object which is used as top/outer element of igEditor.
showDropDown Show the dropdown list.
hideDropDown Hide the dropdown list.
dropDownVisible Returns the visibility state of the drop down listing the items.
dropDownButton Returns a reference to the dropdown button of the editor.
clearButton Returns a reference to the clear button of the editor.
getSelectionStart Gets start index of the selected text in editor.
getSelectionEnd Gets end index of the selected text in editor.
insert Paste text at location of caret.
spinUp Increase date-time period, depending on the cursor position.
spinDown Decrease date-time period, depending on the cursor position.
spinUpButton Returns a reference to the spin up button of the editor.
spinDownButton Returns a reference to the spin down button of the editor.

See all API methods

Event changes

Event Changes
hideDropDown Event is not supported anymore. Two new events are introduced, giving you more control over hiding the dropdown list: dropDownListClosed and the jQuery UI datepicker onClose function can also be used through datepickerOptions.
showDropDown Event is not supported anymore. Two new events are introduced, giving you more control over showing the dropdown list: dropDownListOpening and dropDownListOpened.
listSelected Event is renamed to itemSelected to better communicate what it does. Use ui.owner to obtain reference to igEditor. Use ui.editorInput to obtain reference to the editable input. Use ui.calendar to obtain reference to the jQuery UI date picker, used as a calendar from the igDatePicker. Use ui.dateFromPicker or ui.item to obtain reference to the item which is selected. The jQuery UI datepicker onSelect function can also be used through datepickerOptions.
listSelecting Event is not supported anymore.
mouseleave Event is renamed to mouseout to better communicate what it does.

New events

Event Description
rendering Event which is raised before rendering of the editor completes.
rendered Event which is raised after rendering of the editor completes.
dropDownListOpening Event which is raised when the drop down is opening.
dropDownListOpened Event which is raised when the drop down is already opened.
dropDownListClosed Event which is raised when the drop down is already closed.
mouseout Event which is raised on mouseleave at any part of editor including drop-down list.

See all events

jQuery requirements

Lib Prev required version New required version
jQuery core 1.4.4 1.9.1
jQuery UI 1.7 1.9.0

View on GitHub