Styles in Server Controls

2014-10-17

Styles govern the visual appearance of a control. If you are developing a control that supports styles, derive from System.Web.UI.WebControls.WebControl, which exposes styles as strongly typed properties (such as Font, Height, Width, and so on) and provides methods for working with style properties. For an overview of styles in ASP.NET controls, see the ASP.NET QuickStart —> ASP.NET Web Forms —> Applying Styles to Controls.

The WebControl class provides two techniques for supporting styles:

Exposing strongly typed style properties of type System.Web.UI.WebControl.Style or types derived from System.Web.UI.WebControl.Style.
Emitting styles as HTML attributes by adding name/value pairs to the WebControl.Style collection. Control developers should not use this technique. This technique is provided so that the control's users can add styles that the control does not expose as strongly typed properties. A control's user can set styles in this manner both programmatically and declaratively, as described in the ASP.NET QuickStart —> ASP.NET Web Forms —> Applying Styles to Controls.

Exposing Strongly Typed Style Properties

A Web server control (a server control that derives from WebControl) inherits the WebControl.ControlStyle property, which determines the typed style for the control as a whole. The type of ControlStyle is Style, which is a class that encapsulates style-related functionality, as described in the following list.

Style has properties such as Font, Height, Width, ForeColor, BackColor, and others that correspond to cascading style-sheet styles. WebControl exposes these style properties as top-level properties by delegating to subproperties of its ControlStyle property.
Style exposes a method (Style.AddAttributesToRender) for rendering styles as attributes to an HtmlTextWriter object. This allows WebControl to delegate style rendering to its ControlStyle property.

Note When you override the Render method of WebControl, you must ensure that the base rendering functionality provided by WebControl is preserved. For instance, if you override the Render method to directly call the Write method on the HtmlTextWriter instance, you lose the style rendering functionality that is built into WebControl. See Rendering a Server Control Samples for an example of the recommended technique for overriding Render.
Style provides methods for copying (Style.CopyFrom) and merging (Style.MergeWith) styles. See the Templated Data-Bound Control Sample for an example that uses these methods.
Style implements the IStateManager interface, which provides state management functionality, thus allowing a control to delegate state management to its style properties. As part of the IStateManager contract, Style implements methods such as LoadViewState, SaveViewState, and TrackViewState. Style also has an overloaded constructor that takes a StateBag type as an argument. WebControl creates ControlStyle by passing ViewState to the Style constructor, thus allowing its control style to access its view state. For an example of how to delegate customized state management to a control's style properties, see the Templated Data-Bound Control Sample.

While the default type of the ControlStyle property is Style, a Web server control can set its control style to any class that derives from Style by overriding the WebControl.CreateControlStyle method, as shown in the following example.

protected override Style CreateControlStyle() 
{
    // Note that the constructor of Style takes ViewState as an   
    // argument. 
    TableStyle style = new TableStyle(ViewState);
    // Set up default initial state.
    style.CellSpacing = 0;
    return style;
}
[Visual Basic]
Protected Overrides Function CreateControlStyle() As Style
    ' Note that the constructor of Style takes ViewState as an   
    ' argument. 
    Dim style As New TableStyle(ViewState)
    ' Set up default initial state.
    style.CellSpacing = 0
    Return style
End Function

In addition to the base Style type, the System.Web.UI.WebControls namespace provides other style types, such as TableStyle and TableItemStyle You can define additional strongly typed styles by deriving from Style (or from a class that derives from Style) and overriding or adding members. Just as WebControl exposes subproperties of Style as top-level properties, you can expose subproperties of your custom style type as top-level properties. For example, Table sets its ControlStyle as TableStyle and exposes subproperties of TableStyle, such as CellPadding, CellSpacing, and Gridlines, as top-level properties. The following code fragment from the Templated Data-Bound Control Sample shows how the TemplatedList custom control exposes the CellPadding subproperty of its ControlStyle as a top-level property.

public virtual int CellPadding {
                  get {
                        if (ControlStyleCreated == false) {
                              return -1;
                        }
                        return ((TableStyle)ControlStyle).CellPadding;
                  }
                  set {
                        ((TableStyle)ControlStyle).CellPadding = value;
                  }
            } 
[Visual Basic]
Public Overridable Property CellPadding() As Integer
   Get
      If ControlStyleCreated = False Then
         Return - 1
      End If
      Return CType(ControlStyle, TableStyle).CellPadding
   End Get
   Set
      CType(ControlStyle, TableStyle).CellPadding = value
   End Set
End Property

The following methods of WebControl allow a control's user to alter the control's ControlStyle.

The WebControl.ApplyStyle method copies a specified style to ControlStyle and overwrites existing elements.
The WebControl.MergeStyle method merges a specified style with ControlStyle, without overwriting existing elements.

See the Templated Data-Bound Control Sample for examples that use these methods.

Exposing Additional Style Properties for Child Controls

While the ControlStyle property governs the overall style of a Web server control, a composite Web server control (one that has child controls) can also expose additional style properties that apply to its child controls. A control must implement customized state management to preserve those additional styles across round trips to the client. The following list describes the main steps for providing such additional styles.

To expose styles for child controls

Define one or more properties that derive from Style. The custom control TemplatedList, described in the Templated Data-Bound Control Sample, exposes additional styles, as shown in the following code fragment. Note that in this case, when a new Style object is created, the control's ViewState is not passed to the Style constructor. A control's ViewState is passed to the Style constructor only when creating a control's ControlStyle property, and not for any other properties of type Style. Note also that the control delegates view-state tracking to the style property itself.

public virtual TableItemStyle AlternatingItemStyle {
                  get {
                        if (alternatingItemStyle == null) {
                              alternatingItemStyle = new TableItemStyle();
                              if (IsTrackingViewState)
                                    ((IStateManager)alternatingItemStyle).TrackViewState();
                        }
                        return alternatingItemStyle;
                  }
            }
[Visual Basic]
Public Overridable ReadOnly Property AlternatingItemStyle() As TableItemStyle
   Get
      If _alternatingItemStyle Is Nothing Then
         _alternatingItemStyle = New TableItemStyle()
         If IsTrackingViewState Then
            CType(_alternatingItemStyle, IStateManager).TrackViewState()
         End If
      End If
      Return _alternatingItemStyle
   End Get
End Property

Apply styles to the child controls. For an example, see the PrepareControlHierarchy method in the Templated Data-Bound Control Sample, which also shows how to merge styles. You should apply styles to the child controls in the render phase, as shown in the sample, so that they are not persisted in the view state.

Override the SaveViewState method to save the additional style properties to ViewState. Since Style objects manage their own state, a control must invoke SaveViewState on its style properties to get the objects that need to be added to the ViewState property. The following example from the Templated Data-Bound Control Sample shows how a control delegates customized state management to its style properties.

protected override object SaveViewState() 
{
    // Customized state management to handle saving 
    // state of contained objects such as styles.
    object baseState = base.SaveViewState();
    object itemStyleState = (itemStyle != null) ? 
        ((IStateManager)itemStyle).SaveViewState() : null;
    object selectedItemStyleState = (selectedItemStyle != null) ? 
        ((IStateManager)selectedItemStyle).SaveViewState() : null;
    object alternatingItemStyleState = (alternatingItemStyle != null) ? 
        ((IStateManager)alternatingItemStyle).SaveViewState() : null;

    object[] myState = new object[4];
    myState[0] = baseState;
    myState[1] = itemStyleState;
    myState[2] = selectedItemStyleState;
    myState[3] = alternatingItemStyleState;

    return myState;
}
[Visual Basic]
Protected Overrides Function SaveViewState() As Object
    ' Customized state management to handle saving 
    ' state of contained objects such as styles.
    Dim baseState As Object = MyBase.SaveViewState()
    Dim itemStyleState As Object 
    Dim selectedItemStyleState As Object
    Dim alternatingItemStyleState As Object

    If Not (_itemStyle Is Nothing) Then 
        itemStyleState = CType(_itemStyle, IStateManager).SaveViewState()
    Else
        itemStyleState = Nothing
    End If

    If Not (_selectedItemStyle Is Nothing) Then
        selectedItemStyleState = CType(_selectedItemStyle, IStateManager).SaveViewState()
    Else
       selectedItemStyleState = Nothing
    End If

    If Not (_alternatingItemStyle Is Nothing) Then
        alternatingItemStyleState = CType(_alternatingItemStyle, IStateManager).SaveViewState()
    Else
        alternatingItemStyleState = Nothing
    End If

    Dim myState(4) As Object
    myState(0) = baseState
    myState(1) = itemStyleState
    myState(2) = selectedItemStyleState
    myState(3) = alternatingItemStyleState

    Return myState
End Function

Override the LoadViewState method to customize restoration of the additional style properties from ViewState. The additional objects that were added to the ViewState must now be retrieved in the same order in which they were added. The following example from the Templated Data-Bound Control Sample shows how a control delegates customized state restoration to its style properties.

protected override void LoadViewState(object savedState) 
{
    // Customized state management to handle 
    // state restoration of contained objects.

    if (savedState != null) 
    {
        object[] myState = (object[])savedState;

        if (myState[0] != null)
            base.LoadViewState(myState[0]);
        if (myState[1] != null)
            ((IStateManager)ItemStyle).LoadViewState(myState[1]);
        if (myState[2] != null)
            ((IStateManager)SelectedItemStyle).LoadViewState(myState[2]);
        if (myState[3] != null)
            ((IStateManager)AlternatingItemStyle).LoadViewState(myState[3]);
    }
}
[Visual Basic]
Protected Overrides Sub LoadViewState(savedState As Object)
    ' Customized state management to handle saving 
    ' state of contained objects.
    If Not (savedState Is Nothing) Then
        Dim myState As Object() = CType(savedState, Object())

        If Not (myState(0) Is Nothing) Then
            MyBase.LoadViewState(myState(0))
        End If
        If Not (myState(1) Is Nothing) Then
            CType(ItemStyle, IStateManager).LoadViewState(myState(1))
        End If
        If Not (myState(2) Is Nothing) Then
            CType(SelectedItemStyle, IStateManager).LoadViewState(myState(2))
        End If
        If Not (myState(3) Is Nothing) Then
            CType(AlternatingItemStyle, IStateManager).LoadViewState(myState(3))
        End If
    End If
End Sub

For a sample of a control that exposes style properties that are applied to its child controls, see the Templated Data-Bound Control Sample.

Share via

Styles in Server Controls

Exposing Strongly Typed Style Properties

Exposing Additional Style Properties for Child Controls

See Also

Additional resources