Version

igDateEditor Overview

The Ignite UI™ date editor, or igDateEditor, is a control that renders an input field, which allows users to edit date formatted data. The igDateEditor control supports localization and different regional options.

The igDateEditor control exposes a rich client-side API, which can be configured to work with any server technology. While the Ignite UI™ controls are server-agnostic, the control does feature wrappers specific for the Microsoft® ASP.NET MVC Framework to configure the control with the .NET™ language of your choice.

The igDateEditor control may be extensively styled giving you an opportunity to provide a completely different look and feel for the control as opposed to the default style. Styling options include using your own styles as well as styles from jQuery UI’s ThemeRoller.

Note: One of the major changes in the new date editor is that it no longer supports Lists and DropDown. Note that if you try to use methods related to dropdown and list, you will receive a notification pointing out that they are no longer available.

Figure 1: The igDateEditor rendered to the user

Features

The igDateEditor includes the following characteristics:

Adding igDateEditor to a Web Page

  1. To get started, include the required and localized resources for your application. Details on which resources to include can be found in the Using JavaScript Resources in Ignite UI help topic.
  2. On your HTML page or ASP.NET MVC View, reference the required JavaScript files, CSS files, and ASP.NET MVC assemblies.

    In HTML:

    <link type="text/css" href="/css/themes/infragistics/infragistics.theme.css" rel="stylesheet" />
    <link type="text/css" href="/css/structure/infragistics.css" rel="stylesheet" />
    <script type="text/javascript" src="/Scripts/jquery.min.js"></script>
    <script type="text/javascript" src="/Scripts/jquery-ui.min.js"></script>
    <script type="text/javascript" src="/Scripts/Samples/infragistics.core.js"></script>
    <script type="text/javascript" src="/Scripts/Samples/infragistics.lob.js"></script>
    

    In Razor:

    @using Infragistics.Web.Mvc;
    
    <link type="text/css" href="@Url.Content("~/css/themes/infragistics/infragistics.theme.css")" rel="stylesheet" />
    <link type="text/css" href="@Url.Content("~/css/structure/infragistics.css")" rel="stylesheet" />
    
    <script type="text/javascript" src="@Url.Content("~/Scripts/jquery-1.9.1.min.js")"></script>
    <script type="text/javascript" src="@Url.Content("~/Scripts/jquery-ui.min.js")"></script>
    <script type="text/javascript" src="@Url.Content("~/Scripts/Samples/infragistics.core.js")"></script>
    <script type="text/javascript" src="@Url.Content("~/Scripts/Samples/infragistics.lob.js")"></script>
    <script type="text/javascript" src="@Url.Content("~/Scripts/Samples/modules/i18n/regional/infragistics.ui.regional-en.js")"></script>
    
  3. For jQuery implementations, create an INPUT, DIV or SPAN as the target element in HTML. This step is optional for ASP.NET MVC implementations as the MVC wrapper creates the containing element for you.

    In HTML:

    <input id="dateEditor"/>
    
  4. Once the above setup is complete, initialize the date editor.

    Note: For the ASP.NET MVC Views, the Render method must be called after all other options are set.

    In Javascript:

     <script type="text/javascript">
           $('#dateEditor').igDateEditor();
     </script>
    

    In Razor:

     @(Html.Infragistics().DateEditor()
                  .ID("dateEditor")
                  .Render())
    
  5. Run the web page to view the basic setup of the igDateEditor control.

Setting the Value option right

In this section of the topic, we are going to review few commonly used and specific scenarios showing how setting the value option is handled by the igDateEditor.

When the value is empty and in edit mode you enter only part of the date, for example only the day, the other part of the date will be generated by the date object. What this means is that the date object will take the current date and fill up the missing parts of the date. For example if the current Date is 1st of January 2017 and the dateInputFormat is specified as "dd", when the user enters "25", then the year and the month will be filled up with 2017 and January. As a result, value would be interpreted as 25th of January 2017 in this case.

If you already have a value in input and delete part of it, again for example the day, and then blur the input the editor will take the missing part from the last entered date. For example if you have 28th of February 2015 and you delete the day, after you blur the input the date will go back to 28th of February.

But if you change a single field of the date, the editor will validate whether the newly created date is correct and if it is not correct it will recalculate it. For example, lets assume that the initially entered value was 01/31/2016 and you change only the month to February. Than the editor will take the day field and recalculate it as February has only 29 days. So the date will become 02/29/2016. Lets take a look at one more example. What will happen if we change only the date? If for example, you try to change manually the 02/29/2016 date to 02/30/2016 the editor will return the day to 29th as it will assume that you entered a wrong, not existing date.

Lets consider another scenario where we have the value set to the last day of a particular month. What will happen if you change the whole date by only adding a month in edit mode? The result will be that the editor will try to create the date by using the JavaScript Date object. For the sake of clarity lets take a look at the following example. The initially set value is again 01/31/2016, than we focus the editor and enter 2 for the month so the date in edit mode will look like this _2/__/__. Then the editor will try to use the previously used day and year and to fill in the deleted fields, but as we know February has only 29 days (two less then January) and that is why the JavaScript object will recalculate the date and add two more days to 29th of February and thus the date will become 3/2/2016.

The last scenario that we are going to pay attention to is the wrong value. If you enter for example 29th of February 2015, the editor will automatically correct you because 2015 is not a leap year. The displayed date will be 28th of February 2015.

When you use a string value for the minValue, maxValue and the value options, the editors will use the JavaScript Date Object constructor to create date object out of it and use it as a value for the corresponding option.

Note: These properties don't use the dateInputFormat setting to extract the date.

Date and Time Formats

The dateInputFormat and dateDisplayFormat options control how dates are formatted when the control is being edited or is simply displaying a value. Display format will match the input one if not provided.

Supported formats follow the general patterns for Formatting Dates where presets like "date"(default) or "dateTime" map to the patterns defined by the regional options. The format can also be defined using a common set of date specifiers - for example a format of "dd/MM/yyyy HH:mm" would display a date similar to "25/01/2017 16:35" where "MM" displays the month number ("MMM" would be a short name instead), "HH" displays the hour number in 24 hour format and "mm" the minute numbers. Characters besides the date parts (such as a space or ":") are used as is and the flags themselves can be escaped to be used as literals as well.

Note: The dateInputFormat option does not support the short numeric specifiers (such as "M" month number without leading zero) for most date parts as they cannot be applied while the value is being edited or yet to be entered. In this case the editor will still provide two prompts for the month, effectively using "MM" while editing.

This sample shows different configurations for formatting dates and times in the date editor:

Related Links

Email your feedback on this topic | View on GitHub