Zimlet Developers Guide:Templates

Revision as of 02:19, 23 December 2009 by Sposetti (talk | contribs) (Example)

Zdg-6-menu-icon-zimbra.jpg Introduction Zdg-6-menu-icon-green-flag.png Getting Started Zdg-6-menu-icon-terminal.png Dev Environment Setup Zdg-6-menu-icon-gear.png
Developing Zimlets
Proxy Servlet Setup
Firefox and Firebug
Templates
Troubleshooting
Zdg-6-menu-icon-library.jpg API Specifications Zdg-6-menu-icon-checkbox.jpg Example Zimlets


Overview

As you start writing user interfaces for your zimlet (for example, in the form of dialogs), you'll start writing more and more HTML code. Simple HTML code can be written in JavaScript in your zimlet. For example, this is the HTML code that displays a simple table:

<table cellpadding="2" cellspacing="0" border="0" width="100%">
  <tr>
    <td colspan="2">
    This is a sample table HTML code...
    </td>
  </tr>
</table>

If you want to use this HTML in your zimlet, you can use an Array to generate the code:

var html = new Array();
var i = 0;
html[i++] = "<table cellpadding=\"2\" cellspacing=\"0\" border=\"0\" width=\"100%\"><tr><td colspan=\"2\">";
html[i++] = "This is a sample table HTML code...";
html[i++] = "</td></table>";
return html.join("");

As your pages get more advanced, keeping track of escaping the double-quotes and making sure your HTML code is properly formatted, to name a few challenges, makes this method of integrating HTML with JavaScript more difficult to manage.

That's where Templates come in. Templates provide a mechanism to write HTML code in a file and compile that code into JavaScript to be used with your zimlet. This allows you to separate the HTML presentation logic from the zimlet application code, making it easier to write HTML for your zimlets.

Template Life Cycle

The life cycle of a template involves these stages:

  1. Creating the Template
  2. Compiling the Template
  3. Including the Template
  4. Calling the Template

This section will walk through the creation of a Template for an example zimlet called "com_zimbra_simpletemplate".

Creating the Template

This stage involves writing the HTML code for the template in the .template file (i.e. the "Template File"). The Template File basically looks like an HTML file but with some dynamic capabilities. The HTML code in the Template File should be wrapped in a <template> tag and have a template ID specified. The Template File should be placed in a "templates" directory below the zimlet base directory.

Example

  1. Browse to your zimlet base directory:
    cd com_zimbra_simpletemplate
    
  2. Create a "template directory:
    mkdir templates
    
  3. Create a file named "Simple.template".
  4. Open the file and insert the following text:
    <template id="Simple">
      <table cellpadding="2" cellspacing="0" border="0" width="100%">
        <tr>
          <td colspan="2">
          This is a sample table HTML code...
          </td>
        </tr>
      </table>
    </template>
    
  5. Save the file. You now have created the template.

Compiling the Template

The Template needs to be compiles before being used in your zimlet. Compiling converts the HTML code into JavaScript so the zimlet can call the template. This stage is often the most troublesome part of using Templates. To that end, we are including a link to a Zimlet Template Generator utility. Note: this utility is provided in early-access form and is provided without support at this time.

Example

  1. Download the Zimlet Template Generator utility: zimlet-template-generator-v0-9.zip
  2. Unzip the package to obtain the ant build.xml file.
  3. Using ant, call this buildfile with the following arguments:
    ant -Dzimlet.name=com_zimbra_simpletemplate -Dtemplate.name=Simple.template -D-Dtemplate.dir=/opt/my/path/to/com_zimbra_simpletemplate/templates
    
    Argument Required/Optional Description
    zimlet.name Required The name of the zimlet. For example, com_zimbra_simpletemplate
    template.name Required The name of the template file. For example, Simple.template
    template.dir Required The directory path to the template file location. This path can be absolute or relative to where the ant buildfile is run. For example, /opt/my/path/to/the/zimlet/file
  4. The compiled Template File "Simple.template.js" will be created next to the "Simple.template" file.

Including the Template

Not that your template is compiled, you need to include that file with your zimlet. To do this, in the Zimlet Definition File, you should add an <include> element.

For example:

<include>templates/Simple.template.js</include>

See Zimlet Definition File Reference for more information on the Zimlet Definition File and the <include> element.

Calling the Template

After you have packaged and deployed your zimlet (note: be sure to include the "templates" directory in your package), from the Zimlet Handler Object, you can use JavaScript to call the template and retrieve the HTML code:

var html = AjxTemplate.expand("com_zimbra_simpledialogtemplate.templates.Simple#Simple");		

The syntax for the name of the template is: {zimlet-name}.{templates-dir}.{template-name}#{template-id}

Dynamic Elements

You can use dynamic elements with the template to call JavaScript or to act on JavaScript objects. When calling the template, data can be optionally passed using an array. That data can be accessed inside of the template using data namespace and "<$= $>" syntax.

For example, in your template (before compilation,) you have:

The phone number is <$=data.phone$>. Lines are open 24/7.

When calling the template, you should include the phone data:

var dataArray = {phone: "123-456-7890"};
canvas.innerHTML = AjxTemplate.expand("com_zimbra_simpledialogtemplate.templates.Simple#Simple", dataArray);

The resulting HTML code will be:

The phone number is 123-456-7890. Lines are open 24/7.

You can also inline JavaScript code in your template (before compilation) using the "<$= $>" syntax for a single-line and "<$ $>" for multi-line.

Do something single-line <$=AjxImg.getImageHtml("Telephone")$>.
Do something multi-line:
<$
var s = AjxImg.getImageHtml("Telephone")
// do something
// do something
// do something
$>

Useful Links


Verified Against: Zimbra Collaboration Suite 6.0 Date Created: 12/22/2009
Article ID: https://wiki.zimbra.com/index.php?title=Zimlet_Developers_Guide:Templates Date Modified: 2009-12-23



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »


Jump to: navigation, search