Skip to content

Commit def46d2

Browse files
svdimitrmarin-bratanov
svdimitr
and
marin-bratanov
authored
Docs form component (#236)
* feat(form): overview artile and structure * chore(form): overview fixes * chore(form): orientation article * chore(form); see also section - orientation * chore(form): events article * chore(form): events article * chore(form): additional data to overview * chore(form): improve overview and formitems articles * chore(form): formitems article * chore(form): add the FormButtons to the overview article and create template article * chore(form): additional explanations on FormButtons * chore(form): improve explanation for the formbuttons * chore(form): template article * chore(form): fix slug in template article * chore(form): add Id parameter to formitems article * chore(form): improve code snippet in template article * chore(form): groups article * chore(form): fix typo in groups article * chore(form): validation article * chore(form): improvements to overview article * chore(form): improvements to overview article * chore(form): improvements to different articles * chore(form): improve validation article * chore(form): add the form to config file * chore(form): fix a slug * chore(form): improve events article * chore(form): improve overview article * chore(form): fix issues in form docs * chore(form): remove the Refresh method from the docs * chore(form): remove the DateTimeOffset * chore(form): minor improvements, link from common validation article * chore(form): minor improvements on the form item articles * chore(form): minor improvements on groups and validation * chore(form): typo * chore(form): minor tweaks * chore(form): some improvements to the overview * chore(form): improvements to the overview article * chore(form): remove a redundant new line * chore(form): improvements to the overview article * chore(form): overview article improvements * chore(form): improve examples in overview * chore(form): update the sequence of articles * chore(form); improve the groups article * chore(form): add explanations on what Orientation parameter controls and move the gif upward in the article * chore(form): fix wording * chore(form): retake the grouping example screenshot * chore(form): improve the formitems overview article * chore(form): improve validation article * chore(form): better explain the colspan param and redo the example in the groups article * chore(form): imrpove events article * chore(form): improve templates article * chore(form): improve templates article * chore(): for build purposes * chore(form): minor improvements * chore(form): minor wording fix * chore(form): improve orientation article * chore(form): improve events article * chore(form): add ToC to templates article; add Width to overview * chore(form): add screenshot after first snippet too in overview article * chore(form): remove expandObject from validation article * chore(form): add slug for telerikvalidationmessage * chore(form): add separate article for the buttons * docd(form): add width parameter * docs(form): tweak data annotations that are supported * chore(form): fix reset button example to have working validation after new model creation * chore(form): remove editable attribute from examples, to be re-added when it is supported Co-authored-by: Marin Bratanov <[email protected]>
1 parent 53e0b5b commit def46d2

18 files changed

+1319
-1
lines changed

‎_config.yml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,9 @@ navigation:
6464
position: 20
6565

6666
## List custom TOC order for folders here
67-
67+
"*components/form/formitems":
68+
title: "Form Items"
69+
position: 20
6870
"*components/grid/columns":
6971
title: "Columns"
7072
position: 5
@@ -245,6 +247,8 @@ navigation:
245247
title: "DropDownTree"
246248
"*editor":
247249
title: "Editor"
250+
"*form":
251+
title: "Form"
248252
"*flatcolorpicker":
249253
title: "FlatColorPicker"
250254
"*gantt":
@@ -443,6 +447,7 @@ intro_columns:
443447
"Tile Layout": "tilelayout-overview"
444448
"Notification": "notification-overview"
445449
"Splitter": "splitter-overview"
450+
"Form": "form-overview"
446451
-
447452
title: "Scheduling"
448453
items:

‎common-features/input-validation.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ This article provides examples of validating the Telerik Blazor components. The
3131
* [MaskedTextbox](#maskedtextbox)
3232
* [Sliders](#sliders)
3333

34+
>tip Telerik offers the [Form Component]({%slug form-overview%}) that lets you generate and manage forms with predefined layouts and less code.
35+
3436
## Simple Inputs
3537

3638
Simple textbox-like inputs do not have any special behavior. You need to bind them to a model field that has the desired data annotation attributes set. Such inputs are the textbox, numeric textbox and date input.
@@ -715,6 +717,7 @@ The sliders are, effectively, numeric inputs in terms of behavior and what data
715717

716718
* [Data Annotation attributes](https://docs.microsoft.com/en-us/aspnet/core/mvc/models/validation)
717719
* [Live Demos](https://demos.telerik.com/blazor-ui/)
720+
* [Form Component]({%slug form-overview%})
718721
* [ValueChanged and Validation]({%slug value-changed-validation-model%})
719722
* [Validate on Blur/Change, not on input]({%slug textbox-validate-on-change%})
720723
* [Error: Requires a value for ValueExpression]({%slug common-kb-requires-valueexpression%})

‎components/form/colums.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Columns
3+
page_title: Form Columns
4+
description: Form for Blazor - Columns.
5+
slug: form-columns
6+
tags: telerik,blazor,form,edit,form,columns,spacing,column
7+
published: True
8+
position: 15
9+
---
10+
11+
# Form Columns
12+
13+
The Form component for Blazor allows you to add multiple columns by using the `Columns` parameter. It takes an `int` which represents the number of columns the Form will have. To manipulate the spacing between the columns you can use the `ColumnSpacing` parameter.
14+
15+
>caption Add columns to a Form with Automatically generated fields
16+
17+
You can set the `Columns` parameter when the Form component automatically generates the editors. The form will spread the editors evenly across the columns. It will calculate it using this formula: `propertiesInModelCount / Columns`.
18+
19+
````CSHTML
20+
@* Add colums to the Form component *@
21+
22+
<TelerikForm Model="@person"
23+
Columns="2" ColumnSpacing="25px">
24+
</TelerikForm>
25+
26+
@code {
27+
public Person person = new Person();
28+
29+
public class Person
30+
{
31+
public int Id { get; set; }
32+
public string FirstName { get; set; }
33+
public string LastName { get; set; }
34+
public DateTime DOB { get; set; } = DateTime.Today.AddYears(-20);
35+
public string CompanyName { get; set; }
36+
public DateTime HireDate { get; set; }
37+
public bool IsOnVacation { get; set; } = true;
38+
}
39+
}
40+
````
41+
42+
>caption The result from the code snippet above
43+
44+
![Form Columns Example](images/form-columns-example.png)
45+
46+
## See Also
47+
48+
* [Overview]({%slug form-overview%})
49+
* [FormItems]({%slug form-formitems%})
50+
* [FormGroups]({%slug form-formgroups%})
51+
* [Orientation]({%slug form-orientation%})
52+
* [Events]({%slug form-events%})
53+

‎components/form/events.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
title: Events
3+
page_title: Form Events
4+
description: Form for Blazor - Events.
5+
slug: form-events
6+
tags: telerik,blazor,form,edit,events
7+
published: True
8+
position: 30
9+
---
10+
11+
# Form Events
12+
13+
The Form component for Blazor exposes events that allow you to respond to user actions and provide custom logic.
14+
15+
* [OnSubmit](#onsubmit)
16+
* [OnValidSubmit](#onvalidsubmit)
17+
* [OnInvalidSubmit](#oninvalidsubmit)
18+
19+
>note The examples in this article use the [`EditContext`]({%slug form-overview%}#use-the-telerik-form-for-blazor-with-an-editcontext), but you can use a [model]({%slug form-overview%}#use-the-telerik-form-for-blazor-with-a-model) instead.
20+
21+
## OnSubmit
22+
23+
The `OnSubmit` event fires when the user clicks on the Submit button in the Form. Its handler takes as an argument the `EditContext` object and is used to trigger some custom logic based on the validity of the form.
24+
25+
When there is a handler for the `OnSubmit` event, the [`OnValidSubmit`](#onvalidsubmit) and [`OnInvalidSubmit`](#oninvalidsubmit) events will not be fired.
26+
27+
The `OnSubmit` event is mapped to the `OnSubmit` event of the <a target="_blank" href="https://docs.microsoft.com/en-us/aspnet/core/blazor/forms-validation?view=aspnetcore-5.0">Microsoft EditForm</a>
28+
29+
30+
>caption Handle the OnSubmit event
31+
32+
````CSHTML
33+
@* Use the OnSubmit event to trigger some custom logic depending on the validity of the form *@
34+
35+
@using System.ComponentModel.DataAnnotations
36+
37+
<TelerikForm EditContext="@myEditContext"
38+
OnSubmit="@OnSubmitHandler">
39+
<FormValidation>
40+
<DataAnnotationsValidator></DataAnnotationsValidator>
41+
</FormValidation>
42+
</TelerikForm>
43+
44+
45+
@code {
46+
public Person person = new Person();
47+
48+
EditContext myEditContext { get; set; }
49+
50+
51+
private void OnSubmitHandler(EditContext editContext)
52+
{
53+
bool isFormValid = editContext.Validate();
54+
55+
if (isFormValid)
56+
{
57+
//apply some custom logic when the form is valud
58+
}
59+
else
60+
{
61+
//apply some custom logic when the form is not valid
62+
}
63+
}
64+
65+
protected override void OnInitialized()
66+
{
67+
myEditContext = new EditContext(person);
68+
base.OnInitialized();
69+
}
70+
71+
public class Person
72+
{
73+
public int Id { get; set; }
74+
[Required(ErrorMessage ="Add your first name")]
75+
public string FirstName { get; set; }
76+
[Required(ErrorMessage = "Add your last name")]
77+
public string LastName { get; set; }
78+
[Range(typeof(DateTime), "1/1/1900", "1/15/2020", ErrorMessage = "The Date of Birth must be between 1/1/1900 and 1/15/2021")]
79+
public DateTime DOB { get; set; } = DateTime.Today.AddYears(-20);
80+
public string CompanyName { get; set; }
81+
public DateTime HireDate { get; set; }
82+
public bool IsOnVacation { get; set; } = true;
83+
}
84+
}
85+
````
86+
87+
## OnValidSubmit
88+
89+
The `OnValidSubmit` event fires when the form is submitted and there are no validation erros. It is mapped to `OnValidSubmit ` event of the <a target="_blank" href="https://docs.microsoft.com/en-us/aspnet/core/blazor/forms-validation?view=aspnetcore-5.0">Microsoft EditForm</a>. Its handler takes the `EditContext` as an argument.
90+
91+
>caption Use the OnValidSubmit event
92+
93+
````CSHTML
94+
@* You can use the OnValidSubmit event to provide custom logic when the form is valid *@
95+
96+
@using System.ComponentModel.DataAnnotations
97+
98+
<TelerikForm EditContext="@myEditContext"
99+
OnValidSubmit="@OnValidSubmitHandler">
100+
<FormValidation>
101+
<DataAnnotationsValidator></DataAnnotationsValidator>
102+
</FormValidation>
103+
</TelerikForm>
104+
105+
106+
@code {
107+
public Person person = new Person();
108+
109+
EditContext myEditContext { get; set; }
110+
111+
112+
public void OnValidSubmitHandler(EditContext editContext)
113+
{
114+
//some logic when the form is valid.
115+
Console.WriteLine("valid submission, you can save the model");
116+
}
117+
118+
protected override void OnInitialized()
119+
{
120+
myEditContext = new EditContext(person);
121+
base.OnInitialized();
122+
}
123+
124+
public class Person
125+
{
126+
public int Id { get; set; }
127+
[Required(ErrorMessage = "Add your first name")]
128+
public string FirstName { get; set; }
129+
[Required(ErrorMessage = "Add your last name")]
130+
public string LastName { get; set; }
131+
[Range(typeof(DateTime), "1/1/1900", "1/15/2020", ErrorMessage = "The Date of Birth must be between 1/1/1900 and 1/15/2021")]
132+
public DateTime DOB { get; set; } = DateTime.Today.AddYears(-20);
133+
public string CompanyName { get; set; }
134+
public DateTime HireDate { get; set; }
135+
public bool IsOnVacation { get; set; } = true;
136+
}
137+
}
138+
````
139+
140+
## OnInvalidSubmit
141+
142+
The `OnInvalidSubmit` event fires when there are validation erros in the Form upon its submission. It is mapped to `OnInvalidSubmit` event of the <a target="_blank" href="https://docs.microsoft.com/en-us/aspnet/core/blazor/forms-validation?view=aspnetcore-5.0">Microsoft EditForm</a>. Its handler takes the `EditContext` as an argument.
143+
144+
>caption Use the OnInvalidSubmit event
145+
146+
````CSHTML
147+
@* You can use the OnInvalidSubmit event to provide custom logic when the form is not valid *@
148+
149+
@using System.ComponentModel.DataAnnotations
150+
151+
<TelerikForm EditContext="@myEditContext"
152+
OnInvalidSubmit="@OnInvalidSubmitHandler">
153+
<FormValidation>
154+
<DataAnnotationsValidator></DataAnnotationsValidator>
155+
</FormValidation>
156+
</TelerikForm>
157+
158+
159+
@code {
160+
public Person person = new Person();
161+
162+
EditContext myEditContext { get; set; }
163+
164+
public void OnInvalidSubmitHandler(EditContext editContext)
165+
{
166+
//some logic when the form is not valid.
167+
Console.WriteLine("INVALID submission attempt");
168+
}
169+
170+
protected override void OnInitialized()
171+
{
172+
myEditContext = new EditContext(person);
173+
base.OnInitialized();
174+
}
175+
176+
public class Person
177+
{
178+
public int Id { get; set; }
179+
[Required(ErrorMessage = "Add your first name")]
180+
public string FirstName { get; set; }
181+
[Required(ErrorMessage = "Add your last name")]
182+
public string LastName { get; set; }
183+
[Range(typeof(DateTime), "1/1/1900", "1/15/2020", ErrorMessage = "The Date of Birth must be between 1/1/1900 and 1/15/2021")]
184+
public DateTime DOB { get; set; } = DateTime.Today.AddYears(-20);
185+
public string CompanyName { get; set; }
186+
public DateTime HireDate { get; set; }
187+
public bool IsOnVacation { get; set; } = true;
188+
}
189+
}
190+
````
191+
192+
## See Also
193+
194+
* [Overview]({%slug form-overview%})
195+
* [FormItems]({%slug form-formitems%})
196+
* [Template]({%slug form-formitems-template%})
197+
* [Orientation]({%slug form-orientation%})
198+
* [Events]({%slug form-events%})
199+

‎components/form/formgroups.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: Form Groups
3+
page_title: Form for Blazor - FormGroups
4+
description: Form for Blazor - FormGroups.
5+
slug: form-formgroups
6+
tags: telerik,blazor,form,edit,formgroups,groups
7+
published: True
8+
position: 25
9+
---
10+
11+
# Form Groups
12+
13+
You can group some associated fields in your form (model) by using the [FormItems]({%slug form-formitems%}). and putting them inside `FormGroup` tags.
14+
15+
In this article:
16+
17+
* [Features](#features)
18+
* [Example - Organize FormItems into Groups](#example---organize-formitems-into-groups)
19+
20+
## Features
21+
22+
The `FormGroup` tag exposes the following parameters:
23+
24+
* `LabelText` - `string` - defines a label for the entire group.
25+
26+
* `Columns` - `int` - defines the number of columns in the group.
27+
28+
* `ColumnSpacing` - `string` - defines the space between the editors in the group.
29+
30+
## Example - Organize FormItems into Groups
31+
32+
You can organize some FormItems into logical groups. You can configure the label of the group, the number of columns and the spacing between the items.
33+
34+
>caption The result from the code snippet below
35+
36+
![FormItem example](images/formgroups-example.png)
37+
38+
````CSHTML
39+
@* Organize items into groups *@
40+
41+
@using System.ComponentModel.DataAnnotations
42+
43+
<TelerikForm Model="@person" Columns="2" ColumnSpacing="25px">
44+
<FormValidation>
45+
<DataAnnotationsValidator></DataAnnotationsValidator>
46+
</FormValidation>
47+
<FormItems>
48+
<FormGroup LabelText="Personal Information" Columns="2" ColumnSpacing="15px">
49+
<FormItem LabelText="First Name" Field="@nameof(Person.FirstName)"></FormItem>
50+
<FormItem LabelText="Last Name" Field="@nameof(Person.LastName)"></FormItem>
51+
<FormItem LabelText="Age" Field="@nameof(Person.Age)" ColSpan="2"></FormItem>
52+
<FormItem LabelText="Email" Field="@nameof(Person.Email)" ColSpan="2"></FormItem>
53+
</FormGroup>
54+
<FormGroup LabelText="Employee Information" ColumnSpacing="25px">
55+
<FormItem LabelText="Company Name" Field="@nameof(Person.CompanyName)"></FormItem>
56+
<FormItem LabelText="Position" Field="@nameof(Person.Position)"></FormItem>
57+
</FormGroup>
58+
</FormItems>
59+
</TelerikForm>
60+
61+
@code {
62+
public Person person { get; set; } = new Person();
63+
64+
public class Person
65+
{
66+
[Required(ErrorMessage = "The First name is required")]
67+
public string FirstName { get; set; }
68+
[Required(ErrorMessage = "The Last name is required")]
69+
public string LastName { get; set; }
70+
[Range(18, 120, ErrorMessage = "The age should be between 18 and 120")]
71+
public int Age { get; set; }
72+
[Required]
73+
[EmailAddress(ErrorMessage = "Enter a valid email")]
74+
public string Email { get; set; }
75+
[Required]
76+
public string CompanyName { get; set; }
77+
[MaxLength(25, ErrorMessage = "The position can be maximum 25 characters long")]
78+
public string Position { get; set; }
79+
}
80+
}
81+
````
82+
83+
## See Also
84+
85+
* [Overview]({%slug form-overview%})
86+
* [FormItems]({%slug form-formitems%})
87+
* [Template]({%slug form-formitems-template%})
88+
* [Orientation]({%slug form-orientation%})
89+
* [Events]({%slug form-events%})
90+
91+

0 commit comments

Comments
 (0)