When working with templates, you may have times when you want to initialize a template only if certain data sets are available for it to process. Templates have an attribute available to them for exactly this use case: require.

The require attribute accepts a string of comma-separated keys that refer to their associated data sets, generated through sources like data pipes. If any of the required data sets are not available, the template rendering process will be deferred until a time when they are all available:

<script type="text/os-template" require="Viewer, Ratings">
   Welcome ${Viewer.name}<br />
   You most recently rated ${Ratings.last.title} with a rating
   of ${Ratings.last.rating}
</script>

In the preceding example, we require the data objects with keys set to Viewer and Ratings to be available before the template is rendered.

As we have already covered in our discussion of data pipelining, data pipes may be updated with the opensocial.data.DataContext.putDataSet(...) JavaScript method. This means that our core data can change at a whim, but we have not yet explored a method for updating the templates that implement that data.

Templates can be set to automatically update when a data source they are implementing changes. This provides wonderful functionality, because it means that we don’t have to manually update the HTML nodes when we need to update a piece of the data.

To activate the auto-update functionality, we add a new attribute, autoUpdate, to our template script block and set its value to true. Now, when the data pipes implemented in the template are updated via the opensocial.data.DataContext.putDataSet(...) method, our template will automatically rerender its content based on the new data set:

<script type="text/os-template" require="Viewer" autoUpdate="true">
  Hello ${Viewer.name}!
</script>

<p>Welcome to our site</p>

<script type="text/javascript">
   //update the viewer object
   function updateViewer(viewerObj) {
      opensocial.data.DataContext.putDataSet("Viewer", viewerObj);
   }
</script>

In the preceding example, a greeting will be displayed to the current viewer. When the Viewer data pipe is updated via the updateViewer function, the template will be rendered and its markup updated. Any markup outside the template’s bounds—in this case, <p>Welcome to our site</p>—will not be updated.

Template structures provide a number of features and functionality to reduce code bloat, promote usability, and enable code reuse. At the same time, embedding all content within a single template block is not always the most ideal setup for debugging code structure.

Within a template, developers can add XML references to include custom tags. These custom tags give the developer a way to define blocks of markup and functionality—such as button sets, template structures, message functions, and many other features—that can be reused easily within other sections of the template. This provides a clean working interface for the code, allowing for quicker development with a focus on modularity.

You can implement a custom tag quickly using a few features. The custom tag’s look and feel is similar to the standard development of other OpenSocial templates:

<script type="text/os-template"
        tag="app:login"
        xmlns:app="http://www.mysite.com/app">
   <form action="login.php" method="post">
      <p>
         <label for="username">Username:</label>
         <input type="text" name="username" />
      </p>
      <p>
         <label for="password">Password</label>
         <input type="hidden" name="password" /><br />
      </p>
      <p>
         <input type="submit" value="Login" />
         <input type="reset" value="Reset" />
      </p>
   </form>
</script>

The main difference in this implementation is the tag attribute attached to the script node, which indicates that the block of markup following it will be created and used as a custom tag. In the preceding example, we create a login tag to allow us to display a username/password login at any point in our application.

Custom tags must be implemented within a namespace. In addition to the preceding method, which contains a custom URL for the app namespace, you can create these namespaces using the following syntax:

os.createNamespace("app", "http://www.mysite.com/app");

Creating custom tags in the default HTML namespace is not allowed, so you must employ one of the two implementations I’ve described.

When you wish to incorporate the custom tag in your template markup, you can simply include the XML node of the same name as the custom tag namespace:

<script type="text/os-template">
  <app:login/>
</script>

In addition to containing blocks of HTML, custom tags also support parameter structures within their definition. This helps in allowing code to be reused at different places within a gadget. These parameters are passed back through to the template being used and can be set up as XML attributes or elements to leverage the stored data sets:

<script type="text/os-template">
  <app:preferences name="Lucas Bell">
    <template theme="dark" />
    <template language="EN" />
  </app:preferences>
</script>

We can set access to this stored data within our visual template:

<script type="text/os-template"
        xmlns:app="http://www.mysite.com/app"
        tag="app:preferences">
   <div id="themeWrap" class="${My.template.theme}">
      Theme preferences for: ${My.name}<br />
      Language Requested: ${My.template.language}
   </div>
</script>

Much like creating custom tags to reuse markup throughout your application sections, here you create custom tags to reuse stored data sets throughout the template building process. This is also an excellent way to separate data and visualization layers, promoting debugging ease and code readability.