Skip to content
This repository
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 136 lines (120 sloc) 4.273 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
@title sgte - A simple Erlang Template Engine

@doc
<p><em>sgte</em> is a library implementing a Template Engine.
The template system is inspired on <a href="http://www.stringtemplate.org">String Template</a>
</p><p>
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):
<pre>
> {ok, Compiled} = sgte:compile(TmplStr),
> sgte:render(Compiled, Data).

or:

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

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.
<ul>
    <li>render/2 and render/3 returns a deep iolist() suitable e.g. to use in yaws</li>
    <li>render_str/2 and render_str/3 returns a string()</li>
    <li>render_bin/2 and render_bin/3 returns a list of binaries()</li>
</ul>

In the rest of the overview the template features will be described using render_str since
the produced is easier to read.
</p>
<p>
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.
</p>

<h3>Template Features</h3>
<h4>Attribute reference</h4>
Attribute reference is written as:
<pre>
$name$
</pre> Here is an example:
<pre>
> {ok, C} = sgte:compile("Hello $name$!").
> sgte:render_str(C, [{name, "Filippo").
"Hello Filippo!"
</pre>
You can also use attribute references to access nested structures. Eg.:
<pre>
> {ok, C} = sgte:compile("$foo.bar.baz$").
> sgte:render_str(C, [{foo, [{bar, [{baz, "a string"}]}]}]).
"a string"
</pre>

<h4>Template reference</h4>
<pre>
$include tmpl$
</pre> Includes an external compiled template. Eg.:
<pre>
> {ok, C1} = sgte:compile("foo").
> {ok, C2} = sgte:compile("$include t1$ bar").
> sgte:render_str(C2, [{t1, C1}]).
"foo bar"
</pre>

<h4>Application of an attribute to another</h4>
<pre>
$apply myFun aVar$
</pre> When the first attribute is callable you get the
result of myFun(aVar). Otherwhise the result is the value of
myFun.

<h4>Conditional evaluation</h4>
  <pre>
  $if title$
      &lt;h1&gt;$title$&lt;/h1&gt;
  $else$
      &lt;h1&gt;default title&lt;/h1&gt;
  $end if$
  </pre>

<h4>Template application to a list of elements</h4>
if names is a list [{username, "foo"}, {username, "bar"}]
<pre>
$map li names$
</pre>
map li template to names. Each element in names is passed to the template with name attr.
If li is the template:
<pre>
&lt;li&gt;&lt;b&gt;$username$&lt;/b&gt;&lt;/li&gt;</pre>
We get the result:
<pre>
&lt;li&gt;&lt;b&gt;foo&lt;/b&gt;&lt;/li&gt;&lt;li&gt;&lt;b&gt;bar&lt;/b&gt;&lt;/li&gt;
</pre>

In the shell we write something like:
<pre>
> {ok, LI} = sgte:compile("&lt;li&gt;&lt;b&gt;$username$&lt;/b&gt;&lt;/li&gt;").
> {ok, NamesC} = sgte:compile("$map li names$").
> sgte:render_str(NamesC, [{li, LI}, {names, [{username, "foo"}, {username, "bar"}]}]).
&lt;li&gt;&lt;b&gt;foo&lt;/b&gt;&lt;/li&gt;&lt;li&gt;&lt;b&gt;bar&lt;/b&gt;&lt;/li&gt;
</pre>

Another way to express the same template inline all in one step is:
<pre>
$map:{&lt;li&gt;&lt;b&gt;$username$&lt;/b&gt;&lt;/li&gt;} names$
</pre>
<h4>Join of items using a separator</h4>
<pre>
> {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;"
</pre>

<h4>Internationalization support using gettext</h4>
Gettext is a package that can be found in <a href="http://jungerl.sourceforge.net/">jungerl</a>. It
supports internationalization using the <a href="http://www.gnu.org/software/gettext/">GNU Gettext format</a>.
<pre>
$txt:{Hello World}$
</pre>
Here's an example supposing you already have started gettext and you have the .po files containing
translated strings:
<pre>
> {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"
</pre>

@end
@author Filippo Pacini <filippo.pacini@gmail.com>
@copyright 2006 - 2008 S.G. Consulting
Something went wrong with that request. Please try again.