Template Sets and Templated Controls

Artigo
11/03/2006

ASP.NET provides templated controls that expose a number of template properties that define the control's content and layout. 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 you to significantly customize the appearance of controls at run time, based on the device.

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 inside 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 markup.

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.

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 selected 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

To programmatically set properties of a control in a template, you must obtain a reference to the naming container and use the FindControl method to find the control. You can then set its properties. The following example illustrates this technique.

Note
Because style sheet information is loaded prior to when you can programmatically change the StyleReference property, changing it in code has no effect.

void Page_Load(Object sender, EventArgs e)
{
    // Iterate through the controls in the form.
    foreach(Control c in Form1.Controls)
    {
        if(c.GetType()) == typeof(TemplateContainer)
        {
            // Get the link control.
            Link ctrl = (Link)c.FindControl("myLink");
            if (ctrl != null)
            {
                // Set the text and url properties.
                ctrl.Text = "Home Page";
                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 ASP.NET Mobile Controls QuickStart.

Style Templates vs. Style Properties

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. For more information, see Styles.

Dynamically Added Templates

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" %>
<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 = 
            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>

<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
  <mobile:form id="form1" runat="server" OnInit="Form_Init">
  </mobile:form>
</body>
</html>

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 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> element, and the <p> element generated for the second Label control is incorrectly rendered by the browser because it is located within the <td> element.

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 pages provide a content template for the Panel control. If a selected choice contains a content template, the control renders using the template instead of its usual contents.

Compartilhar via