Introduction

Templates describe reusable fragments of XHTML nodes and script. Templates and Fragments are differentiated by intent: Templates describe a reusable container, may be directly loaded through Application Components, receive special virtual method invocations, and may spawn their own Application Space. Fragments describe reusable chunks of content and script for use by other Fragments or Templates.

Loading a template causes the ontemplateload message to be published.

Templates as Application Spaces

Enabling Application Spaces for Templates is optional in general, but preferred when dealing with multiple forms and objects with the same names, or when using declarative elements defined by Application Space definitions.

Reference Identifier

The Reference Identifier is used to establish uniqueness within an Application Space, as opposed to XHTML identifiers and names which are unique to the entire form or page. Several Hemi services cooperatively support the Reference Identifier feature.

Using a reference identifier does not preclude using a global identifier or name, but is required to differentiate identical nodes that are used multiple times.

Reference Identifiers are specified as constructor arguments, are with the rid attribute on XHTML nodes defined within Application Spaces.

Useful Application Space Definitions

The following Application Space Definitions are useful within Templates for loading fragments and styles.

• import-xml : Used to include a block of XML, such as another template or fragment, in the current context.
• import-style : Used to import an external CSS stylesheet.

Syntax

Basic Template Syntax

<Template Title = "Friendly Title" id = "templateId">
<p>Some XHTML</p>
</Template>

Basic Fragment Syntax

<html-fragment>
<p>Some XHTML</p>
</html-fragment>

EL Expressions

Templates and Fragments (except embedded-script) support token resolution through the backing Application Component to resolve context and object references, and form and bean values.

• ${this} : Evaluates to a script statement used to identify the Application Component object, for use in invoking methods from inline event handlers.
• ${this.id} : Evalutes to the Application Component object identifier.
• ${hemi.hemi_base} : Evaluates to the configured Hemi base path.
• ${form.fieldName} : Evaluates to the virtualized form field value.
• ${bean.beanName} : Evaluates to the bean object identifier. Used in conjunction with the bind attribute for form elements.
• ${bean.beanName.property} : Evaluates to the value of the bean property.

Template Beans

JSON script constructs may be designated as beans by using the Application Component setBean and getBean methods.

Using JSON beans allows developers to leverage the binding feature of the Form Service to associate script data with form fields. Integrated EL support allows bean properties to be displayed in the template.

The following fragment embedded script demonstrates setting up a JSON bean, where the bean name is scoped to the Application Component instead of being globally unique.

<html-fragment>
<embedded-script><![CDATA[
embedded_init : function(){
   if(!this.getBean("myBean")){
      var oObject = {customText : "My Custom Text"};
      this.setBean(oObject, "myBean");
   }
}
]]></embedded-script>
</html-fragment>

The following Template demonstrates binding an input field to the bean. Note that the JSON property must be the same name as the field name or reference identifier.

<Template>
   <p>
      <input type = "text" name = "customText" bind = "${bean.myBean}" />
   </p>
</Template>

And, the following Template demonstrates accessing the value of the bound property.

<Template>
   <p>
      Bean Value: ${bean.myBean.customText}
      <br />
      Bean ID: ${bean.myBean}
      <br />
      Equivalent Form EL: ${form.customText}
   </p>
</Template>

And, because the bean value is synchronized with the virtual form field, then the object property holds the latest value of the form field.

<Template>
   <p>
      Bean EL: ${bean.myBean.customText}
   </p>
<embedded-script><![CDATA[
   template_init : function(){
      var oBean = this.getBean("myBean");
      if(oBean){
         /// oBean.customText holds the current form field value
      }
   }
]]></embedded-script>
</Template>

Embedded Script

Templates and Fragments use a special script construct, embedded-script. This CDATA block uses a hash structure to define functions which persist for the duration of the template, and are removed when the template is changed or unloaded.

Embedded Script Syntax

<embedded-script><![CDATA[
   myFunction : function(){
   }
]]></embedded-script>

Embedded Script API

Embedded Script statements include several virtual methods.

• local_template_init : Invoked after a template has been loaded, and after all template and fragment initializers have been invoked.
• template_init : Volatile. May exist once per template, and is invoked after a template has been loaded, and after all fragment initializers have been invoked. Removed when the template is unloaded or changed.
• template_destroy : Volatile. May exist once per template, and is invoked before a template is unloaded, and before the fragment destroy methods are invoked. Removed when the template is unloaded or changed.
• fragment_init : Volatile. May exist once per embedded-script block and is invoked in order of discovery. Removed when the template is unloaded or changed.
• fragment_destroy : Volatile. May exist once per embedded-script block, is invoked before a template is unloaded, and after the template destroy methods are invoked. Removed when the template is unloaded or changed.

Framework Template and Fragment Tools

The Hemi JavaScript Framework includes a few Templates and Fragments for reuse in other Templates and Fragments.

• Templates/TemplateTools.xml : Includes a number of helper methods for serializing Virtual Forms and resolving object references.
• Fragments/IOGrid.xml : Includes a reusable pagination control for data lists.

Example

The following example demonstrates using a token for binding an event handler to a local function, using a reference identifier to identify an input field, using an imported script from TemplateTools.xml to retrieve the value of the input field when the button is clicked, and using the setInnerXHTML method to copy the value into a paragraph element.

<Template Title = "Friendly Title" id = "templateId">
   <import-xml src = "Templates/TemplateTools.xml" id = "TemplateTools" />
   <p>
      <input type = "text" rid = "someText" />
      <input type = "button" value = "Check" onclick = "${this}.DoCheck()" />
   </p>
   <p rid = "lblValue">[ click for value ]</p>
   <embedded-script><![CDATA[
      DoCheck : function(){
         /// Long hand
         var sVal1 = Hemi.data.form.service.getValue("someText",this.getTemplateSpace().space_id);
         /// Using the TemplateTools-provided method
         var sVal2 = this.GetFormValue("someText");
         Hemi.xml.setInnerXHTML(this.GetElementByRID("lblValue"), sVal2);
      }
   ]]></embedded-script>
</Template>

Loading Templates

Given any application component that is bound to a node, templates are loaded with the loadTemplate method or Quick Fixes.

Using Quick Fixes

The easiest way to setup and Application Component and load a template is to use a Quick Fix. Given some template, Templates/MyTemplate.xml:

<p template = "MyTemplate"></p>

If the template resided in /SomeDir/MyTemplate.xml:

<p template = "/SomeDir/MyTemplate.xml"></p>

To load a template into the window application component when the element is clicked, the window_control component may be used. Note: Quick Fixes don't stack, so in the following example, the template attribute is processed by window_control, whereas in the previous example, template was processed by XHTML Component which supported the shorthand.

<p component = "window_control" template = "Templates/MyTemplate.xml"></p>

Using the API

Loading a template from the API is very straightforward, and is the primary method for switching content.

The following example demonstrates loading a template using a reference to a component.

var oComponent = ...;
/// optional: Separate the contents of the template from the parent application space
oComponent.setTemplateIsSpace(true);
oComponent.loadTemplate("Templates/MyTemplate.xml");

The following example demonstrates using loadTemplate to change the view from the current template.

<Template Title = "Friendly Title" id = "templateId">
   <import-xml src = "Templates/TemplateTools.xml" id = "TemplateTools" />
   <p>
      <input type = "button" value = "Next" onclick = "${this}.DoNext()" />
   </p>
   <embedded-script><![CDATA[
      DoNext : function(){
         this.loadTemplate("/Path/NextFile.xml");
      }
   ]]></embedded-script>
</Template>

API: Application Component