Skip to content

Commit 86ffca4

Browse files
marin-bratanovmarin-bratanov
committed
docs(dateTimePicker): initial docs
1 parent 927c08d commit 86ffca4

File tree

5 files changed

+216
-6
lines changed

5 files changed

+216
-6
lines changed

‎_config.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -131,11 +131,11 @@ navigation:
131131
"*dateinput":
132132
title: "Date Input"
133133
"*datepicker":
134-
title: "DatePicker"
134+
title: "Date Picker"
135135
"*daterangepicker":
136136
title: "DateRangePicker"
137137
"*datetimepicker":
138-
title: "DateTimePicker"
138+
title: "DateTime Picker"
139139
"*dialog":
140140
title: "Dialog"
141141
"*draganddrop":
@@ -260,6 +260,7 @@ intro_columns:
260260
"Date Input": "components/dateinput/overview"
261261
"Date Picker": "components/datepicker/overview"
262262
"Time Picker": "components/timepicker/overview"
263+
"DateTime Picker": "components/datetimepicker/overview"
263264
"DropDownList": "components/dropdownlist/overview"
264265

265266
-

‎common-features/input-validation.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Simple textbox-like inputs do not have any special behavior. You need to bind th
3434
>caption How to validate inputs
3535
3636
````CSHTML
37-
@using System.ComponentModel.DataAnnotations // used for the model class attributes
37+
@using System.ComponentModel.DataAnnotations @* used for the model class attributes *@
3838
3939
<EditForm Model="@person" OnValidSubmit="@HandleValidSubmit">
4040
<DataAnnotationsValidator />
@@ -60,12 +60,16 @@ Simple textbox-like inputs do not have any special behavior. You need to bind th
6060
Daily scrum: <TelerikTimePicker @bind-Value="person.DailyScrum"></TelerikTimePicker>
6161
<ValidationMessage For="@(() => person.DailyScrum)"></ValidationMessage>
6262
</p>
63+
<p class="start-time">
64+
Start time: <TelerikDateTimePicker Format="G" @bind-Value="@person.StartTime" Width="250px"></TelerikDateTimePicker>
65+
<ValidationMessage For="@(() => person.StartTime)"></ValidationMessage>
66+
</p>
6367
<p class="accepts-terms">
6468
Accepts terms: <InputCheckbox @bind-Value="person.AcceptsTerms" />
6569
<ValidationMessage For="@(() => person.AcceptsTerms)"></ValidationMessage>
6670
</p>
6771
68-
<button type="submit">Submit</button>
72+
<TelerikButton ButtonType="@ButtonType.Submit">Submit</TelerikButton>
6973
</EditForm>
7074
7175
@code {
@@ -92,9 +96,15 @@ Simple textbox-like inputs do not have any special behavior. You need to bind th
9296
public DateTime FavoriteDay { get; set; }
9397
9498
[Required(ErrorMessage = "The daily standup is required")]
95-
[Range(typeof(DateTime), "1/1/1900 08:00:00", "1/1/1900 17:00:00", ErrorMessage = "Time should be in business hours, between 8AM and 5 PM.")]
99+
[Range(typeof(DateTime), "1/1/1900 08:00:00", "1/1/1900 17:00:00",
100+
ErrorMessage = "Time should be in business hours, between 8AM and 5 PM.")]
96101
public DateTime? DailyScrum { get; set; }
97102
103+
[Required(ErrorMessage = "Enter a starting time")]
104+
[Range(typeof(DateTime), "29/11/2018 10:00:00", "22/12/2025 17:00:00",
105+
ErrorMessage = "Value for {0} must be between {1:dd MMM yyyy HH:mm} and {2:dd MMM yyyy HH:mm}")]
106+
public DateTime StartTime { get; set; }
107+
98108
[Required]
99109
[Range(typeof(bool), "true", "true", ErrorMessage = "Must accept terms")]
100110
public bool AcceptsTerms { get; set; }
@@ -103,7 +113,7 @@ Simple textbox-like inputs do not have any special behavior. You need to bind th
103113
Person person = new Person()
104114
{
105115
// for time pickers, the initial date value must match the date portion of the range validation rule
106-
DailyScrum = new DateTime(1900, 1, 1, 1, 1, 1)
116+
DailyScrum = new DateTime(1900, 1, 1, 1, 1, 1),
107117
};
108118
109119
void HandleValidSubmit()

‎components/datetimepicker/events.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: Events
3+
page_title: DateTimePicker for Blazor | Events
4+
description: Events in the DateTimePicker for Blazor
5+
slug: components/datetimepicker/events
6+
tags: telerik,blazor,DateTimePicker,events
7+
published: true
8+
position: 20
9+
---
10+
11+
# Events
12+
13+
This article explains the events available in the Telerik DateTimePicker for Blazor:
14+
15+
* [OnChange](#onchange)
16+
* [ValueChanged](#valuechanged)
17+
18+
## OnChange
19+
20+
The `OnChange` event fires when the new value is commited by the user either by pressing `Enter` while the input is focused, or when the input loses focus.
21+
22+
The datetime picker is a generic component, so you must provide either a `Value`, or a type to the `T` parameter of the component.
23+
24+
>caption Handle OnChange
25+
26+
````CSHTML
27+
@result
28+
<br />
29+
30+
<TelerikDateTimePicker T="DateTime" OnChange="@MyOnChangeHandler"></TelerikDateTimePicker>
31+
32+
@code {
33+
string result;
34+
35+
private void MyOnChangeHandler(object theUserInput)
36+
{
37+
// the handler receives an object that you may need to cast to the type of the component
38+
// if you do not provide a Value, you must provide the Type parameter to the component
39+
result = string.Format("The user entered: {0}", (DateTime)theUserInput);
40+
}
41+
}
42+
````
43+
44+
@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
45+
46+
>tip The `OnChange` event is a custom event and does not interfere with bindings, so you can use it together with models and forms.
47+
48+
>caption Handle OnChange and use two-way binding
49+
50+
````CSHTML
51+
@result
52+
<br />
53+
model value: @thePickerValue
54+
<br />
55+
56+
<TelerikDateTimePicker @bind-Value="@thePickerValue" OnChange="@MyOnChangeHandler"></TelerikDateTimePicker>
57+
58+
@code {
59+
string result;
60+
61+
DateTime? thePickerValue { get; set; } = DateTime.Now;
62+
63+
private void MyOnChangeHandler(object theUserInput)
64+
{
65+
// the handler receives an object that you may need to cast to the type of the component
66+
// if you do not provide a Value, you must provide the Type parameter to the component
67+
result = string.Format("The user entered: {0}", (theUserInput as DateTime?).Value);
68+
}
69+
}
70+
````
71+
72+
73+
## ValueChanged
74+
75+
The `ValueChanged` event fires upon every change (for example, keystroke) in the input, and upon clicking the `Set` or `Now` buttons in the time dropdown.
76+
77+
>caption Handle ValueChanged
78+
79+
````CSHTML
80+
@result
81+
<br />
82+
83+
<TelerikDateTimePicker ValueChanged="@( (DateTime d) => MyValueChangeHandler(d) )"></TelerikDateTimePicker>
84+
85+
@code {
86+
string result;
87+
88+
private void MyValueChangeHandler(DateTime theUserInput)
89+
{
90+
result = string.Format("The user entered: {0}", theUserInput);
91+
}
92+
}
93+
````
94+
95+
@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
96+
97+
@[template](/_contentTemplates/common/issues-and-warnings.md#valuechanged-lambda-required)
98+
99+
>caption Handle ValueChanged and provide initial value
100+
101+
````CSHTML
102+
@result
103+
<br />
104+
model value: @thePickerValue
105+
<br />
106+
107+
<TelerikDateTimePicker Value="@thePickerValue" ValueChanged="@( (DateTime d) => MyValueChangeHandler(d) )"></TelerikDateTimePicker>
108+
109+
@code {
110+
string result;
111+
112+
DateTime thePickerValue { get; set; } = DateTime.Now;
113+
114+
private void MyValueChangeHandler(DateTime theUserInput)
115+
{
116+
result = $"The user entered: {theUserInput}";
117+
118+
//you have to update the model manually because handling the ValueChanged event does not let you use @bind-Value
119+
thePickerValue = theUserInput;
120+
}
121+
}
122+
````
123+
124+
## See Also
125+
126+
* [ValueChanged and Validation]({%slug value-changed-validation-model%})

‎components/datetimepicker/images/date-time-picker-overview.gif‎

279 KB
Loading

‎components/datetimepicker/overview.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: Overview
3+
page_title: Date-Time Picker for Blazor Overview
4+
description: Overview of the DateTime Picker for Blazor
5+
slug: components/datetimepicker/overview
6+
tags: telerik,blazor,datetime,picker,datetimepicker,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# DateTime Picker Overview
12+
13+
The DateTime Picker component allows the user to choose both a date and a time from a visual list in a dropdown, or to type it into a [date input]({%slug components/dateinput/overview%}) that can accept only DateTime values. You can control the format shown in the input and respond to [events]({%slug components/datetimepicker/events %}).
14+
15+
To use a Telerik DateTime Picker for Blazor, add the `TelerikDateTimePicker` tag.
16+
17+
>caption Basic datetime picker with custom format, min and max
18+
19+
````CSHTML
20+
Selected time: @selectedTime
21+
<br />
22+
23+
<TelerikDateTimePicker Min="@Min" Max="@Max" @bind-Value="@selectedTime"
24+
Format="dd MMM yyyy HH:mm:ss" Width="250px"></TelerikDateTimePicker>
25+
26+
@code {
27+
private DateTime? selectedTime = DateTime.Now;
28+
public DateTime Min = new DateTime(1990, 1, 1, 8, 15, 0);
29+
public DateTime Max = new DateTime(2025, 1, 1, 19, 30, 45);
30+
}
31+
````
32+
33+
>caption The result of the snippet above and the behavior of the component
34+
35+
![](images/date-time-picker-overview.gif)
36+
37+
>caption Component namespace and reference
38+
39+
````CSHTML
40+
@using Telerik.Blazor.Components
41+
42+
<TelerikDateTimePicker @ref="@theDateTimePickerRef" @bind-Value="@selectedTime"></TelerikDateTimePicker>
43+
44+
@code {
45+
private DateTime? selectedTime = DateTime.Now;
46+
// the datetime picker is a generic component and its type comes from the value field type
47+
Telerik.Blazor.Components.TelerikDateTimePicker<DateTime?> theDateTimePickerRef { get; set; }
48+
}
49+
````
50+
51+
The DateTimePicker component exposes the following features:
52+
53+
* `Class` - the custom CSS class rendered on the wrapping element.
54+
* `Enabled` - Specifies whether typing in the input and opening the dropdown are allowed.
55+
* `Format` - Specifies the format of the DateInput of the DateTimePicker. Defaults to `MM/dd/yyyy HH:mm:ss` (24 hour time short month and date). Read more in the [Supported Formats]({%slug components/dateinput/supported-formats%}) article.
56+
* `Min` - The earliest date and time that the user can select in the dropdown.
57+
* `Max` - The latest date and time that the user can select in the dropdown.
58+
* `Value` - The current value of the input. Can be used for binding.
59+
* `Width` - Defines the width of the DateTimePicker.
60+
* Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
61+
62+
63+
64+
When using the dropdown to edit dates, you must click the "Set" button to commit the date. It is located in the Time portion of the dropdown (you will be navigated to it automatically upon selecting a date). Clicking "Cancel", or outside of the dropdown without clicking "Set", will revert the time to the original value. You can also commit a date by clicking the "NOW" button which will choose the current time.
65+
66+
The time format specifiers in the `Format` control the tumblers available in the dropdown. For example, the `HH` specifier will result in a hour selector in a 24 hour format. If you also add the `tt` specifier, you will also get the AM/PM tumbler, but the 24 hour format will still be used. This means that you can also add several tumblers for the same time portion if the format string repeats them.
67+
68+
69+
## See Also
70+
71+
* [Live Demo: DateTime Picker](https://demos.telerik.com/blazor-ui/datetimepicker/index)
72+
* [Input Validation]({%slug common-features/input-validation%})
73+
* [Supported Input Date Formats]({%slug components/dateinput/supported-formats%})

0 commit comments

Comments
 (0)