template-tal

v0.2.9

Published

2 years ago

XML Lightweight Template Attribute Language implementation for Javascript

Downloads

128

0High
0Medium
0Low

jhiver

tal zpt template xml

template-tal

TAL Implementation for nodejs. TAL is an XML templating language. template-tal is suitable for node.js or client-side, and has no dependancies.

** UPDATE ** as from 0.2.0, template-tal supports invoking synchronous & asynchronous functions from the template expressions, see below.

SYNOPSIS

In your Javascript code:

let tal  = require ('./lib/template-tal')
let xml = `
  <html>
    <body>
      <p tal:content="foo">Dummy Content</p>
      <p tal:content="bar()">Dummy Content</p>
      <p tal:content="baz()">Dummy Content</p>
    </body>
  </html>
`

let data = {

  // value
  foo: "FOO",

  // function
  bar: function() { return "BAR" },

  // async function
  baz: function() {
    return new Promise(function(resolve) {
      setTimeout(function() { resolve('BAZ')}, 100)
    })
  }
}

tal
  .process(xml, data)
  .then(function(result){
    console.log(result)
  })

It should produce something like this:

  <html>
    <body>
      <p>FOO</p>
      <p>BAR</p>
      <p>BAZ</p>
    </body>
  </html>

SUMMARY

Template Attribute Language https://en.wikipedia.org/wiki/Template_Attribute_Language is an amazingly clever specification on how to template XML documents. It does so simply by adding extra attributes to your XML Template file.

The specification has been implemented in many languages, including Javascript, but the two existing Javascript implementation either depend on external libraries (jstal/E4X) or work using the DOM (distal).

template-tal does neither. It is a completely self-contained library, suitable for node.js, client side applications and / or embedded apps. It is a port of the Perl Petal::Tiny package. http://search.cpan.org/~jhiver/Petal-Tiny-1.03/

This Readme hence steals a lot of its documentation and explains the differences between the two modules.

NAMESPACE

template-tal has no namespace support, you must use the tal: prefix throughout.

KICKSTART

Typically, you may have a data structure looking like this:

var data = {
    user: "Bob",
    getBasket: fetchBasketFunction,
};

Where fetchBasketFunction() would either return a list of fruits, or a Promise object which should resolve to a list of fruits, like ['apple', 'banana', 'kiwi', 'mango']

You want your end result to look like this:

<body>
  <h1>Bob</h1>
  <p>Basket List:</p>
  <ul>
    <li>apple</li>
    <li>banana</li>
    <li>kiwi</li>
    <li>mango</li>
  </ul>
</body>

So let's work this out. First let's replace the username "Bob":

<h1 tal:content="user">Bob</h1>

Now lets work out the list:

<ul>
  <li tal:repeat="item getBasket()"
      tal:content="item">some fruit goes here</li>
</ul>

Our template now looks like:

<body>
  <h1 tal:content="user">Bob</h1>
  <p>Basket List:</p>
  <ul>
    <li tal:repeat="item getBasket()"
        tal:content="item">some fruit goes here</li>
  </ul>
</body>

Ah! But what is happening if our basket is empty? Then we'd get the following output:

<body>
  <h1>Bob</h1>
  <p>Basket List:</p>
  <ul>
  </ul>
</body>

Which is not very elegant. Thus we change the template as follows:

<body tal:define="basket getBasket()">
  <h1 tal:content="user">Bob</h1>
  <div tal:condition="true:basket">
    <p>Basket List:</p>
    <ul>
      <li tal:repeat="item basket"
          tal:content="item">some fruit goes here</li>
    </ul>
  </div>
  <div tal:condition="false:basket">
    <p><span tal:replace="user">SomeUser</span>'s basket is empty :-(.</p>
  </div>
</body>

Let's explain what we did:

We used tal:define to assign the list of fruits to a variable called basket using a javascript expression, getBasket(), which can either return the desired value or a Promise to resolve to the desired value.
We used tal:content to replace the content of a tag with a javascript expression. This implementation of the TAL spec evals Javascript directly, so you can do things like <theAnswer tal:content="21*2" />

Which would output

<theAnswer>42</theAnswer>

Your expression must return something or a Promise of something.

We then used tal:condition in conjunction with the "true:" modifier to either display a list if the list is populated, or display a message describing an empty basket.
Finally, we used tal:repeat to iterate through each item of the basket.

You can find a TAL reference at http://www.owlfish.com/software/simpleTAL/tal-guide.html, and this library tried to implement most of it.

RESTRICTIONS:

SUPPORTED TAL STATEMENTS:

<p tal:on-error="string:sorry, could not fetch user.">
  <b tal:content="database.getUser().name">replace me</b>
</p>

<p tal:define="user database.getUser()">
  <span tal:replace="user.name" />
</p>

<p tal:condition="true:stuff">
  stuff is true, let's do something.
</p>
<p tal:condition="false:stuff">
  stuff is false, let's do something else.
</p>

<table>
  <th>
    <td>username</td>
    <td>email</td>
  </th>
  <tr tal:repeat="user users()">
    <td tal:content="user.login()">login</td>
    <td tal:content="user.email()">email</td>
  </tr>
</table>

Note that tal:repeat also auto creates the following variables, which you can access from within your repeat block.

<p tal:content="someStuff">I will be replaced</p>

<p tal:replace="someStuff">I will be replaced, including the p tag.</p>

<a href="#" alt="desc"
   tal:attributes="href url.href; alt url.desc"
   tal:content="url.label">SomeLabel</a>

<em tal:omit-tag="false:important">I may be important.</em>

Note that tal:omit-tag="" ALWAYS strips the tag.

EXPRESSIONS

structure keyword

Prefixing an expression with the keyword structure will make it not escape HTML when replacing the output. This is handy when you are using variables which themselves return HTML.

<!-- bad, will be double encoded -->
<span tal:content="getSomeHTML()">replace me</span>

<!-- yup, that should work -->
<span tal:content="structure getSomeHTML()">replace me</span>

template keyword

Same as structure, except the resulting expression is expected to be a template. Useful for importing template fragments and even building recursive templates such as sitemaps.

<span tal:content="template getSomeTALTemplate()">replace me</span>

true:EXPRESSION

If EXPRESSION returns an array reference
  If this array reference has at least one element
    Returns TRUE
  Else
    Returns FALSE
Else
  If EXPRESSION returns a TRUE value (according to Javascript 'trueness')
    Returns TRUE
  Else
    Returns FALSE

the true: or false: modifiers should always be used when using the tal:condition statement.

false:EXPRESSION

I'm pretty sure you can work this one out by yourself :-)

string:STRING

The string: modifier lets you interpolate tal expressions within a string and returns the value.

IMPORTANT NOTE string interpolation does not support asynchronous expressions which returns Promises. You can always get the async value in another variable using tal:define and then interpolate that.

string:Welcome ${user.realName()}, it is ${myLocalTime()}!

Writing your own modifiers is easy:

tal.MODIFIERS.uppercase = function (expr, self, callback) {
  resolve(expr, context, function(error, arg) {
    if(error) { return callback(error) }
    if (typeof arg === 'string') { string = string.toUpperCase() }
    return callback(null,string)
  })
}

Then in your template:

<p tal:content="uppercase:database.getUser().name">hello</p>

EXPORTS

tal.process(), tal.MODIFIERS

BUGS

If you find any, please drop me an email - jhiver (at) gmail (dot) com. Patches are always welcome of course.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

template-tal

SYNOPSIS

SUMMARY

NAMESPACE

KICKSTART

RESTRICTIONS:

SUPPORTED TAL STATEMENTS:

EXPRESSIONS

EXPORTS

BUGS

SEE ALSO