Working with Control Property Collections
| When you build more complex controls, you often need to represent a collection of items. For example, the standard ASP.NET DropDownList control contains one or more ListItem controls that represent individual options in the DropDownList. The GridView control can contain one or more DataBoundField controls that represent particular columns to display. In this section, we build several controls that represent a collection of items. We build multiple content rotator controls that randomly display HTML content, as well as a server-side tab control that renders a tabbed view of content. Using the ParseChildren AttributeWhen building a control that contains a collection of child controls, you need to be aware of an attribute named the ParseChildren attribute. This attribute determines how the content contained in a control is parsed. When the ParseChildren attribute has the value TRue, then content contained in the control is parsed as properties of the containing control. If the control contains child controls, then the child controls are parsed as properties of the containing control. (The attribute really should have been named the ParseChildrenAsProperties attribute.) When the ParseChildren attribute has the value False, then no attempt is made to parse a control's child controls as properties. The content contained in the control is left alone. The default value of the ParseChildren attribute is False. However, the WebControl class overrides this default value and sets the ParseChildren attribute to the value to true. Therefore, you should assume that ParseChildren is False when used with a control that inherits directly from the System.Web.UI.Control class, but assume that ParseChildren is true when used with a control that inherits from the System.Web.UI.WebControls.WebControl class. Imagine, for example, that you need to create a content rotator control that randomly displays content in a page. There are two ways of creating this control, depending on whether ParseChildren has the value true or False. The control in Listing 31.24 illustrates how you can create a content rotator control when ParseChildren has the value False. Listing 31.24. ContentRotator.vb
The file in Listing 31.24 actually contains two controls: a ContentRotator control and a Content control. The ContentRotator control randomly selects a single Content control from its child controls and renders the Content control to the browser. This all happens in the control's RenderContents() method. Notice that the ParseChildren attribute has the value False in Listing 31.24. If you neglected to add this attribute, then the Content controls would be parsed as properties of the ContentRotator control and you would get an exception. Note The AddParsedSubObject() method is discussed in the next section. The page in Listing 31.25 illustrates how you can use the ContentRotator and Content controls (see Figure 31.11). Listing 31.25. ShowContentRotator.aspx
Figure 31.11. Randomly displaying content with the ContentRotator control. If ParseChildren is not set to the value False, then you need to add a property to your control that corresponds to the child controls contained in the control. For example, the control in Listing 31.26 includes an Items property that represents the Item controls contained in the control. Listing 31.26. ItemRotator.vb
In Listing 31.26, the second value passed to the ParseChildren attribute is the name of a control property. The contents of the ItemRotator are parsed as items of the collection represented by the specified property. Unlike the ContentRotator control, the controls contained in the ItemRotator control are not automatically parsed into child controls. After the CreateChildControls() method executes, the ItemRotator control contains only one child control (the randomly selected Item control). The page in Listing 31.27 illustrates how you can use the ItemRotator control to randomly display page content. Listing 31.27. ShowItemRotator.aspx
There is no requirement that the contents of a control must be parsed as controls. When building a control that represents a collection of items, you can also represent the items as objects. For example, the ImageRotator control in Listing 31.28 contains ImageItem objects. The ImageItem class does not represent a control. Listing 31.28. ImageRotator.vb
Notice that the ImageItem class is just a class. It does not derive from the base Control class. Because the ImageItem class does nothing more than represent a couple of properties, there is no reason to make it a full-blown control. The page in Listing 31.29 illustrates how you can use the ImageRotator control to display different images randomly. Listing 31.29. ShowImageRotator.aspx
The page in Listing 31.29 has tracing enabled. If you look in the Control Tree section, you'll see that the ImageRotator control does not contain any child controls (see Figure 31.12). Figure 31.12. The ShowImageRotator.aspx page control tree. Using the AddParsedSubObject() MethodWhen the ParseChildren attribute has the value false, the contents of a control are automatically added to the control's collection of child controls (represented by the Controls property). It is important to understand that all content contained in the control, even carriage returns and spaces, are added to the controls collection. Any content contained in a control that does not represent a server-side control is parsed into a Literal control. In some cases, you might want to allow only a certain type of control to be added to the Controls collection. The AddParsedSubObject() method is called as each control is added to the Controls collection. By overriding the AddParsedSubObject() method, you can block certain types of controlssuch as Literal controlsfrom being added to the Controls collection. For example, the ContentRotator control in Listing 31.20 overrides the base AddParsedSubObject() method and prevents anything that is not a Content control from being added to the ContentRotator Controls collection. If you removed the AddParsedSubObject() method from this control, then all of the carriage returns and spaces between the Content controls would be added to the Controls collection as Literal controls. Using a ControlBuilderThe AddParsedSubObject() method enables you to specify which parsed controls get added to a Controls collection. Sometimes, you must take even more control over the parsing of a control. When the ASP.NET Framework parses a page, the Framework uses a special type of class called a ControlBuilder class. You can modify the way in which the content of a control is parsed by associating a custom ControlBuilder with a control. Here's a list of the most useful methods supported by the ControlBuilder class:
The GetChildControlType() method is the most useful method. It enables you to map tags to controls. You can use the GetChildControlType() method to map any tag to any control. For example, the file in Listing 31.30 contains a ServerTabs control that renders multiple tabs (see Figure 31.13). Each tab is represented by a Tab control. Figure 31.13. Using the ServerTabs control. Listing 31.30. ServerTabs.vb
Notice that the ServerTabs class is decorated with a ControlBuilder attribute. This attribute associates the ServerTabs control with a ControlBuilder class named ServerTabsBuilder. The ServerTabsBuilder class overrides the base ControlBuilder GetChildControlType() method. The overridden method maps the <tab> tag to the Tab control. Because of this mapping, you do not need to use a prefix or use the runat="server" attribute when declaring a tab within the ServerTabs control. The page in Listing 31.31 illustrates how you can use the ServerTabs control. Listing 31.31. ShowServerTabs.aspx
The ControlBuilder enables you to declare instances of the Tab control by using the <tab> tag instead of using a <custom:Tab runat="server"> tab. |
/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server"> <title>Show ContentRotator</title> </head> <body> <form runat="server"> <div> <custom:ContentRotator Runat="server"> <custom:Content Runat="server"> First Content Item </custom:Content> <custom:Content Runat="server"> Second Content Item <asp:Calendar Runat="server" /> </custom:Content> <custom:Content Runat="server"> Third Content Item </custom:Content> </custom:ContentRotator> </div> </form> </body> </html> 