Authoring Web Forms with the WebControls
This article provides general information on authoring Web Forms with the Windows Internet Explorer WebControls. The information given here is equally applicable to authoring with the MultiPage, TabStrip, Toolbar, and TreeView controls.
This document includes the following sections.
- Processing Directives
- Import Directive
- Register Directive
- The RUNAT Attribute
- The AUTOPOSTBACK Attribute
- Example WebControl Page
- Related Topics
Processing Directives
When authoring Web Forms pages using the WebControls ASP.NET controls, it is necessary to include certain processing directives. These directives keep the resulting XML content concise and enable ASP.NET scripts to access the WebControls namespace and its associated objects.
Two processing directives are added to an ASP.NET Web Forms page to enable WebControls to be authored and scripted on the page.
Import Directive
The @ Import directive allows an author to write code that relies on the Microsoft.Web.UI.WebControls namespace within the .aspx page.
<%@ import namespace="Microsoft.Web.UI.WebControls" %>
In the code snippet, the @ Import directive imports the Microsoft.Web.UI.WebControls namespace corresponding to the Microsoft.Web.UI.WebControls.dll file, which is the custom ASP.NET control that implements the WebControls.
If this statement is not included in the .aspx file, then it is not possible to script with the WebControls objects. Therefore, this directive is required in order to generate WebControls elements and objects dynamically within the Page_Load function.
Register Directive
The @ Register directive can be used to associate a user-defined tag prefix with an assembly and its namespace. When authoring with an element that has been implemented with a custom control, for example TabStrip, the namespace of the assembly is specified as the tag prefix of the element.
In many cases the name of a namespace can be lengthy, so it is both practical and convenient to associate a short tag prefix with the namespace, and use this in the code and markup.
<%@ Register TagPrefix="mytree"
Namespace="Microsoft.Web.UI.WebControls"
Assembly="Microsoft.Web.UI.WebControls, Version=1.0.2.226, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>
The @ Register directive registers a TagPrefix for the WebControls namespace, in this case mytree. Clearly, the TagPrefix is much shorter than the full namespace and keeps the WebControls markup concise. However, the namespace for the assembly can be used directly as the tag prefix in ASP.NET.
These directives should be placed at the top of the Web Form page, before any of the WebControls elements are used or referenced.
After the @ Import and @ Register directives have been added to the Web page, the WebControls elements can be authored declaratively or programmatically.
The RUNAT Attribute
The HTML markup for ASP.NET controls must reside within a containing <form> control with the runat="server" attribute/value pair.
<form runat="server">
<mytree:treeview runat="server" ...>
<mytree:treenode text="Node number 1" />
<mytree:treenode text="Node number 2" />
</mytree:treeview>
</form>
All WebControls markup also requires runat="server" on the top-level element of the control, but this attribute is not required on the child elements. For example, a TreeView requires runat="server", whereas TreeNode elements do not.
The AUTOPOSTBACK Attribute
The AutoPostBack attribute is used to control how the client browser posts user interactions to the server. When AutoPostBack is true, every interaction with the control causes a postback, and the server controls are used to update the page rendering.
When AutoPostBack is false, the controls never cause a postback. Therefore, by setting AutoPostBack to false, it is possible to handle the events fired on the client-side behavior and force a postback with Dynamic HTML (DHTML).
As a general rule, when posting forms with the WebControls, it is useful to test the IsPostBack property in the Page_Load event before creating controls or manipulating them with script. Controls only need to be created once and are persisted for each postback to the server. The first time a page is loaded, there is no postback; this condition provides a convenient way to determine if the Web Form has been initialized.
<script language="C#" runat="server">
public void Page_Load(Object sender, EventArgs e)
{
if (!IsPostBack)
{
SetupButtons();
}
}
</script>
Example WebControl Page
The source content for a simple Web Form page is given to illustrate how a TreeView UI can be added to a page declaratively. The source code highlights the processing directives.
<%@ import namespace="Microsoft.Web.UI.WebControls" %>
<%@ Register TagPrefix="mytree"
Namespace="Microsoft.Web.UI.WebControls"
Assembly="Microsoft.Web.UI.WebControls, Version=1.0.2.226, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>
<head>
</head>
<body>
<form id="myform" runat="server">
<mytree:treeview runat="server">
<mytree:treenode Text="Michigan">
<mytree:treenode Text="Detroit" />
<mytree:treenode Text="Farmington" />
<mytree:treenode Text="Southfield" />
</mytree:treenode>
</mytree:treeview>
</form>
</body>