libtemplate

Top-level Files of trunk
Login

Files in the top-level directory from the latest check-in of branch trunk


libtemplate

libtemplate is a mustache like templating system for C.

Installation

To use libtemplate, copy the template.h and template.c files in your project.

You can also clone this repository using fossil to compile the library and play with the examples provided:

$ fossil clone https://foutaise.org/fossil/libtemplate

Compile libtemplate:

$ cd libtemplate
$ make

Dependencies

libtemplate depends on libjson. JSON structures are used as input to render the templates.

API

The template.h file provide details on libtemplate API.

Examples

See the examples directory for several examples of libtemplate usage.

Documentation

libtemplate works by expanding tags in a template using values from a JSON structure. Different type of tags are supported.

Variable

The base tag is a variable. A {{name}} tag will be replaced by the 'name' key value from the JSON input. If no value is found, an empty string is generated.

Template:

a variable: {{name}}

JSON:

{
  "name": "Bob"
}

Output:

a variable: Bob

Sections

Sections are block of text that can be rendered multiple times, depending of the value of the key associated to the section. A start tag {{#riders}} begins a 'riders' section, while a end tag {{/riders}} ends the 'riders' section.

Template:

A list of riders:
{{#riders}}
- Hi {{name}}!
{{/riders}}

JSON:

{
  "riders": [
    { "name": "Merckx" },
    { "name": "Poulidor" },
    { "name": "Hinault" }
  ]
}

Output:

A list of riders:
- Hi Merckx!
- Hi Poulidor!
- Hi Hinault!

If the section key exists but is false, null or an empty array, the section won't be rendered.

Inverted sections

Inverted sections are sections that are rendered when the associated key is false, null, or linked to an empty array. An start tag {{^riders}} begins a 'riders' inverted sections, while a end tag {{/riders}} end the 'riders' inverted section.

Template:

A list of riders:
{{#riders}}
- Hi {{name}}!
{{/riders}}
{{^riders}}
- No riders available.
{{/riders}}

JSON:

{
  "riders": []
}

Output:

A list of riders:
- No riders available.

Comments

Comments are ignored and not rendered. They begin with a {{! prefix and a }} suffix. Everything in between is ignored.

Template:

The quick {{! brown}} fox.

Output:

The quick fox.

Partials (includes)

Partials are used to include another template, using the following syntax: {{> template-filename}}.

Templates:

main.tpl:
<h1>The main template</h1>
<p>Bla bla...</p>
{{> footer.tpl}}

footer.tpl:
<footer>Author: {{author}}</footer>

JSON:

{
  "author": "Jef"
}

Output:

<h1>The main template</h1>
<p>Bla bla...</p>
<footer>Author: Jef</footer>

Formatters

Custom formatters can be used to alter variable rendering. Formatters are called using the following syntax: {{f:formatter-name variable}}

Two custom formatters are provided by defaut: an html escape formatter ({{f:html variable}}), and a url escape formatter ({{f:url variable}}).

Template:

<p>escaped html: {{f:html html-var}}</p>
<p>escaped url: <a href="{{f:url url-var}}">link</a></p>

JSON:

{
  "html-var": "<tag>"
  "url-var": "https://foutaise.org"
}

Output:

<p>escaped html: &lt;tag&gt;</p>
<p>escaped url: <a href="http%3A%2F%2Ffoutaise.org">link</a></p>

These two html and url escape formatters can be invoked using a shorter syntax:

The API allows you to define your own formatters. See tpl-formatter.c as an example.