Several Mvc Controls Toolkit controls use customizable templates to render the various parts they are composed of. There are:

• overall layout templates that dtermine the layout of the control
• templates for the various layout subparts, such as header/footers toolbars or sidebars, headers (as for instance a grid columns header), footers, etc.
• templates that render the actual data based on rows and columns

Each tag helpers provider has default templates based on partial Views for all tag helpers it handles, but the developer has the possiblity to customize all of them in several ways:

• Providing custom partial views with the same name as the default templates partial views in the Shared folder
• Providing custom partial views with the same name as the default templates partial views in a controller specific folder
• By specifying custom templates in the control tag helpers

Each template receives both a model and an options object whose type depend on the kind of template(row template, column template, etc.)

Templates may be created either programmatically or with the asp-template tag helper.

The asp-template tag helper may be used just for row or columns templates. All other templates are specified in attributes of the tag helper that implements the control with a string that references either a partial view or a ViewComponent.

Template types

Templates may be implemented with: partial views, View components, in-line, and with functions.

Once created all above template types offer exactly the same interface, and are dealt with in exactly the same way. Below a detailed description of each of them:

Partial view templates.

They are created either with <asp-template use-partial="partialviewName" type="Display/Edit" /> or programmatically with: new Template(TemplateType.Partial, partialviewName). While the template model is mapped into the PartialView model, the option object is placed into the Options ViewData entry.

View component templates.

They are created either with <asp-template use-view-component="viewcomponentName" type="Display/Edit" /> or programmatically with: new Template(TemplateType.ViewComponent, viewcomponentName). The ViewComponent InvokeAsync method must have the following 4 parameters:

1. model: object. The template model
2. options: O (it depends on the template functionality). The options object
3. prefix . The prefix to add to all input names.
4. modelState: ModelStateDictionary. Caller model state dictionary(anyway errors are automatically copied into the ViewComponent ModelState)

The ViewComponent InvokeAsync must perform the following operation, in order to ensure proper naming:

ViewData.TemplateInfo.HtmlFieldPrefix = prefix;
                

in-line templates.

They are created only with <asp-template type="Display/Edit" >...</asp-template>. The template markup is inserted as tag content. The template model may be obtained by invoking: Html.Item<ModelType>() which must be assigned either to a variable named Model or to a variable starting with a lower case letter in order to ensure proper naming of input fields. Typically the whole tempate code is enclosed within:

@{{
   ...
   ...
   ...             
}}
                

In order to limit the lexical scope of all variables. This is not obligatory, but it is a good practice that avoids unwanted interation due to variable homonymies.

The option object is obtained with: Html.Options<OptionsType>()

Function templates.

They are used sometimes in the code that implements new controls, and should not used by Web App developers. For this reason they will not be described in this documentation addressed mainly to Web App developers.

Templates should not be invoked directly by Web App developers, that should use higher level rendering methods, thus it is not covered in this documentation addressed mainly to Web App developers.