The asp+| control uses the asp+ list to bind the control
Nikhil Kothari
Microsoft Corporation
July 2000
Summary: Describes asp+ Repeater, DataList, and DataGrid server controls. These controls enable an html-based application user interface that is rooted in a data source. Discusses concepts related to these controls and provides an overview of the basic examples of using these controls.
Directory
Brief introduction
How does a list-bound control work?
Repeater Control
DataList Control
DataGrid Control
Repeater, DataList or DataGrid?
Related Resources
Download the sample file (in kilobytes) that is related to this article.
Brief introduction
The Repeater, DataList, and DataGrid controls make up the set of related Web controls within the System.Web.UI.WebControls namespace in the asp+ page frame. These controls enable HTML to display the contents of a list or data source that is bound. Therefore, collectively they are referred to as "list-bound controls."
Similar to other WEB controls in the framework, these controls provide a consistent programming model and encapsulate a browser-independent presentation logic. These features enable developers to program on the object model without having to master the inconsistent and complex technical knowledge associated with HTML.
These three controls can represent the data source content associated with them in a variety of layouts, including lists, columns/newspaper columns, and flow layouts (HTML streams). In addition, they allow you to create completely different or fully customizable layouts. In addition to encapsulating the presentation logic, it provides the ability to handle sent data, perform state management, and raise events. Finally, they also provide different levels of support for standard operations such as selection, editing, paging, and sorting. These controls can simplify several common WEB application scenarios, including reports, shopping carts, product lists, query results, and navigation menus.
The following sections further explain these controls and how to use them in your WEB application, and how to select controls.
How does a list-bound control work?
This section is the background material for the remainder of this article. Provides an overview of how these list-bound controls work, their common characteristics, and some related concepts.
DataSource Property
Each control has a DataSource property of type System.Collections.ICollection. In the simplest terms, a data source is a list or collection of objects of the same kind.
There are several objects in this framework that provide a ICollection implementation. This collection includes System.Data.DataView (which is typically used to access relational and XML data), general ICollection implementations (such as ArrayList and Hashtable), and arrays.
Unlike traditional data-bound controls, which typically require an ADO recordset, these list-bound controls do not impose any additional requirements on their data sources in addition to implementing the ICollection interface. By design, they can achieve maximum simplicity and flexibility for your application code by substantially increasing the types and data structures that can be used as valid DataSource property values.
Project Collection
Each list-bound control contains a project collection. Controls to place their project collections by enumerating the current data sources for these objects. Create a single item for each object in the enumeration and use it to represent the object. These items are also part of the control hierarchy contained in the list-bound control.
The following table lists the project types associated with data from the data source.
Default project type created by project
AlternatingItem for projects with odd subscript in the project collection
SelectedItem is created for the selected project, whether or not it is an alternative project
EditItem is created for an item in edit mode (regardless of whether it is selected or is an alternative item)
Control to create the following items that will be used in the presentation. However, they are not associated with data from the data source.
Headers are used to represent header information
Footnotes are used to denote footnote information
Delimiters are used to represent the content between each of the items shown in Figure 1 and apply only to Repeater and DataList
The page break is used to represent the paging UI associated with the DataGrid control
Figure 1. The project collection relative to the control collection
Data binding and creation of projects
List-bound controls follow the explicit data-binding model that is implemented throughout the asp+ framework. This means that the control needs to coordinate its data source only when its DataBind method is invoked.
When the DataBind method is invoked, the list control enumerates its data source, creates the project, and initializes it by extracting the value from its data source. If state management is enabled, the control also saves all the information it needs in order to re-create its project during postback processing of the page without having to reset the data source.
The explicit data-binding model enables your application code to accurately determine when and where the data source is needed in the processing sequence. This functionality makes access to the database server less and more efficient, and these are typically the most resource-intensive operations of a WEB application.
The general rule is that you must call DataBind whenever you need to re-create the project. In most cases, you will call DataBind when your page is first requested to create the initial project collection. During subsequent execution of the page, you will need to call this method in the various event handlers that cause the project collection to be changed. This can happen when the query used to create the initial data source is modified. This can also occur when the state of a project changes, such as from read-only mode to edit mode.
Style
By using style properties on the object model, you can define the formatting and appearance of all DataList and DataGrid controls and the items they contain. These properties allow you to customize fonts, colors, borders, and other appearance factors. The style properties of the control itself, such as the foreground color, background color, font, and border style, affect the representation of the entire control.
In addition, each control contains a large number of style attributes that match the type of project you create, such as as ItemStyle, AlternatingItemStyle, and HeaderStyle. The DataGrid provides a third-level style attribute that affects all cells in a particular column. Each column contained in a control can have its own headerstyle, FooterStyle, and ItemStyle.
Template
The style controls the format display, while the template defines the contents and representations for each item. You can consider a template as an HTML code fragment that defines the control hierarchy that is used to represent the project.
The Repeater and DataList controls are driven by templates that you specify, providing various template properties that can be set, such as ItemTemplate, AlternatingItemTemplate, and HeaderTemplate. Similar to styles, each template corresponds to a specific type of item.
The DataGrid control is not templated. However, TemplateColumns in the Column collection of the control makes the use of templates in the DataGrid possible. Each cell in the TemplateColumn can contain a template that is very similar to an item in a Repeater or DataList control. This also makes customization representations in the DataGrid possible.
Data binding in a template
The template defines the control hierarchy that is contained in the project. By using a data-binding expression, the control properties in this hierarchy can be bound to the data properties associated with this project.
An item that is the logical parent of a template is called a "container" in a data-binding expression. Each container has a property called DataItem that refers to its associated data. As a result, most typical data-binding expressions in the template bind the control properties to one of the properties of the Container.DataItem. This binding is further illustrated in the examples that are described in the following sections.
Repeater Control
As mentioned earlier, the Repeater control is completely template-driven, allowing for the creation of fully customizable representations and layouts. The following figure illustrates this feature.
Figure 2. Bulleted list of links generated by using the Repeater control
Excerpt from repeater1.aspx:
<%@ Page language= "C #" src= "Repeater1.cs" inherits= "Samples.repeater1page"%>
...
<asp:repeater runat=server id= "Linkslistrepeater"
Datasource= ' <%# sitelinks%> ' >
<template name= "HeaderTemplate" >
<ul type= "1" >
</template>
<template name= "ItemTemplate" >
<li>
<asp:hyperlink Runat=server
Text= ' <%# DataBinder.Eval (Container.DataItem, "SiteName")%> '
Navigateurl= ' <%# DataBinder.Eval (Container.DataItem, "SiteURL")%> ' >
</asp:HyperLink>
</li>
</template>
<template name= "FooterTemplate" >
</ul>
</template>
</asp:Repeater>
this. aspx file shows a declaration for generating a repeater control with a bulleted list.
This example demonstrates how to set up a data source declaration method with data binding syntax (<%#...%>). When you call the DataBind method, the expression in the data binding is executed. In this case, the Repeater DataSource property is bound to the page's SiteLinks property, which contains the URL reference to display.
Repeater is the only control that allows HTML fragments to exist in its templates, and the combination of Repeater controls and HTML fragments results in good form of HTML. In this example, a bulleted list is divided into three parts:
The list start tag represented by HeaderTemplate (<ul type= "1" >).
The list end tag (</ul>) represented by FooterTemplate.
The body of a list is placed by a list item (<li>) that is generated by repeating ItemTemplate for each object that appears in the SiteLinks collection.
You can also use these templates to specify the opening tag (<TABLE>) of the table in the header, specify the end tag (</TABLE>) of the table in the footnote, and specify a single table row (<TR>) in each project. This substitution option will cause the list to be represented.
You must specify ItemTemplate. It is the only required template. When no other template is specified, the control automatically uses this ItemTemplate for other templates.
In the following example, ItemTemplate contains a HyperLink Web control. The Text and NavigateUrl properties of this control are bound to the data properties associated with each recurring item. This is done by using a data-binding expression that is evaluated immediately after the project is created.
Repeater1.cs:
Namespace Samples {
...
public class Repeater1page:page {
protected Repeater Linkslistrepeater;
Public ICollection SiteLinks {
get {
ArrayList sites = new ArrayList ();
Sites. ADD (New Siteinfo ("Microsoft Home",
"http://www.microsoft.com"));
Sites. ADD (New Siteinfo (MSDN home),
"http://msdn.microsoft.com"));
Sites. ADD (New Siteinfo ("MSN homepage",
"http://www.msn.com"));
Sites. ADD (New Siteinfo ("Hotmail"),
"http://www.hotmail.com"));
return sites;
}
}
protected override void OnLoad (EventArgs e) {
Base. OnLoad (e);
if (! IsPostBack) {
Data binding (DataBind) is made to the page when it is first requested.
This recursively calls each control in the control hierarchy on this page.
DataBind ();
}
}
}
public sealed class Siteinfo {
private string SiteName;
private string SiteURL;
Public Siteinfo (String siteName, String siteurl) {
This.sitename = SiteName;
This.siteurl = SiteURL;
}
public string SiteName {
get {return siteName;}
}
public string SiteURL {
get {return siteurl;}
}
}
}
This. cs file contains code that appears with an ASPX page in the previous list.
The Repeater1page class overrides the OnLoad method of the Page class. This represents the invocation of DataBind in the first request to the page. This causes the data-binding expressions on these pages to be evaluated and the Repeater control to enumerate the data sources and create their projects. The DataBind method is invoked only on the first request. This works because Repeater is able to re-create its project during the return of the previous save state without the need for a data source instance.
This page exposes the common properties of type ICollection. This will be used in a data-binding expression that sets the value of the DataSource property of repeater. Property gets implemented using the ArrayList containing a sequence of Siteinfo objects. This property is public because only the public and protected members of the page class can be used in data-binding expressions.
Each Siteinfo object has two properties: SiteName and SiteURL. These properties are accessed when data binding is made to the HyperLink control in the template. In the binding expression for this control, Container.DataItem represents a single Siteinfo object to bind a particular item to. DataBinder.Eval (Container.DataItem, "SiteName") accesses the SiteName property of the current Siteinfo object.
The Repeater1 sample introduces you to a few basic concepts:
Defining templates
Data-binding syntax and data-binding expressions in templates
To use the ICollection representation of ArrayList as a data source
Calling the DataBind method during the initial processing of a page
DataList Control
The DataList control is a templated control that provides the ability to visually format its representations using style attributes. It can also produce multiple-column layouts. Figure 3 illustrates both of these features.
Figure 3. Example of a build from a two-column representation of DataList
Excerpt from datalist1.aspx:
<%@ Page language= "C #" src= "DataList1.cs" inherits= "Samples.datalist1page"%>
...
<asp:datalist runat=server id= "Peopledatalist"
repeatcolumns= "2" repeatdirection= "Vertical" repeatmode= "Table"
Width= "100%" >
<property name= "AlternatingItemStyle" >
<asp:tableitemstyle backcolor= "#EEEEEE"/>
</property>
<template name= "ItemTemplate" >
<asp:panel runat=server font-size= "12pt" font-bold= "true" >
<%# (person) container.dataitem). Name%>
</asp:Panel>
<asp:label runat=server width= "20px"
Borderstyle= "Solid" borderwidth= "1px" bordercolor= "BLACK"
Backcolor= ' <%# (person) container.dataitem). FavoriteColor%> ' >
</asp:Label>
<asp:label runat=server font-size= "10pt"
Text= ' <%# getcolorname ((person) container.dataitem). FavoriteColor)%> ' >
</asp:Label>
</template>
</asp:DataList>
this. aspx file shows the declaration of the DataList used to generate this example.
In this example, the DataList layout is implemented by setting the RepeatColumns property to "2". Setting RepeatDirection to "Vertical" causes items to be arranged from top to bottom and then from left to right. Conversely, setting the value to "horizontal" causes items to be arranged from left to right, and then from top to bottom.
The ASPX syntax contains settings for style attributes for a few DataList. In this example, the Width of DataList is set to 100% of its parent. Set the AlternatingItemStyle with a gray background to get a striped look. This example also shows that a template can contain any complex control definitions to meet the need for an ideal layout within each project.
Finally, the data-binding expression in this template uses early binding by converting Container.DataItem to its type. This does not incur the cost of late binding associated with using DataBinder.Eval, as shown in Repeater1. However, this method may produce an expression that is less readable. The following example gives an example of an expression that invokes the Getcolorname method, which is implemented in a file supported by code on this page.
DataList1.cs:
Namespace Samples {
...
public class Datalist1page:page {
protected DataList peopledatalist;
Protected string Getcolorname (Color c) {
Return
Typedescriptor.getconverter (typeof (Color)). ConvertToString (c);
}
private void Loadpeoplelist () {
Create a data source
Person[] people = new person[] {
New Person ("Nikhil Kothari", Color.green),
New Person ("Steve millet", color.purple),
New Person ("Chris Anderson", Color.Blue),
New Person ("Mike Pope", Color.orange),
New Person ("Anthony Moore", Color.yellow),
New Person ("Jon Jung", Color.mediumaquamarine),
New Person ("Susan Warren", Color.slateblue),
New Person ("Izzy Gryko", color.red)
};
Set the data source for a control
Peopledatalist.datasource = people;
And make the control use this data source to build its project
Peopledatalist.databind ();
}
protected override void OnLoad (EventArgs e) {
Base. OnLoad (e);
if (! IsPostBack) {
First request this page
Loadpeoplelist ();
}
}
}
public sealed class Person {
private string name;
Private Color FavoriteColor;
Public person (string name, Color favoritecolor) {
THIS.name = name;
This.favoritecolor = FavoriteColor;
}
Public Color FavoriteColor {
get {return favoritecolor;}
}
public string Name {
get {return name;}
}
}
}
In this page, the control's DataSource property is set by the program and is set in the ASPX file in a relatively declarative manner. The results of the two methods are the same. When you cannot choose which method, you must call the DataBind method so that the control can enumerate its data source and create the project it represents.
The data source used in this example is a simple array of the person object. Because each array implements the ICollection method, the array is suitable for use as a data source. This shows the degree of flexibility you can get when you use data structures and types as sources.
The DataList1 sample describes the following concepts:
To define a rich HTML UI in a template
Using a simple array as a data source
To set up a data source from a program
Various expressions allowed in the data-binding syntax
