Render template strings

(templatel-render-file (path variables &rest opt))

Render template file at PATH with VARIABLES.

Just like with templatel-render-string, templates rendered with this function also can’t use {% extends %} statements. Please refer to the section Template Environments to learn how to use the API that enables template inheritance.

Given the HTML template file.html:

Hi, {{ name }}!

And the following Lisp code:

(templatel-render-file "out.html" ’(("name" . "test")))

When, executed the above code would generate the file ‘out.html‘ with the variable interpolated into the content. e.g.:

Hi, test!

The argument OPT can have the following entries:

AUTOESCAPE-EXT: list contains which file extensions enable

automatic enabled HTML escaping. In the example above, HTML entities present in ‘name‘ will be escaped. Notice that the comparison is case sensitive. Defaults to ’("html" "xml").

(templatel-render-string (template variables &rest options))

Render TEMPLATE string with VARIABLES.

This is the simplest way to use templatel, since it only takes a function call. However, notice that it won’t allow you to extend other templates because no :importfn can be passed to the implicit envoronment created within this function. Please refer to the next section Template Environments to learn how to use the API that enables template inheritance.

The argument OPTIONS can have the following entries:

AUTOESCAPE: enables automatic HTML entity escaping. Defaults to nil.

(templatel-render-string "Hello, {{ name }}!" ’(("name" . "GNU!")))

Template environments

(templatel-env-add-filter (env name filter))

Add FILTER to ENV under key NAME.

This is how templatel supports user-defined filters. Let’s say there’s a template environment that needs to provide a new filter called addspam that adds the word "spam" right after text.:

(let ((env (templatel-env-new)))
  (templatel-env-add-filter env "spam" (lambda(stuff) (format "%s spam" stuff)))
  (templatel-env-add-template env "page.html" (templatel-new "{{ spam(\"hi\") }}"))
  (templatel-env-render env "page.html" ’()))

The above code would render something like hi spam.

Use templatel-env-remove-filter to remove filters added with this function.

(templatel-env-add-template (env name template))

Add TEMPLATE to ENV under key NAME.

(templatel-env-add-test (env name test))

Add TEST to ENV under key NAME.

(templatel-env-get-autoescape (env))

Get autoescape flag of ENV.

(templatel-env-new (&rest options))

Create new template environment configured via OPTIONS.

Both templatel-render-string and templatel-render-file provide a one-call interface to render a template from a string or from a file respectively. Although convenient, neither or these two functions can be used to render templates that use {% extends %}.

This decision was made to keep templatel extensible allowing users to define how new templates should be found. It also keeps the library simpler as a good side-effect.

To get template inheritance to work, a user defined import function must be attached to a template environment. The user defined function is responsible for finding and adding templates to the environment. The following snippet demonstrates how to create the simplest import function and provide it to an environment via :importfn parameter.

(templatel-env-new
 :importfn (lambda(environment name)
             (templatel-env-add-template
              environment name
              (templatel-new-from-file
               (expand-file-name name "/home/user/templates")))))

(templatel-env-remove-filter (env name))

Remove filter from ENV under key NAME.

This function reverts the effect of a previous call to templatel-env-add-filter.

(templatel-env-remove-template (env name))

Remove template NAME from ENV.

This function reverts the effect of a previous call to templatel-env-add-template.

(templatel-env-remove-test (env name))

Remove test from ENV under key NAME.

This function reverts the effect of a previous call to templatel-env-add-test.

(templatel-env-render (env name vars))

Render template NAME within ENV with VARS as parameters.

(templatel-env-set-autoescape (env autoescape))

Set AUTOESCAPE flag of ENV to either true or false.

Filters

(templatel-filters-abs (n))

Absolute value of number N.

(templatel-filters-attr (s n))

Get element N of assoc S.

(templatel-filters-capitalize (s))

Upper-case the first character of S.

(templatel-filters-default (value default))

Return DEFAULT if VALUE is nil or return VALUE.

(templatel-filters-escape (s))

Convert special chars in S to their respective HTML entities.

(templatel-filters-first (s))

First element of sequence S.

(templatel-filters-float (s))

Parse S as float.

(templatel-filters-int (s &optional base))

Convert S into integer of base BASE.

(templatel-filters-join (seq &optional sep))

Join al elements of SEQ with SEP.

(templatel-filters-last (s))

Last element of sequence S.

(templatel-filters-length (seq))

Return how many elements in a SEQ.

(templatel-filters-lower (s))

Lower case all chars of S.

(templatel-filters-max (seq))

Find maximum value within SEQ.

(templatel-filters-min (seq))

Find minimum value within SEQ.

(templatel-filters-plus1 (s))

Add one to S.

(templatel-filters-round (n))

Round N.

(templatel-filters-safe (s))

Mark string S as safe.

That is useful if one wants to allow variables to contain HTML code. e.g.:

(templatel-render-string
 "Hi {{ name|safe }}!" ’(("name" . "<b>you</b>"))
 :autoescape t)

The above snippet would output the HTML entities untouched even though the flag for auto escaping is true:

Hi <b>you</b>!

'templatel api reference