Template Sets and Templated Controls

Article
09/14/2006

ASP.NET provides templated controls, controls that expose a number of template properties that the developer can apply to mark up language targets. These templates are inserted in the appropriate places during the rendering of the control. For example, there are templates for the List control, such as header and footer templates. This feature allows for significant customization in the appearance of controls at run time, based on the device.

The ASP.NET mobile controls extend this model and introduce the notion of template sets. A template set is a collection of templates. However, a single templated control might refer to multiple sets of templates, with each template set having different device-specific criteria.

Rendering Criteria for Template Sets

Each template set of a templated control is contained in a <Choice> element that resides within a shared <DeviceSpecific> element.

At run time, the choices in the <DeviceSpecific> element are evaluated in order. The first matching <Choice> element is used for device-specific content. If the selected choice contains templates, the control uses them. If no templates are found, or if none of the specified choices is appropriate, the control renders its default rendering.

By design, you cannot programmatically change the StyleReference property on the current form and then immediately switch to another form and expect controls to render with the new style setting. The style templates are loaded prior to the StyleReference property being referenced; thus, the programmatic change is accomplished after the fact.

Control-Specific Rendering

The rendering behavior of controls in templated mode is specific to the control. Some controls, such as List and ObjectList, might render all their contents from the provided templates. Other controls might add the contents of specific templates to their default content. For example, if a header or footer template is specified and chosen for the Form control, the markup contained in the template is added to the form contents as a header or footer, respectively.

Setting Properties for a Templated Control

Setting properties on a control in a template takes slightly more effort than if the control were not in a template. You must obtain a reference to the naming container and use the FindControl method to find your link control. You can then set the properties. The following example briefly illustrates these concepts.

void Page_Load(Object sender, EventArgs e) {

  // Iterate through the controls in the form.
  foreach(Control c in Form1.Controls)   {

      if(c.GetType().ToString() ==
      "System.Web.UI.MobileControls.TemplateContainer")     {
      // Get the link control.
      Control ctrl = c.FindControl("myLink");

      if (ctrl != null)       {
        // Set the text and url properties.
        ((System.Web.UI.MobileControls.Link)ctrl).Text = "Home Page";
        ((System.Web.UI.MobileControls.Link)ctrl).NavigateURL = 
          "https://www.microsoft.com";
      }
    }
  }
}

Template Sets and Styles

Styles in a StyleSheet control might also contain template sets. Thus, you can have multiple-templated controls that reference the same style, use the same template sets, and provide the same benefits of encapsulation that a style provides. For an example that illustrates template sets, see the ASP.NET Mobile Controls QuickStart.

Style Templates vs. Style Properties

As described in the Styles documentation, you can inherit a style from a parent, you can explicitly set the StyleReference property, or you can inherit the style through aggregation. With templates, however, there is no cascading effect. You cannot retrieve a template from a parent style template unless you use a template within a style sheet.

Device-Independent Templates

Any templated control can have a device-independent template. To specify device-independent templates, use a <Choice> element without an explicit Filter attribute. A device-independent choice, where specified, must always be the last choice declared, so that it is chosen if no other choices apply to the target device.

Templated UI in Form Controls

In some advanced scenarios, it is useful to dynamically instantiate and add templates. The following code example adds templates in an Init event handler.

<%@ Page language="c#" Inherits="System.Web.UI.MobileControls.MobilePage" Debug="true"%>
<script runat="server">
private void Form_Init(object sender, System.EventArgs e)
{
   DeviceSpecific devSpecific = new DeviceSpecific();

   // Create the choice tag.
   DeviceSpecificChoice devChoice = new DeviceSpecificChoice();
   devChoice.Filter = "isHTML32";
      
   // Create the template.
   ITemplate myTemplate;
   myTemplate = new CustomTemplate("HeaderTemplate");
   
   // Create the templateContainer.
   TemplateContainer container = new TemplateContainer();
   myTemplate.InstantiateIn(container);
                        
   // Create the tree.
   devChoice.Templates.Add("HeaderTemplate", myTemplate);
   ((IParserAccessor)devSpecific).AddParsedSubObject(devChoice);
   ((IParserAccessor)Form1).AddParsedSubObject(devSpecific);
}

public class CustomTemplate : ITemplate
{   
   String strWhichTemplate;

   public CustomTemplate(String strTemplate)
   {
      strWhichTemplate = strTemplate;
   }
   
   public void InstantiateIn(Control container)
   {
      if(strWhichTemplate == "HeaderTemplate")
      {
         System.Web.UI.MobileControls.Label lb = new System.Web.UI.MobileControls.Label();
         lb.Text = "Header Template";

         System.Web.UI.MobileControls.Command cmd = new System.Web.UI.MobileControls.Command();
         cmd.Text = "hello";

         container.Controls.Add(lb);
         container.Controls.Add(cmd);
      }
      else if(strWhichTemplate == "FooterTemplate")
      {
         System.Web.UI.MobileControls.Label lb = new System.Web.UI.MobileControls.Label();
         lb.Text = "FooterTemplate";
         container.Controls.Add(lb);
      }
      
   }
}

</script>
<body>
   <mobile:Form id="Form1" runat="server" OnInit="Form_Init">
   </mobile:Form>
</body>

Special Considerations for Using Device-Specific Templates

When mixing device-specific markup languages with mobile controls, you must ensure consistency, based on what the mobile controls are rendering. Intelligent detection and adaptation for mixed device-specific and device-independent markup is not supported.

For example, note the alignment setting on the first Panel control and the Label control in the following partial code sample.

<mobile:Panel runat=server alignment="right">
<DeviceSpecific>
   <Choice Filter="isWML11">
      <ContentTemplate>
         <table columns="2" align="LR">
      <tr><td>
      </ContentTemplate>
   </Choice></Devicespecific>
</mobile:panel>

<Mobile:Label id="label1" runat=server Text="HELLO, HOW ARE YOU?" 
   alignment="left">
</Mobile:Label>
<mobile:Panel runat=server>
   <DeviceSpecific>
      <Choice Filter="isWML11">
         <ContentTemplate></td><td>
         </ContentTemplate>
      </Choice>
   </Devicespecific> 
</mobile:panel>

WML <p> elements are used to render non-default alignment. In the preceding example, the second Label control is within a WML <td> tag, and the <p> tag generated for the second Label control is incorrectly rendered by the browser because it is located within the <td> tag.

In this case, the Label control does not inherit the alignment from the first Panel control, so it generates a <p> tag for its alignment. However, a <p> tag cannot be added in this situation. This is not a common situation, but you can work around the problem by marking the Label control as visible if the target device is not WML-based and by making the text of the Label control specified within the template.

Arbitrary Device Specific Markup

In some cases, you might want to insert arbitrary markup for a specific device or type of device. To enable this, ASP.NET mobile Web Forms provides a ContentTemplate template for the Panel control. If a selected choice contains a ContentTemplate template, the control renders by using the template instead of its usual contents.