Dark Mode

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

jhiver/template-tal

Folders and files

NameName
Last commit message
Last commit date

Latest commit

History

42 Commits

Repository files navigation

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:

Dummy Content

Dummy Content

Dummy Content

` 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) })">let tal = require ('./lib/template-tal')
let xml = `


Dummy Content


Dummy Content


Dummy Content




`

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:



FOO


BAR


BAZ




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:


Bob


Basket List:



  • apple

  • banana

  • kiwi

  • mango



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

Bob


Now lets work out the list:


  • tal:content="item">some fruit goes here


Our template now looks like:


Bob


Basket List:



  • tal:content="item">some fruit goes here



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


Bob


Basket List:





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

">

Bob



Basket List:



  • tal:content="item">some fruit goes here




SomeUser's basket is empty :-(.




Let's explain what we did:

  1. 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.

  2. 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

Which would output

42

Your expression must return something or a Promise of something.

  1. 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.

  2. 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:

  • No namespace support, just use 'tal:' everywhere.
  • Doesn't implement TALES to evaluate expressions Instead, the Javascript which you supply is evaled directly, which should allow some cool stuff if you use this library in conjunction with jquery for instance.
  • Doesn't implement METAL spec (Macros).

SUPPORTED TAL STATEMENTS:

  • tal:on-error - to deal with errors


replace me


  • tal:define - to avoid typing too much




  • tal:condition - for conditional branching

stuff is false, let's do something else.

">


stuff is true, let's do something.



stuff is false, let's do something else.


  • tal:repeat - to iterate over arrays









username email
login email

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

  • repeat.index - 1, 2, 3, etc.
  • repeat.number - same as 'index'
  • repeat.even - true if index is even
  • repeat.odd - true is index is odd
  • repeat.start - true if index == 1
  • repeat.end - true if index is pointing to last item of your list
  • repeat.inner - true if niether start nor end are true
  • tal:content - replaces inner tag content with something else.

I will be replaced


  • tal:replace - replaces the whole tag and all its contents with something else.

I will be replaced, including the p tag.


  • tal:attributes - to set tag attributes
  • tal:omit-tag - omits a tag (but not its contents) if the expression which is evaled is true.
I may be important.

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

EXPRESSIONS

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:

hello


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.

SEE ALSO

This library is a port of the Perl package Petal::Tiny, which I also wrote.

Jean-Michel Hiver - jhiver (at) gmail (dot) com

This module free software and is distributed under the same license as node.jis itself (MIT license)

Copyright (C) 2018 - Jean-Michel Hiver

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About

TAL Implementation for nodejs

Resources

Readme

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 4

Languages