When rendering data within escaped expressions or loops (i.e., not os:Repeat or os:If blocks), developers run into the issue that because all data is displayed as strings, they’re prevented from using a lot of rich data sets. When you’re using third-party data sources that are not necessarily trusted, this practice is a good option for sanitizing content. When a part of the source data is trusted, however, we need a means of rendering that data with the markup intact. This is where the os:Html tag comes in handy.

os:Html provides a means for a developer to render a block of data without having it automatically escaped and displayed as a string. The markup is rendered intact and applied to the template.

You use os:Html through the code attribute of the tag. Any data values within the code attribute are evaluated as a string and then rendered as HTML. For instance, if you have an object containing the viewer’s friends, and in that object you also have a name and a badge that contains HTML, you can easily render the badge HTML using the os:Html tag as follows:

<div repeat="${Top.ViewerFriends}">
   Name: ${Cur.name}<br />
   Badge:<br />
   <os:Html code="${Cur.badge}" />
</div>

Once rendered, name will be displayed as an escaped string and badge will be displayed as markup.

When working with custom tags containing reusable blocks of content, you may need to render that content within the template markup. You can do this using the os:Render tag.

os:Render allows you to define a location from which to pull the custom block of content using the content attribute of the tag. The value of the content attribute in this case should be an immediate child of an os-template block.

For example, let’s say we are building an application that has multiple page structures but maintains a universal header and footer. We can use the os:Render tag to specify the sections where we want to integrate this content:

<script type="text/os-template"
        tag="app:pageTemplate"
        xmlns:os="http://opensocial.org/templates"
        xmlns:pageTemplate ="http://www.mysite.com/app">
   <div class="header"><os:Render content="header"/></div>
   This is the content of my current page, using a universal
   header and footer
   <div class="footer"><os:Render content="footer"/></div>
</script>

Within an os-template script block, we define the XML namespaces that will be used, and then insert the tag attribute to refer to the custom tag that we will use to define the header and footer. We then implement the content of our template. At the beginning and end of the content block, we have two div nodes. These nodes contain our os:Render tags, which specify the node that will need to be inserted into that section.

In an alternate script block, we can define the custom tag nodes that will be used for the content of the header and footer sections:

<script type="text/os-template"
        xmlns:app="http://www.mysite.com/app"
   <app:pageTemplate>
      <app:header>
         <div id="navItems">
            <a href="/home">Home</a> |
            <a href="/profile">Profile</a> |
            <a href="/tasks">Tasks</a>
         </div>
      </app:header>
      <app:footer>
         <div id="copyright">
            Copyright &copy; 2011
         </div>
      <app:footer>
   </app:pageTemplate>
</script>

Our script block defines the XML namespace that we will use for the custom tags, and then defines the custom tag that should be used for these values, app:pageTemplate. Within app:pageTemplate, we specify our header and footer nodes with their associated content, which is what will be inserted via the os:Render tags. If there were multiple child nodes with the same name (e.g., two header nodes), the results of both nodes would be merged and returned as one block.

When rendered, the template will generate the following markup:

<div class="header">
   <div id="navItems">
      <a href="/home">Home</a> |
      <a href="/profile">Profile</a> |
      <a href="/tasks">Tasks</a>
   </div>
</div>
   This is the content of my current page, using a universal
   header and footer
<div class="footer">
   <div id="copyright">
      Copyright &copy; 2011
   </div>
</div>

Using os:Render and custom tags can help increase code reuse, general usability, and ease of debugging. When you’re building out a large-scale application, tags like these can vastly reduce the amount of time spent on development and on repairing bugs.