Manual of Lua-SmplTmpl

Lua-SmplTmpl - Very simple Lua 5.1 templating module

Description

This module can be used for generating HTML, or any textual output, in a convenient way. It was designed to be as simple as possible while still having all the features it needs to be suitable for generating real web pages.

The template files used by this module should have the file extension .st. Everything in the template is treated as plain text, and sent straight to the output when the template is used, except the following special syntax:

Loading the module

The SmplTmpl module doesn't install itself into any global tables, so you can decide what name you want to use to access it. You will probably want to load it like this:

local Tmpl = require "smpltmpl"

You can use a variable called something other than Tmpl if you'd like, or you could assign the table returned by require to a global variable. In this documentation we'll assume you're using a variable called Tmpl.

Compiling and running templates

First create a template processor object:

local tmplproc = Tmpl.new({ dirs = { 'templates' } })

The argument provided must be a table, and must include the dirs table. That option should be an array of at least one path in which the processor will search for templates.

Each template processor object is separate from any others. They each have their own dirs setting, and their own in-memory cache of compiled templates.

The Tmpl processor object has another function called escape_html, which is used by the compiled template code to do HTML escaping. It can be called directly as well by any Lua code. The template processor object is made available in the template's environment as well, so it can be called inside a template explicitly. For example, these two lines of template code will generate the same output:

{textvar}
{!Tmpl.escape_html(textvar)}

Templates can be compiled as follows:

local tmpl = tmplproc:compile_template('foo')

This will search for a file called foo.st in each directory in the dirs option, using the first one it finds. The value returned is an object which can be used to produce the templates output.

The compile_template method actually returns two values, but the second one can usually be ignored. The second value is a string containing the Lua code which the template was compiled into. It might sometimes be helpful to write this code into a file to debug it. The template object itself only contains the compiled Lua bytecode which will be run when the template is used.

To generate output from a template object, call it's generate method:

tmpl:generate(out, vars)

The vars argument should be a table of values that will be accessible in the template code's environment. You can access these like normal global variables in any Lua code in the template.

The first argument can be any object representing some kind of output stream. It must possible to call a method called write on the output object. The write function will always be passed the output object and a single string as its arguments. Any results returned from the write function will be ignored.

Ordinary Lua file handles fulfil the requirements of the output stream objects the templates need, so you can easily write template output to a file. For example, this will write to the standard output:

tmpl:generate(io.output(), { var1 = "hello" })

Copyright

This software and documentation is Copyright © 2012 Geoff Richards <geoff at this domain dot co dot uk>. It is free software; you can redistribute it and/or modify it under the terms of the Lua 5.0 license. The full terms are given in the file COPYRIGHT supplied with the source code package, and are also available here: http://www.lua.org/license.html