sgte overview

hankwang edited this page Dec 26, 2011 · 4 revisions
Clone this wiki locally

sgte is a library implementing a Template Engine. The template system is inspired on StringTemplate

The template source can be a string or binary or a filename. The use of the engine is as simple as (from the command line):

> {ok, Compiled} = sgte:compile(TmplStr),
> sgte:render(Compiled, Data).

or:

> {ok, Compiled} = sgte:compile_file(FileName),
> sgte:render(Compiled, Data).

When compile/1 or compile_file/1 are called, the template is "compiled" to an internal representation made of mixed binaries and erlang terms. Then one of the render functions (render, render_str, or render_bin) can be called passing the Data to be rendered in the template.

  • render/2 and render/3 returns a deep iolist() suitable e.g. to use in yaws
  • render_str/2 and render_str/3 returns a string()
  • render_bin/2 and render_bin/3 returns a list of binaries()

In the rest of the overview the template features will be described using render_str since the produced is easier to read.

Data can be a Dict or a proplist (e.g. [{attr1, Val1}, {attr2, Val2}]) Values can be a simple value or a function/1. In this case the function is called with Data as an argument.

Template Features

Attribute reference

Attribute reference is written as:

$name$

Here is an example:

> {ok, C} = sgte:compile("Hello $name$!").
> sgte:render_str(C, [{name, "Filippo"}]).
"Hello Filippo!"

You can also use attribute references to access nested structures. Eg.:

> {ok, C} = sgte:compile("$foo.bar.baz$").
> sgte:render_str(C, [{foo, [{bar, [{baz, "a string"}]}]}]).
"a string"

Template reference

$include tmpl$

Includes an external compiled template. Eg.:

> {ok, C1} = sgte:compile("foo").
> {ok, C2} = sgte:compile("$include t1$ bar").
> sgte:render_str(C2, [{t1, C1}]).
"foo bar"

Application of an attribute to another

$apply myFun aVar$

When the first attribute is callable you get the result of myFun(aVar). Otherwhise the result is the value of myFun.

You can also get the same result using the more compact form:

$aVar:myFun$

Conditional evaluation

$if title$
    <h1>$title$</h1>
$else$
    <h1>default title</h1>
$end if$

Template application to a list of elements

if names is a list [{username, "foo"}, {username, "bar"}]

$map li names$

map li template to names. Each element in names is passed to the template with name attr. If li is the template:

<li><b>$username$</b></li>

We get the result:

<li><b>foo</b></li><li><b>bar</b></li>

In the shell we write something like:

> {ok, LI} = sgte:compile("<li><b>$username$</b></li>").
> {ok, NamesC} = sgte:compile("$map li names$").
> sgte:render_str(NamesC, [{li, LI}, {names, [{username, "foo"}, {username, "bar"}]}]).
<li><b>foo</b></li><li><b>bar</b></li>

Another way to express the same template inline all in one step is:

$map:{<li><b>$username$</b></li>} names$

Join of items using a separator

> {ok, SEL} = sgte:compile("SELECT $join:{,} columns$ FROM $table$;").
> sgte:render_str(SEL, [{table, "myTable"}, {columns, ["col1", "col2", "col3"]}]).
"SELECT col1,col2,col3 FROM myTable;"

Internationalization support using gettext

Gettext is a package that can be found in jungerl. It supports internationalization using the GNU Gettext format.

$txt:{Hello World}$

Here's an example supposing you already have started gettext and you have the .po files containing translated strings:

> {ok, C} = sgte:compile("$txt:{Hello World}$"),
> sgte:render(C, [{options, [{gettext_lc, "en"}]}]).
"Hello World"
> sgte:render(C, [{options, [{gettext_lc, "it"}]}]).
"Ciao Mondo"