|
|
     
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 ModesYou 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 |
|---|
<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 |
|---|
<div id="pickerFR" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
culture: 'fr-FR'
}">
</div> |
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 |
|---|
<div id="picker2" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
displayValueFormat: 'dddd, MMMM dd, yyyy'
}">
</div> |
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 |
|---|
<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 |
|---|
<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 |
|---|
<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 |
|---|
<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 |
|---|
<div id="picker8" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
header: 'Pick a date for your trip:'
}">
</div> |
| HTML | Copy |
|---|
<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> |
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 |
|---|
<div id="picker10" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
emptyContent: 'Trip date...'
}">
</div> |
| HTML | Copy |
|---|
<div id="picker11" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
emptyContent: {Destination: 'Prague'},
emptyContentTemplate: 'Trip to #=Destination# date...'
}">
</div> |
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 |
|---|
<div id="picker12" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
selectorHeader: 'Pick a Date'
}">
</div> |
| HTML | Copy |
|---|
<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> |
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 |
|---|
<div id="picker14" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
selectorFormat: 'm/y'
}">
</div> |
| HTML | Copy |
|---|
<div id="picker15" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
selectorFormat: 'm'
}">
</div> |
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 |
|---|
<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> |
With RadTimePicker use the minuteStep property to set a step value for the minutes.
| HTML | Copy |
|---|
<div id="picker15-2" data-win-control="Telerik.UI.RadTimePicker" data-win-options="{
minuteStep: 15
}">
</div> |
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 |
|---|
<div id="picker16" data-win-control="Telerik.UI.RadDatePicker">
</div>
<button style="display: block" id="showSelectorBtn">Show the selector</button> |
| JavaScript | Copy |
|---|
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 |
|---|
<div id="picker17" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
itemCount: 1
}">
</div> |
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 |
|---|
<div id="picker18" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
itemLength: 65
}">
</div> |
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 |
|---|
<div id="picker19" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
itemSpacing: 15
}">
</div> |
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 |
|---|
<div id="picker20" data-win-control="Telerik.UI.RadDatePicker" data-win-options="{
itemTemplate: '<h2>#=value#</h2> <h6>#=label#</h6>'
}">
</div> |
|