ASP.NET Dynamic Data Field Templates Overview

ASP.NET Dynamic Data field templates are ASP.NET user controls that map data controls to data types in a data model. Field templates derive from FieldTemplateUserControl, the class that enables access to data fields, data columns, and metadata in data models. Dynamic Data projects provide some default field templates, but you can modify them or create custom field templates. This overview topic discusses:

• Features.

• Background.

• Default field templates.

• Using field templates.

• How field templates are rendered.

Features

• Dynamic Data uses field templates to render individual data fields in a data model.

• Dynamic Data enables you to:

  • Modify the default field templates.

  • Create custom field templates.

Background

Dynamic Data supports data-driven Web applications. Compared to accessing data with ASP.NET data source controls and existing data controls such as the GridView and ListView controls, Dynamic Data can require substantially less code. For example, the Products table in the Northwind database has foreign keys in the Categories and Suppliers tables. Displaying a relationship like this by using the GridView or ListView control requires that you understand the database schema and manually configure the controls and possibly write code.

However, by reading the database schema, Dynamic Data can get information about data types and foreign keys. Dynamic Data provides ASP.NET data controls that are aware of the database schema that are configured to make it easier for you to access and manipulate data. To replace the default rendering of the GridView and DetailsView controls, you manually provide the code for the rendering on each page. Field templates provide a simpler way to change the default rendering of the GridView and DetailsView controls globally.

Field templates are used in Dynamic Data controls to display individual data fields. Dynamic Data uses default field templates to create default rendering for displaying and editing data. You can customize the default field templates or create new ones.

For example, by using field templates with the Products table in the Northwind database, you can display the category name instead of the category ID, provide a drop-down list box in edit mode, and link to other pages, such as detail pages that show related data.

For information about how to create rich data controls that are database schema aware, see Adding Dynamic Behavior to ASP.NET Data-bound Controls.

Dynamic Data Controls that Use Field Templates

Dynamic Data controls that use filed templates to automatically render data based on data type include the following:

• DynamicControl—Used in FormView, ListView any controls such as GridView and DetailsView that support the use of templates to display and edit data in the data model. This control also enables the use of templates in data columns. For more information, see How to: Use ASP.NET Dynamic Data in Templated Data-Bound Controls.

• ForeignKey.ascx—A default field template that is used for displaying foreign key columns. The NavigateUrl can be exposed and accessed through DynamicField and DynamicControl objects.

• Children.ascx—A default field template that is used for displaying foreign key columns. The NavigateUrl and AllowNavigation properties can be set through DynamicField and DynamicControl.

• DynamicField—Although DynamicField is a DataControlField, it is mentioned here because it is used in a GridView and DetailsView data controls to display, edit, and add validation logic to the data model. For more information, see How to: Add Dynamic Behavior to Data-Bound Controls by Using a DynamicField.

Default Field Templates

Default field templates are field templates that are built into a Dynamic Data Web application. Examples of these default field templates include:

ForeignKey.ascx — Displays fields that have a many-to-one relationship.

ForeignKey_Edit.ascx — Used to edit fields that have a many-to-one relationship.

DateTime.ascx — Displays DateTime data type as text.

Dynamic Data provides default field templates that render data types such as Boolean, Decimal, integer and text.

For more information about default field templates, see ASP.NET Dynamic Data Default Field Templates.

Using Field Templates

To implement a field template you get values from the database and display it, get value out using the IBindableControl.ExtractValues method, and provide access to the DataControl control.

Dynamic Data enables you to customize the default field templates or create new field templates. If you customize a default field template, Dynamic Data uses the default field templates you customized.

Customizing How Default Field Templates Display Data

Default field templates are ASP.NET user controls that map to data types in a data model. These controls are derived from the FieldTemplateUserControl class, which enables access to data fields, database columns, and metadata.

You can modify the default field templates to change how data controls render data. For example, you can change the background and foreground colors of the text that is displayed in a data control that uses the default field templates. For more information, see How to: Customize ASP.NET Dynamic Data Default Field Templates.

Creating Custom Field Templates

You can also create custom field templates. To do so, you create an ASP.NET user control that derives from the FieldTemplateUserControl class. You add a UIHint property that maps the data field to the new control you created so that it is used in place of the default field template.

For information about how to create a custom field template, see How to: Customize Data Field Display in the Data Model. For information about how to use the UIHint property, see How to: Customize Data Field Appearance and Behavior in a Dynamic Data Control.

How Field Templates Are Rendered

Dynamic Data renders default and custom field templates in display, edit, and insert mode. Dynamic Data uses look-up rules to determine which field template to render. The look-up rule that Dynamic Data uses depends on whether the control is in display, edit, or insert mode. For example, if the data in the column is a Boolean value and the data control is in display mode, Dynamic Data renders Boolean.ascx, the default field template that displays Boolean data types. However, if the data control is in edit mode, Dynamic Data renders Boolean_Edit.ascx, the field template that enables editing of Boolean data types. If the data control is in insert mode, Dynamic Data renders Boolean_Insert.ascx, the field template that enables users to insert Boolean data types.

If a data field in the data model has a UIHint attribute associated with it—that is, if a custom field template is specified—Dynamic Data looks for a control based on the UIHint name. For example, if the UIHint attribute specifies MyTemplate, Dynamic Data looks for the field template named MyTemplate.ascx, or MyTemplate_Edit.ascx if the control is in edit mode, or MyTemplate_Insert.ascx if the control is in insert mode. If no such controls are found, Dynamic Data defaults to the default field templates.

Look-Up Rules

Dynamic Data starts the look-up by determining the mode of the field templates. For each mode, Dynamic Data applies a set of look-up rules.

Display Mode Look-Up

The following lists the look-up rules Dynamic Data uses to render field templates in display mode:

1. If a UIHint (that is, if a custom field template) metadata exists, Dynamic Data looks up a control based on the user control name and the DataTypeAttribute defined in the UIHint and DataTypeAttribute properties. Dynamic Data does not display all the data types by default. For example, Byte[] data types such as binary, timestamp, image types are not rendered by default. For more information about the data types Dynamic Data displays by default, see ASP.NET Dynamic Data Default Field Templates. For information about how to display custom data types, see DataTypeAttribute.

2. Dynamic Data determines the data type from the column in the database and looks up a control based on the data type. The data type name is determined and used in the following order:

   1. Looks up the full data type name, for example, System.Int32.

   2. If the full type name is not found, Dynamic Data looks up the simple data type name, for example, int32.

   3. If the simple data type name is not found, it looks up the special cases defined in the data table. For example, if a simple data type such as Int32 is not found, Dynamic Data looks up Integer, the special case defined in the data table. If the simple data type String is not found, it looks up Text, the special case for String.

   4. If a special case is not found and a fallback data type exists, it looks up a fallback data type. Dynamic Data uses the fallback data type to perform the look-up from the beginning.

   5. If a fallback data type does not exist, Dynamic Data does not display any data.

3. If the field is a foreign key field Dynamic Data renders ForeignKey.ascx, the default field template used for a many-to-one relationship or Children.ascx, the default field used for a one-to-many relationship.

If no field template control is found, Dynamic Data displays an error message indicating that no field template was found and no data is displayed.

Edit Mode Look-Up

The Edit mode look up rules is identical to the display mode rules but with the following exception. If the field template is in edit mode, Dynamic Data looks for an "_Edit" field template (For example, MyTemplate_Edit) and applies the rules; otherwise, it defaults to display (read only) mode.

Insert Mode Look-Up

The Insert mode look up rules is identical to the display mode rules but with the following exception. If the field template is in insert mode, Dynamic Data looks for an _Insert field template (for example, MyTemplate_Insert) and applies the rules; otherwise, it looks up an _Edit field template.

Class Reference

Additional Topics

Adding Dynamic Behavior to ASP.NET Data-bound Controls

ASP.NET Dynamic Data Scaffolding and Page Templates Overview

See Also

Other Resources

Using ASP.NET Dynamic Data

Change History