Subproperties

In earlier chapters, we showed how to implement simple properties whose types are primitive types, strings, and enumerations. In those cases, you do not have to do any extra work to enable a page developer to specify the property values on the control's tag (declarative persistence). However, with complex properties, you have to do additional work to enable declarative persistence.

Complex properties typically have subproperties, that is, properties exposed by the type of the complex property. For example, the WebControl class exposes a Font property whose type is the System.Web.UI.WebControls.Font Info class, which in turn exposes properties such as Bold , Name , and Size . The properties of FontInfo are subproperties of the Font property.

Two related entities work together to enable declarative persistence of complex properties:

Metadata attributes related to serialization
Type converter classes that perform conversions to and from the given type to the String type and to other types

In this section, we'll look at the metadata attributes that enable different forms of declarative persistence for complex properties. In the next section, we'll look at type converter classes.

Subproperties Persisted on a Control's Tag

To persist a subproperty on a control's tag, a page developer specifies the subproperty by using a hyphen between the property name and the subproperty name. The following example specifies the Name and Size subproperties of the Font property on the TextBox control's tag:

 <asp:TextBoxid="textBox1"  Font-Name  ="Verdana"  Font-Size  ="12pt" runat="server"/>

The page parser automatically handles the hyphenated subproperty syntax, provided there is a type converter associated with the type of the subproperty. (We will show how to associate a type converter with a property in the next section.) However, to enable the designer to generate the hyphenated subproperty syntax, you must apply certain design-time metadata attributes to the property and to its subproperties. The Font property in the following code fragment shows the design-time metadata attributes that you must apply to a complex property.

 publicclassWebControl:Control{ [ DesignerSerializationVisibility(DesignerSerializationVisibility.Content), NotifyParentProperty(true) ] publicFontInfoFont{...}  }

The DesignerSerializationVisibility(DesignerSerializationVisibility.Content) attribute tells the design-time serializer to step into the subproperties and serialize their values. The designer persists properties on the control's tag and generates the hyphenated syntax for each subproperty. The Notify Parent Property(true) attribute causes change notifications from subproperties in the property browser to bubble up the object model and generate change notifications on the control whose subproperties are changed so that the control gets marked as dirty in the designer. This procedure is essential for the correct persistence in HTML of properties that a page developer modifies in the designer.

You must also apply the NotifyParentProperty(true) attribute to the properties of the type of the complex property. The following example shows this attribute applied to the Name and Size properties of the FontInfo class. These properties are subproperties of the Font property of WebControl .

 [ TypeConverter(typeof(ExpandableObjectConverter)) ] publicsealedclassFontInfo{ [ NotifyParentProperty(true), ] publicstringName{...} [ NotifyParentProperty(true) ] publicFontUnitSize{...}  }

For completeness, the example shows the System.ComponentModel.ExpandableObjectConverter type converter associated with the FontInfo type via the TypeConverterAttribute described in the next section. The ExpandableObjectConverter tells the property browser to provide the expand/collapse UI that allows a page developer to edit subproperties. By default, the subproperties of the Font property are collapsed in the property browser. When a page developer clicks the Font property, the ExpandableObjectConverter causes the property browser to display a hierarchical list that shows the subproperties.

Inner Property Persistence

By default, subproperties are persisted on a control's tag using the hyphenated syntax. However, you can enable a different persistence format for complex properties, which consists of nesting them within your control's tags on a page. This is known as inner property persistence . The following example shows inner property persistence for the HeaderStyle property of the DataGrid control, where ForeColor is a subproperty of HeaderStyle property:

 <asp:DataGridrunat="server"> <HeaderStyleForeColor="Red"/> </asp:DataGrid>

To enable inner property persistence, you must mark your control with the ParseChildren(true ) attribute, which tells the page parser to parse the content within the control's tags as properties. In addition, you must apply the design-time PersistChildren(false) attribute, which tells the designer to persist the inner content as properties, not as child controls. (The ParseChildrenAttribute and the PersistChildrenAttribute attributes use opposing conventions for the semantics of their argument.) WebControl already has these attributes applied, as shown in the following code. Therefore you do not have to reapply these attributes when your control derives from WebControl .

 [ ParseChildren(true), PersistChildren(false) ] publicclassWebControl:Control,...{...}

Furthermore, you must mark the property with the design-time metadata attributes shown in the following example:

 [ DesignerSerializationVisibility(DesignerSerializationVisibility.Content), NotifyParentProperty(true), PersistenceMode(PersistenceMode.InnerProperty) ] publicvirtualTableItemStyleHeaderStyle{...}

We described the first two attributes earlier in this section. The last attribute, PersistenceMode(PersistenceMode.InnerProperty) , tells the designer to persist the property as an inner property. By default, a designer persists subproperties on the control's tag by using the hyphenated syntax. The default persistence mode does not require the PersistenceModeAttribute applied to a property, as you saw earlier with the Font property.

The page framework supports an additional form of inner property persistence: inner default property persistence , which is generally used for persisting a collection property of a control. The following example shows inner default property syntax for the Items property of a ListBox control. Each element within the control's tags is an element of the Items collection property:

 <asp:ListBoxid=ListBox1Width="100px"runat="server"> <asp:ListItem>Item1</asp:ListItem> <asp:ListItem>Item2</asp:ListItem> <asp:ListItem>Item3</asp:ListItem> </asp:ListBox>

When a control has an inner default property, content within the control's tags can correspond only to that property. The page parser will not permit any other properties within the control's tags. This explains why the property is called an inner default property. Note that the name of the inner default property ( Items in the preceding example) is not specified within the control's tags.

To enable inner default property persistence, you must mark your control with the following variation of the ParseChildrenAttribute , where the second argument of the attribute is the name of the inner default property:

 [ ParseChildren(true,"<  DefaultPropertyName  >") ] publicclassMyControl:WebControl{...}

Furthermore, to persist an inner default property correctly in the designer, you must mark the property as PersistenceMode(PersistenceMode.InnerDefaultProperty) . For example, the Items property of the ASP.NET ListControl is marked this way:

 [ PersistenceMode(PersistenceMode.InnerDefaultProperty) ] publicvirtualListItemCollectionItems{...}

In the next section, we will develop a MapDemo control that exposes two properties that have subproperties. Toward the end of this chapter, we will develop an ImageMap control that exposes a collection property persisted as an inner default property.