Skip to content

Commit

Permalink
docs(form): Revamp Template article (#1943)
Browse files Browse the repository at this point in the history 
* docs(form): Revamp Template article

* polishing
  • Loading branch information
@dimodi
dimodi authored Feb 21, 2024
1 parent e8efc05 commit 435a466
Showing 1 changed file with 66 additions and 162 deletions.
228 changes: 66 additions & 162 deletions components/form/formitems/template.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,176 +12,95 @@ position: 5

This article explains how to customize the editor of a single Form item. To customize the rendering and item structure of the whole Form, check the article [Form Template for All Items]({%slug form-formitems-formitemstemplate%}).

You can provide your own custom editors instead of the [default editors the form can generate]({%slug form-overview%}#automatic-generation-of-fields). To do that, use the the `Template` of the [FormItem]({%slug form-formitems%}).
## Basics

When the Template is used, the built-in validation messages from the Form will not be rendered. Instead you can use the [Telerik Validation tools]({%slug validation-tools-overview%}) to provide validation messages, or any other suitable component such as the `ValidationMessage` that comes with the framework.
Form item templates enables the app to:

In this article you can find the following examples:
* Replace the [default editor that the Form generates for a given data type]({%slug form-overview%}#automatic-generation-of-fields) with a different component.
* Use the usual editor component for a given data type, but customize the editor or handle additional events.

* [Use Template to provide custom editors](#use-template-to-provide-custom-editor)
* [Add validation messages to templated Form Items](#add-validation-messages-to-templated-form-items)
To use a form item template, add a `<Template>` tag inside the [FormItem]({%slug form-formitems%}).

## Use Template to Provide Custom Editor
When using a Form item template, the following `FormItem` parameters are ignored, because the Form expects the template content to provide suitable replacements:

````CSHMTL
@* Use the Template to change the default editors *@
@using System.ComponentModel.DataAnnotations
<TelerikForm EditContext="@EditContext">
<FormValidation>
<DataAnnotationsValidator></DataAnnotationsValidator>
<ValidationSummary />
</FormValidation>
<FormItems>
<FormItem>
<Template>
<label for="country">Destination country:</label>
<TelerikDropDownList @bind-Value="@MyModel.Country"
DefaultText="Choose a country"
Data="@DropDownData"
Id="country">
<DropDownListSettings>
<DropDownListPopupSettings Height="auto" />
</DropDownListSettings>
</TelerikDropDownList>
</Template>
</FormItem>
<FormItem>
<Template>
<label for="city">Destination city:</label>
<TelerikComboBox @bind-Value="@MyModel.City"
Data="@CityData"
Id="city">
<ComboBoxSettings>
<ComboBoxPopupSettings Height="auto" />
</ComboBoxSettings>
</TelerikComboBox>
</Template>
</FormItem>
<FormItem>
<Template>
<label for="visited">First time to visit:</label>
<TelerikSwitch @bind-Value="@MyModel.FirstTime"></TelerikSwitch>
</Template>
</FormItem>
</FormItems>
</TelerikForm>
@code {
private TemplateModel MyModel { get; set; } = new TemplateModel();
private EditContext EditContext { get; set; }
private List<string> DropDownData { get; } = new List<string>()
{
"Bulgaria",
"Italy",
"Greece"
};
private List<string> CityData
{
get
{
switch (MyModel.Country)
{
case "Bulgaria":
return new List<string>() { "Sofia", "Plovdiv", "Varna", "Burgas" };
case "Italy":
return new List<string>() { "Rome", "Milan", "Naples", "Turin" };
case "Greece":
return new List<string>() { "Athens", "Thessaloniki", "Patras", "Piraeos" };
default:
return new List<string>();
break;
}
}
}
* `EditorType`
* `Hint`
* `Id`
* `LabelText`

protected override void OnInitialized()
{
EditContext = new EditContext(MyModel);
base.OnInitialized();
}
## Validation Messages and Styling

public class TemplateModel
{
public TemplateModel()
{
The `FormItem` `Template` replaces all the Form item's built-in rendering, which includes validation messages and form item labels. You can use the [Telerik validation tools]({%slug validation-tools-overview%}) to display the desired validation UI, or even use the standard Blazor `ValidationMessage` component.

}
The Telerik Blazor Form applies red color to the labels of invalid Form items. To preserve this behavior in Form item templates:

[Required]
public string Country { get; set; }
1. Set the `FormItem` [`Field` parameter]({%slug form-formitems%}#formitem-parameters), which is otherwise not required when using a `Template`.
1. Use a `<label class="k-label k-form-label">` element inside the `<Template>`.

[Required]
public string City { get; set; }
[Range(typeof(bool), "true", "true", ErrorMessage = "You must confirm first time.")]
public bool FirstTime { get; set; }
}
}
````
## Example

The sample below shows how to:

## Add Validation Messages to Templated Form Items
* Define custom editor components inside a `FormItem` `Template`.
* (optional) Preserve the built-in HTML rendering inside the template for consistent form item layout (`<label>` and `<div>` tags).
* (optional) Preserve the built-in label styling for invalid form items (`FormItem` `Field` parameters and `<label>` classes).
* (optional) Use validation messages inside Form item templates (`<TelerikValidationMessage>`).

You can render validation messages for templated Form items by using the [TelerikValidationMessage]({%slug validation-tools-message%}).
>caption Using Form Item Templates
````CSHTML
@* Use the TelerikValidationMessage to render validation messages *@
@using System.ComponentModel.DataAnnotations
<TelerikForm EditContext="@EditContext">
````CSHMTL
<TelerikForm Model="@FormModel">
<FormValidation>
<DataAnnotationsValidator></DataAnnotationsValidator>
</FormValidation>
<FormItems>
<FormItem>
<FormItem Field="@nameof(TravelDestination.Country)">
<Template>
<label for="country">Destination country:</label>
<TelerikDropDownList @bind-Value="@MyModel.Country"
DefaultText="Choose a country"
Data="@DropDownData"
Id="country">
<DropDownListSettings>
<DropDownListPopupSettings Height="auto" />
</DropDownListSettings>
</TelerikDropDownList>
<TelerikValidationMessage For="@(() => MyModel.Country)" />
<label for="country" class="k-label k-form-label">Destination Country</label>
<div class="k-form-field-wrap">
<TelerikDropDownList @bind-Value="@FormModel.Country"
DefaultText="Select Country"
Data="@DropDownData"
Id="country">
<DropDownListSettings>
<DropDownListPopupSettings Height="auto" />
</DropDownListSettings>
</TelerikDropDownList>
<TelerikValidationMessage For="@(() => FormModel.Country)" />
</div>
</Template>
</FormItem>
<FormItem>
<FormItem Field="@nameof(TravelDestination.City)">
<Template>
<label for="city">Destination city:</label>
<TelerikComboBox @bind-Value="@MyModel.City"
Data="@CityData"
Id="city">
<ComboBoxSettings>
<ComboBoxPopupSettings Height="auto" />
</ComboBoxSettings>
</TelerikComboBox>
<TelerikValidationMessage For="@(() => MyModel.City)" />
<label for="city" class="k-label k-form-label">Destination City</label>
<div class="k-form-field-wrap">
<TelerikComboBox Data="@CityData"
@bind-Value="@FormModel.City"
Placeholder="Select City"
Id="city">
<ComboBoxSettings>
<ComboBoxPopupSettings Height="auto" />
</ComboBoxSettings>
</TelerikComboBox>
<TelerikValidationMessage For="@(() => FormModel.City)" />
</div>
</Template>
</FormItem>
<FormItem>
<FormItem Field="@nameof(TravelDestination.FirstTime)">
<Template>
<label for="visited">First time to visit:</label>
<TelerikSwitch @bind-Value="@MyModel.FirstTime"></TelerikSwitch>
<TelerikValidationMessage For="@(() => MyModel.FirstTime)" />
<label for="firsttime" class="k-label k-form-label">First Time Visit</label>
<div class="k-form-field-wrap">
<TelerikSwitch @bind-Value="@FormModel.FirstTime"
OnLabel="Yes"
OffLabel="No" />
</div>
</Template>
</FormItem>
</FormItems>
</TelerikForm>
@code {
private TemplateModel MyModel { get; set; } = new TemplateModel();
private EditContext EditContext { get; set; }
private TravelDestination FormModel { get; set; } = new();
private List<string> DropDownData { get; } = new List<string>()
{
Expand All @@ -194,7 +113,7 @@ You can render validation messages for templated Form items by using the [Teleri
{
get
{
switch (MyModel.Country)
switch (FormModel.Country)
{
case "Bulgaria":
return new List<string>() { "Sofia", "Plovdiv", "Varna", "Burgas" };
Expand All @@ -204,41 +123,26 @@ You can render validation messages for templated Form items by using the [Teleri
return new List<string>() { "Athens", "Thessaloniki", "Patras", "Piraeos" };
default:
return new List<string>();
break;
}
}
}
protected override void OnInitialized()
{
EditContext = new EditContext(MyModel);
base.OnInitialized();
}
public class TemplateModel
public class TravelDestination
{
public TemplateModel()
{
}
[Required(ErrorMessage = "Select a Country")]
[Required(ErrorMessage = "Country is required")]
public string Country { get; set; }
[Required(ErrorMessage = "Select a City")]
[Required(ErrorMessage = "City is required")]
public string City { get; set; }
[Range(typeof(bool), "true", "true", ErrorMessage = "You must confirm first time.")]
public bool FirstTime { get; set; }
}
}
````

## See Also

* [Overview]({%slug form-overview%})
* [FormItems]({%slug form-formitems%})
* [FormGroups]({%slug form-formgroups%})
* [Orientation]({%slug form-orientation%})
* [Events]({%slug form-events%})

* [Live Demo: Form Item Templates](https://demos.telerik.com/blazor-ui/form/templates)
* [Form Items]({%slug form-formitems%})
* [Form Groups]({%slug form-formgroups%})
* [Form Events]({%slug form-events%})

0 comments on commit 435a466

Please sign in to comment.