<%@ Page Language="C#" MasterPageFile="~/aspnet/section.master" %> <%@ Register TagPrefix="Acme" TagName="SourceRef" Src="~/util/SrcRef.ascx"%> <%@ Register TagPrefix=Acme Namespace=Acme %>

Databinding in Templates

Templated data-bound controls give you ultimate flexibility over the rendering of data in your pages. You may recall several templated controls from ASP.NET v1.x, such as the DataList and Repeater controls. Those controls continue to be supported in ASP.NET 2.0, however the way that you data bind controls inside templates have been simplified and improved in this release. This section discusses the various ways to data bind inside a data-bound control template.

Databinding Expressions

ASP.NET 2.0 adds improvements to data binding in templates, simplifying the data binding syntax from the full v1.x syntax of DataBinder.Eval(Container.DataItem, fieldname) to simply Eval(fieldname). Like DataBinder.Eval, the Eval method also accepts an optional formatString parameter. The shortened Eval syntax is different from DataBinder.Eval in that Eval automatically resolves the field against the DataItem property of the nearest container object (DataListItem, in the examples above), whereas DataBinder.Eval takes an argument for the container. For this reason, Eval is only used inside a template of a data-bound control and cannot be used at the Page level. Of course, DataBinder.Eval continues to be supported in ASP.NET 2.0 pages, so you use that instead for scenarios where the simplified Eval syntax is not supported. 
<asp:DataList DataSourceID="ObjectDataSource1" runat="server">
  <ItemTemplate>
    <asp:Image ImageUrl='<%# Eval("FileName", "images/thumbs/{0}") %>' runat="server"/>
    <asp:Label Text='<%# Eval("Caption") %>' runat="server"/>
  </ItemTemplate>
</asp:DataList>
The example below shows the new simplified Eval data binding syntax to bind an Image, Label and HyperLink control in a DataList ItemTemplate.


Data bindings can also be included as part of a theme definition for a control, so that it is possible to dramatically alter the layout and look-and-feel of a templated control simply by changing the applied Theme. Only Eval (or Bind, as discussed later) can be used in a Theme template, however. Binding to arbitrary user code is disallowed. The next example shows a Theme applied to the previous example to create a completely different look for the photos page. For more information about Themes, refer to the Applying Styles, Themes and Skins section of this tutorial.

The FormView Control

The DataList control iterates over each data item from the data source and outputs the ItemTemplate once for each item. This is useful for rendering a list of items, but often you want to data bind against a single data item inside a form. For this purpose, ASP.NET 2.0 introduces the FormView control, which renders a single data item at a time in a freeform template. The main difference between DetailsView and FormView is that DetailsView has a built-in tabular rendering, whereas FormView requires a user-defined template for its rendering. The FormView and DetailsView object model are very similar otherwise. The following example demonstrates a FormView control bound to an ObjectDataSource. The ItemTemplate property of FormView contains a data-bound Image, Label and HyperLink like the previous DataList example.


Like DetailsView, FormView keeps track of the current item being rendered, and can optionally support paging over multiple data items when the data source returns a list. The following example shows a FormView with paging enabled.

Two-way Databinding

The FormView supports automatic Updates, Inserts, and Deletes through its associated data source control just like the DetailsView control. To define the input UI for editing or inserting, you define an EditItemTemplate or InsertItemTemplate in addition to the ItemTemplate. In this template you will data bind input controls such as TextBox, CheckBox, or DropDownList to the fields of the data source. Data bindings in these templates use a "two-way" data binding syntax, however, to allow the FormView to extract the values of input controls from the template in order to pass to the data source. These data bindings use the new Bind(fieldname) syntax instead of Eval.

Important: A control that is data-bound using the Bind syntax must have an ID property set. 

<asp:FormView DataSourceID="ObjectDataSource1" DataKeyNames="PhotoID" runat="server">
  <EditItemTemplate>
    <asp:TextBox ID="CaptionTextBox" Text='<%# Bind("Caption") %>' runat="server"/>
    <asp:Button Text="Update" CommandName="Update" runat="server"/>
    <asp:Button Text="Cancel" CommandName="Cancel" runat="server"/>
  </EditItemTemplate>
  <ItemTemplate>
    <asp:Label Text='<%# Eval("Caption") %>' runat="server" />
    <asp:Button Text="Edit" CommandName="Edit" runat="server"/>
  </ItemTemplate>
</asp:FormView>
When performing updates or inserts with the GridView or DetailsView, where there are BoundFields defined for the Columns or Fields for the control, GridView or DetailsView is responsible for creating the input UI in Edit or Insert mode, so it can automatically extract these input values to pass back to the data source. Because templates contain arbitrary user-defined UI controls, the two-way data binding syntax is necessary to allow templated controls like FormView to know which control values should be extracted from the template for an update, insert, or delete operation. You can still use the Eval syntax in an EditItemTemplate for data bindings that should not be passed back to the data source. Note also that the FormView supports the DataKeyNames property just like DetailsView and GridView for retaining the original values of primary key fields to pass back to updates/deletes, even when these fields are not rendered.

The FormView supports the DefaultMode property for specifying the default template to display, but by default the FormView starts in ReadOnly mode and renders the ItemTemplate. To enable UI for transitioning from ReadOnly mode to Edit or Insert mode, you can add a Button control to the template and set its CommandName property to Edit or New. From within the EditItemTemplate, you can add Buttons with CommandName set to Update or Cancel to commit or abort the update operation. Similarly, you can add Buttons with CommandName set to Insert or Cancel to commit or abort the insert operation.

The following example shows a FormView with both an ItemTemplate and EditItemTemplate defined. The ItemTemplate contains controls bound using Eval (one-way), whereas the EditItemTemplate contains a TextBox control two-way bound using a Bind statement. The primary key field (PhotoID) is round-tripped in viewstate using the DataKeyNames property. The FormView contains command buttons for switching between its templates.


The GridView and DetailsView also support templated UI, through the use of a TemplateField added to the Columns or Fields collection. TemplateField supports ItemTemplate, EditItemTemplate, and InsertItemTemplate (DetailsView only) for specifying the UI for the field in the different rendering modes of these controls. Just like the FormView example above, two-way databindings in the EditItemTemplate or InsertItemTemplate will allow GridView or DetailsView to extract values from controls in these templates. A common use for TemplateField is to add validator controls to the EditItemTemplate for declarative validation of GridView or DetailsView operations. The example below shows an example of this technique. For more information about the validation controls available in ASP.NET, refer to the Validating Form Input Controls section of this tutorial.


Another use for TemplateField is to customize the input controls used to enter values for GridView or DetailsView columns/fields. For example, you can place a DropDownList control inside the EditItemTemplate of TemplateField to allow selection from a pre-defined list of values. The example below demonstrates this technique. Note that the DropDownList in this example is data-bound to it's own data source control to obtain the values of the list dynamically.