= hi5.template =
hi5.template is a JavaScript templating library that helps separate JavaScript data, logic and HTML.  It's based on XML templates with string substitution, and features custom tag support which is based on standard DOM operations.

These custom tags allow your application to deeply integrate into various integration points that the hi5 platform has provided.

 1. [wiki:CustomTags#hi5.templateTags hi5.template Tags]
   * template
   * if
   * else-if
   * else
   * for-each
   * apply-template
   * hi5:name
   * hi5:profile-pic
 1. [wiki:CustomTags#hi5.templateExample hi5.template Example]
 1. [wiki:CustomTags#Examplecustomtag Example Custom Tags]
 1. [wiki:CustomTags#hi5.templateFunctions hi5.template Functions]

----
=== hi5.template Tags ===
 * <template xmlns:hi5="http://www.w3.org/1999/xhtml"></hi5:template>[[BR]]Encapsulates a template.  XML requires data to have one body tag.
 * <if test="expression"></hi5:if>[[BR]]If Javascript expression is true, evaluate child elements.
 * <else-if test="expression"></hi5:if>[[BR]]Else if Javascript expression is true, evaluate child elements.
 * <else></hi5:if>[[BR]]Else evaluate child elements.
 * <for-each var="variable" source="data-source"></hi5:for-each>[[BR]]Iterates over data-source, which must be an array.  variable is assigned for each item.
 * <apply-template name="template-name"/>[[BR]]Call another template, which is passed the current input, output and context
 * <hi5:name person="person-object"/>[[BR]]Display a member's name, where person is an OpenSocial Person object.
 * <hi5:profile-pic [id="member-id" | person="person-object"] size="thumb | small"/>[[BR]]Display a member photo using a member id or a OpenSocial Person object. Thumbnail size is 50x50, while small is 100x100.
 * <hi5:message key="property" [param="value"]*/>

===  ===
=== hi5.template Example ===
{{{
#!xml
<?xml version="1.0" encoding="UTF-8"?>
<Module>
}}}
==== ModulePrefs declarations ====
{{{
#!xml
    <ModulePrefs title="My Friends (hi5.template)" summary="Display the owner's friends" description="This is a sample app using hi5.template which display's the owner's friends" title_url="http://www.hi5.com"
     icon="http://images.hi5.com/images/icons/_/update_skin.png" thumbnail="http://images.hi5.com/images/opensocial/opensocial_120x60.jpg"
     author="Mike Austin" author_email="name@domain.com" author_affiliation="hi5" author_location="San Francisco, CA">
        <Require feature="opensocial-0.7"/>
        <Require feature="dynamic-height"/>
        <Require feature="views"/>
        <Locale messages="http://www.sandbox.hi5.com/friend/apps/developer/app/get/xml/4512"/>
    </ModulePrefs>
}}}
{{{
#!xml
    <Content type="html" quirks="false" view="default,profile">
    <![CDATA[
}}}
==== Style and Javascript includes ====
{{{
#!xml
        <link rel="stylesheet" type="text/css" href="http://images.hi5.com/images/styles/hi5_common_20080222.css"/>
        <script type="text/javascript" src="http://images.hi5.com/images/js/hi5_template_20080310.js"></script>
        <script type="text/javascript" src="http://images.hi5.com/images/js/hi5_tags_20080310.js"></script>

        <style>
            #page-content .friend-tile {
                float: left; display: inline; width: 270px; margin: 0 0 10px 10px; border: 1px 
                solid #cccccc; padding: 10px;
                background: url(http://images.hi5.com/images/graphics/gray.gif) repeat-x; background-color: #f6f6f6;
            }
           #page-content .friend-tile .image {
               float: left; display: inline; width: 100px; height: 100px; overflow: hidden;
               padding: 5px; margin-right: 10px; background: white; border: 1px solid #cccccc;
           }
           #page-content .friend-tile .name {
               display: block; margin-bottom: 5px; font-weight: bold; background: #eaeaea; 
               zoom: 1;
           }
        </style>
}}}
==== h5.template declaration ====
{{{
#!xml
        <!-- Template that iterates through friends and invokes the "friends-tile" template -->
        <script type="text/xml" id="template">
            <template xmlns:hi5="http://www.w3.org/1999/xhtml">
                <div>
                    Viewer: ${' '} <hi5:name uid="viewer" linked="true"/> 
                    <hi5:profile-pic uid="viewer" size="small"/>
                    ${' '} Owner: ${' '} <hi5:name uid="owner" linked="true"/> 
                    <hi5:profile-pic uid="owner" size="small"/>
                    ${' '} 1000: ${' '} <hi5:name uid="1000" linked="true"/> 
                    <hi5:profile-pic uid="1000" size="small"/>
                </div>
                <br/>
                <for-each var="friend" source="friends.asArray()">
                    <div class="friend-tile">
                        <div class="image">
                            <hi5:profile-pic person="friend" size="small"/>
                        </div>
                        <div class="details">
                            <a class="name" href="${friend.getField(opensocial.Person.Field.PROFILE_URL)}">
                                <hi5:name person="friend"/>
                            </a>
                            <hi5:message key="person.sex" sex="${friend.getField(opensocial.Person.Field.GENDER)}"/>
                        </div>
                    </div>
                </for-each>
                <div class="clear">&#160;</div>
            </template>
        </script>
}}}
==== Template output element ====
{{{
#!xml
        <!-- Output element, parameter to hi5.template.apply() -->
        <div id="page-content"></div>
}}}
==== Application initialization ====
{{{
#!xml
        <!-- Start of application -->
        <script type="text/javascript">
            var hi5AuthToken;
			
            gadgets.util.registerOnLoadHandler(function() {
                var env = opensocial.getEnvironment();
                var params = gadgets.views.getParams();
                hi5AuthToken = params['Hi5AuthToken'];
				
                var request = opensocial.newDataRequest();
                request.add(request.newFetchPersonRequest('OWNER'), 'owner');
                request.add(request.newFetchPersonRequest('VIEWER'), 'viewer');
                //params[opensocial.DataRequest.PeopleRequestFields.MAX] = 10;
                request.add(request.newFetchPeopleRequest('OWNER_FRIENDS', {'max': 10}), 'friends');
				
                request.send(onLoadUsers);
            });

            function onLoadUsers(response) {
                var owner = response.get('owner').getData();
                var viewer = response.get('viewer').getData();
                var friends = response.get('friends').getData();

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

                gadgets.window.adjustHeight();
            }
        </script>
}}}
{{{
#!xml
    ]]>
    </Content>
}}}
{{{
#!xml
</Module>
}}}
===  ===
=== Example custom tag ===
{{{
#!xml
hi5.template.addTag('userpic', function(input, output, context) {
        var src = input.getAttribute('src'); var result = hi5.template.replace(src, context);
        var img = document.createElement('img'); img.src = result; img.width = '70'; img.height = '70';
        output.appendChild(img);
});
}}}
=== hi5.template Functions ===
hi5.template.load(template_string) Uses the browser's DOMParser or Microsoft.XMLDOM to create an XML template from a string.

hi5.template.apply(input_node | input_string, output_node | element_id, [context]) Recursively traverses the input template and performs JavaScript eval substitution and invokes custom tags. If input or output is a string, it will use the element with that name.  Otherwise, it expects a DOM node.

hi5.template.replace(templated_string, object_context) Replaces any occurrences of ${} with eval'ed JavaScript value, for example ${friend.name} is ${friend.age} years old.

hi5.template.addTag(tag_name, tag_function) Add a tag callback function.  The function is passed the input template, the output DOM being created, and an object context. The object context is used for storing foreach variables such as index and length, along with dynamic variable names defined in foreach "var" attributes.

[[BR]][wiki:hi5TemplateLibraryDocumentation ---]
[[BR]][wiki:hi5/Scratch ---]