Telerik UI for Windows 8 HTML

Structurally and functionally, RadDatePicker and RadTimePicker are nearly identical, so they can be configured and used in the same way with two minor exceptions. Both controls work with Date object values. The RadDatePicker uses the date components of the object (year, month and date) while the RadTimePicker uses the time components (hour and minute; the period is determined from the data available in a Windows.Globalization.Calendar object). The other difference is in the format property, which has different values in the two controls corresponding to whether you are modifying date or time values.

This help article describes the configuration options of the RadDatePicker and RadTimePicker controls.

This topic contains the following sections.

Control Display Modes

You can control the way RadDatePicker and RadTimePicker controls are displayed and function in the page using the displayMode property. It accepts two values, listed in the Telerik.UI.RadDatePicker.DisplayMode and Telerik.UI.RadTimePicker.DisplayMode enumerations:

  • standard: This is the default mode of the control. Both the picker and selector parts of the control are available. The selector is opened when the picker button is clicked/tapped. Selection changes when the 'OK' button in the selector is pressed.

  • inline: In this mode the picker part of the control is not available. The selector renders inline in the document and is always open. Once the selected value of any of the lists changes, the control.value property is immediately updated.

Control Configuration Options

The following properties are responsible for global behaviors of the control. In the next sections you will get acquainted with the options for configuring certain parts of its structure.

  • autoSizeWidth: Use it to tell the control whether it should automatically calculate its picker width, so that it equals the width of the selector part.

    HTML Copy imageCopy
    <div id="picker1" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
        autoSizeWidth: true
    }">
    </div>
  • culture: Sets the culture locally for the control. The property takes a valid BCP-47 language tag as a value. For more information regarding Telerik culture support you can visit this article: Culture Support.

    HTML Copy imageCopy
    <div id="pickerFR" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
        culture: 'fr-FR'
    }">
    </div>
    datepicker-culture
  • displayValueFormat: Determines how the edited value is displayed on the screen after it has been selected. If not set, the format from the current system clock configuration is used. The assigned value should conform to the common formats for Telerik UI for Windows 8 HTML, listed in this help article: Formatting.

    HTML Copy imageCopy
    <div id="picker2" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
        displayValueFormat: 'dddd, MMMM dd, yyyy'
    }">
    </div>
    Display value format
  • enabled: Use this property to disable and re-enable the control. It accepts a boolean value indicating whether the user should be able to interact with the control.

    HTML Copy imageCopy
    <div id="picker3" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
        enabled: false
    }">
    </div>
  • isReadOnly: Setting this property value to true will prevent the user from changing the value of the picker. The visual appearance of the picker is not changed, it is only the interaction with it that is prevented.

    HTML Copy imageCopy
    <h3>isReadOnly: true</h3>
    <div id="picker4" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
        isReadOnly: true
    }">
    </div>
  • minValue: Use this property to set a minimum value for the picker. Note that the property accepts a Date object (or a string that can be parsed as a date) as a value but will use only the date part for RadDatePicker and only the time part for RadTimePicker.

    HTML Copy imageCopy
    <div id="picker5" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
        minValue: '10/10/2012'
    }">
    </div>
  • maxValue: Specifies the maximum allowed value for the picker. Same as with minValue, maxValue accepts a whole Date object (or a string that can be parsed as a date) but only the relevant part will be used.

    HTML Copy imageCopy
    <div id="picker6" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
        minValue: '10/10/2012 1:00 PM',
        maxValue: '11/15/2012 6:59 PM'
    }">
    </div>
  • tabIndex: Used to specify the position of the control in the tab order. Accepts an integer value; the default one is 0.

Header Settings

To display content above the picker control, use the header property. You can assign it a string or data object. In case the value is an object, you also need to set a headerTemplate to specify which properties of the object will be rendered.

HTML Copy imageCopy
<div id="picker8" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    header: 'Pick a date for your trip:'
}">
</div>
Header text
HTML Copy imageCopy
<div id="picker9" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    header: {Destination: 'Prague'},
    headerTemplate: 'Pick a date for your trip to #=Destination#:'
}">
</div>
Header template

Displaying Empty Text/Template

Similar to the header, you can specify a string or data object as a value of the emptyContent property. It will be displayed in the picker when there is no date selected yet. Again, if the assigned value is an object, you need to define a template to describe which properties of the object will be displayed.

HTML Copy imageCopy
<div id="picker10" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    emptyContent: 'Trip date...'
}">
</div>
Empty content text
HTML Copy imageCopy
<div id="picker11" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    emptyContent: {Destination: 'Prague'},
    emptyContentTemplate: 'Trip to #=Destination# date...'
}">
</div>
Empty Content Template

Selector Settings

Customizing the Selector Header

The selector header is one more part of the control that can be customized. The combination of the selectorHeader and selectorHeaderTemplate properties allow you to either specify a string, a combination of an object and a template, or only a template that will populate the area at the top of the selector.

HTML Copy imageCopy
<div id="picker12" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    selectorHeader: 'Pick a Date'
}">
</div>
Selector header
HTML Copy imageCopy
<div id="picker13" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    selectorHeader:{Destination: 'Prague'},
    selectorHeaderTemplate: 'Pick a date for trip to: #=Destination#',
    autoSizeWidth: true
}">
</div>
Selector header template

Formatting the Selector

To specify which editable parts of the selector should be visible to the user, you can use the selectorFormat property. Its value defines how the different selector components will be ordered. By setting this property, you can also define which editable parts of the selector will be visible. For example, 'y/m' will display the Year and Month components in a DatePicker. Valid values are a string permutation of the following:

RadDatePicker

  • y - year

  • m - month

  • d - day

RadTimePicker

  • h - hour

  • m - minute

  • t - period [AM/PM]

Note

Whether or not the period list (containing the values 'AM' and 'PM') appears depends also on the system settings. If the system short time pattern is in 24-hour mode, the period list will not appear even if the 't' component is passed to the selectorFormat property.

HTML Copy imageCopy
<div id="picker14" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    selectorFormat: 'm/y'
}">
</div>
Selector format
HTML Copy imageCopy
<div id="picker15" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
    selectorFormat: 'm'
}">
</div>
RadTimePicker selector format

Setting a Step

Setting a step rule allows you to hide some of the date/time values and show only the ones that you need in your scenario. You can configure the step settings for the days, months and years in RadDatePicker and the minutes in RadTimePicker

RadDatePicker's step property exposes three options - day, month, and year. Use them to set a value and a mode individually for each of the three date components. Here is a list of the available step modes:

  • startFromBase: In this mode the first value (base) is shown and all other values are displayed in steps equal to the value property. For example, if the value is set to 3, then the available selections will be 1, 4, 7, 10, 13, etc. The base for all of the three date components is 1.

  • multiplesOnly: If this mode is set, only the values that are multiples of the value property will be displayed. For example, if the value is set to 5, the available selections will be 5, 10, 15, 20, etc.

  • baseAndMultiples: This mode is a combination of the previous two. The base value is displayed and the rest of the values that are available for selection are the multiples of the value property. For example, if the value is set to 5, the displayed values will be 1, 5, 10, 15, 20, etc.

HTML Copy imageCopy
<div id="picker15-1" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    step: {
        year: {
            value: 3,
            mode: 'startFromBase'
        },
        month: {
            value: 2,
            mode: 'multiplesOnly'
        },
        day: {
            value: 4,
            mode: 'baseAndMultiples'
        }
    }
}">
</div>
datepicker-step

With RadTimePicker use the minuteStep property to set a step value for the minutes.

HTML Copy imageCopy
<div id="picker15-2" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
    minuteStep: 15
}">
</div>
timepicker-step

Changing the Default Value

The selectorDefaultValue property represents the default value displayed in the selector part. The default value is shown when the value property is not set (null/undefined). If no default value is specified, the current date/time on the system is displayed when the selector opens.

Showing and Hiding the Selector

If you want to display the selector at all times and not only when the user clicks it, set the isSelectorOpen property to true. Its value is false by default. You can also programmatically toggle the value of the control if under different than the default conditions, you want the selector to show and hide (for example, once the user fills in another form control).

HTML Copy imageCopy
<div id="picker16" data-win-control="Telerik.UI.RadDatePicker">
</div>
<button style="display: block" id="showSelectorBtn">Show the selector</button>
JavaScript Copy imageCopy
document.getElementById("showSelectorBtn").onclick = function () {
    var picker = document.getElementById("picker16").winControl;
    picker.isSelectorOpen = true;
};

Customizing the Appearance and Content of Selector Items

Modifying Item Count

Use the itemCount property to set the number of items visible within the selector part of the control. This property is used to determine the height of the selector part when opened. The calculated height will not exceed the height of the view port.

HTML Copy imageCopy
<div id="picker17" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    itemCount: 1
}">
</div>
Item count

Controlling Item Width and Height

Using the itemLength property, you can specify a numeric value that will set the width and height of the items displayed in the selector part of the control. The same value is used for both dimensions of the items.

HTML Copy imageCopy
<div id="picker18" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    itemLength: 65
}">
</div>
Item length

Changing Spacing Between Items

If you want to increase or decrease spacing between the items that appear in the selector part of the control, change the itemSpacing property value. Note that this property also determines the spacing between the different parts of the selector, e.g. lists, buttons, header.

HTML Copy imageCopy
<div id="picker19" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    itemSpacing: 15
}">
</div>
Item spacing

Templating the Selector Items

You can provide a template for the actual selector items as well. With this property the default template can be overriden. Internally, all items are bound to a data object having a value field that corresponds to the number that represents the current year, month, hour, etc. There is a second label field available for RadDatePicker which holds the name of the month, day, and whether the year is leap. In order to utilize either or both of the data object properties, the template should have mappings to them, e.g., #= value #'#= label #'.

HTML Copy imageCopy
<div id="picker20" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
    itemTemplate: '<h2>#=value#</h2> <h6>#=label#</h6>'
}">
</div>
Item template