hi5.template Library

Overview

The hi5.template library is a browser side, Javascript library which enables you to fuse Javascript data and logic into your HTML. It simplifies writing localized apps by providing a message resource tag, <os:message key=”resource” />, which eliminates the need to build messages and HTML with Javascript. To ease transitioning to language resource files, you can provide the message resource directly in the message tag. For example: <os:message key=”received_gift” gift=”pizza” friend=”Joe”>You received a ${gift} from ${friend}</os:message>. Also, using the hi5.template library allow future compatibility with our user generated content inline-translation tool.

The template is straightforward, with only a few conventions: ${} for variable substitution, <for-each> for iteration, <if>/<else> for conditional logic, and <os:message> for gadget resource localization. There is also a <set> tag for storing the output of tags, and <os:name> and <os:profile-pic> convenience tags.

The library is based on XML templates, which can be embedded in <script type="text/xml"> tags or loaded remotely with gadgets.io.makeRequest(). Here's an example which iterates over an array of friends and displays their thumbnail photo:

application.xmlt

<stylesheet xmlns:os="http://www.w3.org/1999/xhtml">

<template name="my-template">

<for-each var="friend" source="friends.asArray()">

<img src="${friend.getField('thumbnailUrl')}" />

</for-each>

</template>

</stylesheet>

application.html

<div id="my-content"></div>

<script type="text/javascript"> gadgets.io.makeRequest('http://www.hi5.com/app.xmlt',

function(response){hi5.template.parse(response.data);

hi5.template.apply('my-template', 'my-content', {photos: friends});

});

</script>

How To Add Templates To Your Code

Here’s an example of where you would put the library in your application XML: <Content type="html" quirks="false" view="default"><![CDATA[

<link rel="stylesheet" type="text/css" href="http://www.company.com/app/application.css"> <div id="page-content"></div> <script type="text/javascript" src="http://www.company.com/hi5_template_20080430.js"></script> <script type="text/javascript" src="http://www.company.com/app/application.js"></script>

</Content>

Downloading The Library

Here’s the zip file with library and documentation: http://static.hi5.com/images/opensocial/hi5_template_20080430.zip

hi5.template Tags

There are four core tags used for iteration, conditional logic, resource localization and variable assignment, and two convenience tags for member names and thumbnails. A detailed description of each follows.

 for-each

<for-each var="variable" source="collection"> </for-each>
Iterates over a collection, passing the current item to the template as variable

Parameters

var A variable name that is used for each collection item
source An array or object, which it iterates over

Examples

<ul> <for-each var="friend" source="friends"> <li>${friend.name}</li> </for-each> </ul>

 if-test

<if test="expression"> </if><else-if test="expression"></else-if><else></else>
Applies the body of the tag if the Javascript expression evaluates to true

Parameters

test A Javascript expression that evaluates to a boolean

Examples

<if test="index % 2 == 0"> This is an even row </if><else> This is an odd row </else>

 set

<set var="variable"> body </set>

Set a variable in the current scope, storing the output of the body

Parameters

var A variable name that is used to store the body
body The body HTML, which can include template tags

Examples

<set var="title"> <os:message key="received_gift" gift="${gift}" /> </set>
<img src="http://images.hi5.com" title="${title}">

 os:message


<os:message key="resource" [param="value"]* /><os:message key="resource" [param="value"]*> message </:hi5:message>

Look up a message from a resource bundle and perform variable substitution

Parameters

key A message resource name in a resource bundle
param* Each variable substitution name and value to be replaced in the message

Examples

<messagebundle> <msg name="received_gift">You received a ${gift}</msg></messagebundle><for-each var="gift" source="gifts"><hi5:message key="received_gift" gift="pizza" /></for-each>

<hi5:message key="missing-key">Default message</hi5:message>

 os:name

<os:name person="person" | uid="viewer | owner | uid" [linked="true"]/>

Display a member's name, by passing an OpenSocial Person object, 'viewer', 'owner', or a member id.
Note: use of uid generates an OpenSocial request. Use newFetchPeopleRequest for lists of members.

Parameters

person An OpenSocial Person object to be used as the member
uid The values 'viewer', 'owner', or the id of a member
linked Set to true to have the name linked to the member's profile

Examples

<os:name person="friend" /><os:name uid="12345" linked="true" />

{{{#!html<div style="padding: 0 0 0 2; text-align: left; background: lightgrey">&nbsp;os:profile</div>}}}

 os:profile

<os:profile-pic person="person" | uid="viewer | owner | uid" [size="thumb | small"] />
Display a member's profile photo, by passing an OpenSocial Person object, 'viewer', 'owner', or a member id.
Note: use of uid generates an OpenSocial request. Use newFetchPeopleRequest for lists of members.

Parameters

person An OpenSocial Person object to be used as the member
uid The values 'viewer', 'owner', or the id of a member
size The size of the thumbnail, a 50x50 thumb or 100x100 small

Examples

<for-each var="friend" source="friends"><os:profile-pic person="friend" /></for-each>
<os:profile-pic uid="12345" size="small" />

hi5.template Functions

There are three core functions provided to work with templates and template related processing. You can parse templates from text, apply them, and perform message substitution in Javascript.

 hi5.template.parse(templates_text)

Parse template text, such as from a Javascript string or a makeRequest call.

Parameters

templates One or more XML templates contained in a stylesheet tag

Return value None

Examples

hi5.template.parse(document.getElementById('templates'));
gadgets.io.makeRequest('http://www.hi5.com', function(response) { hi5.template.parse(response.data); });

 hi5.template.apply(template_name, output_element, context_data)

</div>

Recursively applies a template or template node and appends the result to an element node

Parameters

input A named element-id such as 'template', or an XML or browser DOM
output A named element-id such as 'content', or a browser DOM node
context A context object used to pass data to the template

Return value

None

Examples

hi5.template.apply(document.getElementById('template'), 'content', {friends: data});hi5.template.apply('template', 'content', {owner: owner, viewer: viewer});

 hi5.template.message(resource_key, substitutions)

Look up a message from a resource bundle and perform variable substitution

Parameters

resource A resource name in message bundle
substitutions A hash map of variable name substitutions to be replaced in the string

Return value

A string representing the message with variable substitution applied

Examples

hi5.template.message('received_gift', {name: 'Joe', gift: 'pizza'});

Close