Cubictemp evaluates expressions between tag delimiters as expressions in the specified namespace. The result is converted to a string, and placed in the rendered template. There are two flavours of delimiters - escaped:
@!...!@
and unescaped:
$!...!$
In Python, an expression can be thought of as anything that can be assigned to a variable. Arithmetic operators, boolean operators, parentheses for grouping, method/function calls, object instantiation and conditional expressions are all valid components of expressions. Python statements include things like while, print, variable assignment and full if blocks. Cubictemp allows only expressions in subtitution tags.
Template:
@!foo!@ times two is @!foo*2!@ @!foo!@ squared is @!foo*foo!@ @!"yes" if (1==2) else "no"!@ key is @!mydict["key"]!@
Code:
import cubictemp
print cubictemp.File(
"template",
foo=3,
mydict=dict(key="value")
)
Output:
3 times two is 6 3 squared is 9 no key is value
In an escaped substitution tag, the &, <, >, ", ’ characters are converted to their corresponding HTML escape sequences. Always use the escaped substitution syntax if you can. When you really need to place HTML in a substitution tag, make sure you carefully evaluate the application context to make sure that users cannot inject malicious data.
import cubictemp
print cubictemp.Template(
"@!x!@ $!x!$",
x = "<H1>foo</H1>"
)
... will print:
<H1>foo</H1> <H1>foo</H1>
Sometimes, it is handy to be able to construct objects that bypass Cubictemp's escaping mechanism, regardless of the type of tag in which they occur. You can signal this to cubictemp by giving the object a special attribute _cubictemp_unescaped which evaluates to true.
Template, File, and named block objects all have a _cubictemp_unescaped attribute, so none of these objects will be escaped when referenced inside an escaped tag.
Copyright Nullcube 2008
Please send any comments, suggestions and bug reports to dev@nullcube.com.
This project is distributed under the MIT license.
Copyright (c) 2007, Nullcube Pty Ltd
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright Nullcube 2008
One common use for blocks is to declare a named block, and then perform some transformation on it when it is inserted back into the document. One way to do this is to write a transformation function that takes a string and returns a string, and pass it straight in the template namespace for use:
<!--(block codesnippet)-->
for i in range(10):
print i
<!--(end)-->
@!syntaxHighlight(codesnippet)!@
Cubictemp has a special processor syntax to facilitate this use pattern.
<!--(block codesnippet|syntaxHighlight)-->
for i in range(10):
print i
<!--(end)-->
@!codesnippet!@
Using processors is similar to using pipes in Unix shells. Any callable that takes a string and returns a string can be used as a processor. Processors can be chained together:
<!--(block codesnippet|trimWhitespace|syntaxHighlight)-->
for i in range(10):
print i
<!--(end)-->
@!codesnippet!@
In this case, trimWhitespace would be run first, then syntaxHighlight. The processor declarations are just expressions evaluated in the namespace of the block declaration. Processors should be passed in to a template namespace for use.
There is one further refinement to the block syntax. In the examples above, naming the block is redundant - it is created, and then immediately substituted into the template. Anonymous blocks remove this redundancy. An anonymous block is immediately inserted into he template at its place of definition. The following template is equivalent to the last definition above:
<!--(block|trimWhitespace|syntaxHighlight)-->
for i in range(10):
print i
<!--(end)-->
Copyright Nullcube 2008
A small, elegant templating system for Python.
Simple, well-tested and well-documented.
Integrates tightly with Python - pass arbitrary Python objects into a template, walk sequences and iterators, evaluate expressions.
Default escaping helps to prevent common classes of Cross-Site Scripting vulnerabilities.
Encourages separation of interface and program logic by disallowing statements in templates.
Tiny - only ~ 170 SLOC. There are many large, over-designed Python templating systems out there. Cubictemp proves that a templating sytem can be complete, elegant, powerful, fast and remain compact.
Cubictemp requires Python 2.4 or newer.
import cubictemp
template = cubictemp.Template("Hello @!foo!@!", foo="walrus")
print template
print template(foo="world")
Output:
Hello walrus! Hello world!
Copyright Nullcube 2008
Cubictemp blocks are chunks of text that are defined in the template body, and can be referenced in various ways. The simplest block variety is the named block:
<!--(block bar)-->
The time has come the walrus said
<!--(end)-->
one
@!bar!@
two
@!bar!@
three
Output:
one
The time has come the walrus said...
two
The time has come the walrus said...
three
Like a function, named blocks only produce output when they are referenced. The block definition itself does not appear in the template output.
Named blocks are callable objects that accept an over-riding namespace argument:
<!--(block bar)-->
The time has come the @!foo!@ said...
<!--(end)-->
@!bar(foo="walrus")!@
@!bar(foo="carpenter")!@
Output:
The time has come the walrus said
The time has come the carpenter said
Blocks can be nested to arbitrary depths. Block namespaces and scopes work similarly to Python namespaces and scopes.
Named blocks have the _cubictemp_unescaped attribute defined by default,
so they will go unescaped when inserted using the standard
@!...!@
escaped substitution syntax.
Cubictemp provides a repeat construct to allow traversal of iterables:
<!--(for foo in bar)-->
@!foo!@
<!--(end)-->
Like a Python for loop, the template above loops through all elements of "bar", setting the value of "foo" to each element in turn. As in simple substitutions, any valid expression can be used as the sequence definition:
<!--(for foo in range(3))-->
Counting: @!foo!@
<!--(end)-->
Output:
Counting: 0 Counting: 1 Counting: 2
There is a minor variation on the block definition syntax to help preserve document structure during template design. Since the start and end directives of Cubictemp blocks look like HTML comments, they are not visible when the document is viewed as HTML. It is often convenient to be able to also comment everything inside the block. This is accomplished using the open tag variation:
<!--(block foo)
The time has come the walrus said...
(end)-->
There is no functional difference between the two flavours.
Copyright Nullcube 2008
def escape(s)
Replace special characters '&', '<', '>', ''', and '"' with the appropriate HTML escape sequences.
class TemplateError(Exception)
Template evaluation exception class.
pos = None | Character offset within the raw template at which the error occurred |
template = None | Template object |
lineNo = None | Line number |
contextLen = 2 | Error context length |
def __init__(self, message, pos, template)
def __str__(self)
class Template()
name = "<string>" | Name by which this template is referred to in exceptions. |
def __init__(self, txt, **nsDict)
def __str__(self)
Evaluate the template in the namespace provided at instantiation.
def __call__(self, **override)
A set of key/value pairs.
Evaluate the template, over-riding the instantiation namespace with the specified key/value pairs. Returns a string.
class File(Template)
Convenience class that extends Template to provide easy instantiation from a file.
def __init__(self, filename, **nsDict)
Copyright Nullcube 2008