doc, etc
diff --git a/doc/makotemplates.txt b/doc/makotemplates.txt new file mode 100644 index 0000000..33b524d --- /dev/null +++ b/doc/makotemplates.txt
@@ -0,0 +1,648 @@ +<html> + +<head> + +<style> + body { + font-family:arial,helvetica; + } +</style> + +</head> + +<body> + +# Mako Templates for Python + +## Slogan +Hyperfast and Lightweight Templating for the Python Platform + +## Features +- Python Server Pages. Templates compile into Python modules for maximum performance. +<li> <p>Insanely Fast. An included bench suite, adapted from a suite included with Genshi, has these results for a simple three-sectioned layout:</p> +<table> +<tr><td>Mako:</td><td>0.51 ms</td></tr> +<tr><td>Cheetah:</td><td>0.80 ms</td></tr> +<tr><td>Django:</td><td>5.43 ms</td></tr> +<tr><td>Myghty:</td><td>5.25 ms</td></tr> +<tr><td>Genshi:</td><td>12.53 ms</td></tr> +<tr><td>Kid:</td><td>19.12 ms</td></tr> +</table> +</li> + +- Super-simple API. For basic usage, just one class, `Template` is needed: + + from mako.template import Template + print Template("hello ${data}!").render(data="world") + +- To manage many templates, leveraging industrial strength module generation and management code adapted from Myghty, use the `TemplateLookup` class: + + from mako.lookup import TemplateLookup + lookup = TemplateLookup(directories=['/my/htmlfiles']) + template = lookup.get_template('index.html') + print template.render(data="foo") + +- Mako's syntax borrows from the best ideas of many others, including: + + - Django Templates + - Myghty / Mason + - Cheetah + - Genshi + - Java Server Pages + - Struts Tiles + +- Standard template features: + - control structures + + % if len(v) > 5: + % for x in range(1,5): + hi ${x} + % endfor + % endif + + - straight python code: + + <% + data = handle.lookup() + view = [d.name for d in data] + %> + + - callable blocks, with or without arguments, which also pull names from the enclosing scope: + + # define: + <%component name="foo(x, y)"> + hi im foo ${x} ${y} ${z} + </%component> + + # then call: + ${foo(4,5)} + + - multi-zoned page inheritance + - "component-calls-with-content" - call any def, nesting any number locally-defined blocks of text as arguments. This is the basis for creating custom tags: + + # define: + <%component name="foo(x, y)"> + ${head()} + foo ${x} {$y} + ${body()} + </%component> + + # then call, defining two more blocks + <%call expr="foo(3, 4)"> + <%component name="head"> + the header + </%component> + main body + </%call> + + - filters, either the standard builtins or custom functions, applicable to any expression or `<%component>` definition: + + ${"some text" | h} + + <%component name="foo" filter="filter1, x"> + ... + </%component> + + - custom tags can be created as templated components, or Python modules containing callables. Whole sets of custom tags can be imported into the current template's namespace using the `<%namespace>` tag. + - caching built in from the ground up. any template or block of text within can be cached using memory, file, DBM or memcached backends. + +## Language + +### Control Structures + +Control structures use the % operator. % can start anywhere on the line, preceded by only whitespace. Blocks are terminated by name-qualified terminators. + + % for item in items: + % if foo: + ${item} + some text + % endif + % endfor + +The amount of whitespace before the % and after the % before the code starts is not significant. + +Myghty style: + + % if x: + % if y: + % endif + % endif + +"Cheetah" style: + + %if x: + %if y: + %endif + %endif + +Messy style (you probably wouldn't want to code this way for readablity): + + %if x: + %if y: + % endif + % endif + +### Comments + +Work similarly to %, using the # tag: + + <html> + # this is a comment. + </html> + +### Truncating Newlines + +End any line with a backslash (\\) to suppress the newline at the end: + + % for x in [1,2,3]:\ + ${x} \ + % endfor + +Produces the output: + + 1 2 3 + +The newline truncator is particularly important for producing plaintext documents such as emails, as well as preformatted sections of HTML (i.e. using `<pre>`). + +### Expressions + +Expressions usually use ${expr} syntax, and compile into literal Python. + + ${someexpression} + + ${"foo" + "bar"} + +### Variable Namespace + +A template executes with a single contextual dictionary. This dictionary is completely transparent in the template itself. AST parsing of all embedded Python is performed in order to locate all referenced variable names, which are pre-declared from the dictionary at runtime (or None if not present) before template-generated Python is executed. So when a variable "x" is referenced, the searched hierarchy is: + +- Variables declared within control structures or locally embedded python code +- Variables explicitly declared by the page or component +- Variables declared in the template at the module-level +- Components (callables) and namespaces (groups of callables) declared within the template +- Variables passed to component calls, undeclared by the component or page +- Variables passed to the template's context, undeclared by the component or page + +If you need to get at the context directly (such as if youve declared a module-level variable thats overriding a name), its available as `context`, and it follows dictionary conventions: + + the context: ${context['some key']} + +Other names that are sometimes used by default include `body`, within a component call, and `text`, within a filter call. + +### Embedding Python +#### Inline + +Inline Python is embedded via the <% %> tags. This is straight python so the whitespace is significant. You can emit text via the `write()` method on the context. + + <table> + <tr><td>some table</td></tr> + <tr> + <% + for x in ["one", "two", "three"]: + context.write("<td>%s</td>" % x) + %> + </tr> + </table> + +Remember that you can reference any variable name from the template's context, and it will be pulled from the context automatically. This works similarly to a global variable in Python; i.e. if you assign to the variable name first, then its a local variable. + +Context: + + {'x':'one', 'y':'two'} + +Template: + + <% + context.write("X is " + x + "\n") + y = "hi there" + context.write("Y is " + y + "\n") + %> + +Produces: + + X is one + Y is hi there + +#### Module Level + +Module level Python is declared by the <%! %> tags. Python in these blocks occurs at module import time (i.e. global scope) + + <%! + import mystuff + def writefoo(text): + return "foo is " +text + %> + + hello ${writefoo('jack')} + + +### File Includes + +Use the <%include> tag. + + <%include file="somefile.txt"/> + +This tag also can handle expressions: + + <%include file="${filename}"/> + +In fact every <%tag> can use expressions (i.e. ${}) inside of their quoted sections. + +The include tag requires that the template being called has a `TemplateLookup` available with which to locate the included template. + +Add the `import="true"` flag to the `<%include>` tag and when you include the file, all the `<%component>` and `<%namespace>` sections declared in that file (described later) are pulled into the local namespace of the template, as though they were declared locally: + + <%include file="somefile.html" import="true"/> + +### Components + +The component is the single tag used to demarcate any block of text and/or code. It exists within generated Python as a callable function. + + <%component name="hello"> + hello world + </%component> + +They are normally called as expressions. + + the component: ${hello()} + +A `<%component>` can be declared anywhere inside a template, and becomes available throughout the template, including above where it was declared. The callable generated by `<%component>` gets generated outside of the enclosing template's callable. The name of the callable is then placed in the variable namespace of the parent component. + +Components have access to the current contextual namespace in exactly the same way their parent template does. + + Hello there ${username}, how are ya. Lets see what your account says: + + ${account()} + + <%component name="account"> + Account for ${username}:<br/> + + % for row in accountdata: + Value: ${row}<br/> + % endfor + </%component> + +You can also pass arguments to a component, which show up in the component's variable namespace overriding whatever is in the enclosing namespace: + + ${account(name='john')} + + <%component name="account"> + Hi ${name} + </%component> + +If you want your component to have positional arguments, you can declare them: + + <%component name="account(accountname, type)"> + account name: ${accountname}, type ${type} + </%component> + +As well as keyword arguments explicitly declared, using normal Python conventions: + + <%component name="account(accountname, type='personal')"> + account name: ${accountname}, type ${type} + </%component> + +When you declare explicit arguments in your component signature, they are required following normal Python conventions. This is in contrast to using variable names implicitly from the template's context, which produces `None` if the name doesn't exist. Additionally, explicitly declared arguments are handy in case you have the same names declared at the module level, and you'd like to insure that you get those arguments from the component call itself. + +#### Calling Components from Other Files + +Calling a component from another file differs from a regular `<%include>`, in that you are calling a specific component declared in that template, not the template body itself. + +First, load the file you want into a "namespace": + + <%namespace name="mystuff" file="mystuff.html"/> + +The namespace tag is declared once per template, and adds a local variable "mystuff" to the current scope. + +Then, just call the components off of `mystuff`: + + ${mystuff.somecomponent(x=5,y=7)} + +#### Components within Components + +The component model is totally recursive. Declaring `<%component>` inside another `<%component>` leads it to be local to its parent: + + <%component name="mycomponent"> + <%component name="subcomponent"> + a sub component + </%component> + + im the component, and the subcomopnent is ${subcomponent()} + </%component> + +The recursive component model becomes very handy for doing layouts, including usage within inheriting templates. + +#### Calling a component with embedded content and/or other components + +A flip-side to component within component is a component call with content. This is where you call a component, and at the same time declare a block of content that can be used by the component being called. This is the basic method used to declare "custom tags". To achieve this, use the `<%call>` tag instead of the regular expression syntax. By default, the body of content is assigned to the name `body`: + + <%component name="buildtable"> + <table> + <tr><td> + ${body()} + </td></tr> + </table> + </%component> + + <%call expr="buildtable"> + I am the table body. + </%call> + +This produces the output: + + <table> + <tr><td> + I am the table body. + </td></tr> + </table> + +The `body` name is executed each time its referenced. This means you can use component-call-with-content to build iterators, conditionals, etc: + + <%component name="lister(count)"> + % for x in range(1,count): + ${body()} + % endfor + </%component> + + <%call expr="lister(3)"> + hi + </%call> + +Produces: + + hi + hi + hi + +A custom "conditional" tag: + + <%component name="conditional(expr)"> + % if expr: + ${body()} + % + </%component> + + <%call expr="conditional(4==4)"> + im the result + </%call> + +Produces: + + im the result + +Since `body` is a callable, the hosting component can pass arguments: + + <%component name="layoutdata(somedata)"> + <table> + % for item in somedata: + <tr> + % for col in item: + <td>${body(col=col)}</td>\ + % endfor + </tr> + % endfor + </table> + </%component> + + <%call expr="layoutdata([[1,2,3],[4,5,6],[7,8,9]])"> + Body data: ${col} + </%call> + +Produces: + + <table> + <tr> + <td>Body data: 1</td><td>Body data: 2</td><td>Body data: 3</td> + <td>Body data: 2</td><td>Body data: 5</td><td>Body data: 6</td> + <td>Body data: 3</td><td>Body data: 8</td><td>Body data: 9</td> + </tr> + </table> + +If you combine nested components with the component call with content, you can build whole layouts quite easily: + + <%component name="layout"> + # a layout component + <div class="mainlayout"> + <div class="header"> + ${header()} + </div> + <div class="sidebar"> + ${sidebar()} + </div> + <div class="content"> + ${body()} + </div> + </div> + </%component> + + # calls the layout component + <%call expr="layout"> + <%component name="header"> + I am the header + </%component> + <%component name="sidebar"> + <ul> + <li>sidebar 1</li> + <li>sidebar 2</li> + </ul> + </%component> + + this is the body + </%call> + +The above layout would produce: + + <div class="mainlayout"> + <div class="header"> + I am the header + </div> + <div class="sidebar"> + <ul> + <li>sidebar 1</li> + <li>sidebar 2</li> + </ul> + </div> + <div class="content"> + this is the body + </div> + </div> + +### Inheritance + +Inheritance allows you to specify another template file that should take control of execution, using the current template's namespace. This is provided via the <%inherit> tag. This works similarly to the component call with content example above, where `body` is the main body of the template and you can also define other `<%component>` sections: + + # page.html: + + <%inherit name="base.html"/> + <%component name="header"> + this is the header + </%component> + + I am the body + + <%component name="footer"> + this is the footer + </%component> + + # base.html: + + <html> + <body> + <div class="top"> + ${header()} + </div> + + ${body()} + + ${footer()} + </body> + </html> + +Which produces: + + <html> + <body> + <div class="top"> + this is the header + </div> + + I am the body + + this is the footer + </body> + </html> + +The inheritance of the parent template occurs *where you put the inherit tag.* This means whatever content is above the inherit tag gets executed normally, without any inheritance. It also means you can inherit *dynamically!* + + <% + if layout=='green': + inheritfrom = 'greentmpl.html' + else: + inheritfrom = 'normaltmpl.html' + %> + <%inherit name="${inheritfrom}"/> + +### Page-level arguments + +As components can declare optinally explicit argument signatures, so can your template, using the `<%page>` tag: + + <%page arguments="(arg1, arg2, arg3=None)"/> + +The named arguments are pulled from the incoming context dictionary, overriding any module-level declared arguments. It also serves as a way to declare certain context arguments as required. + +### Filters + +Filters are callable functions that receive a single textual argument as a string, and return a new textual string as output. They are called using the `|` operator in expressions: + + ${"this is some text" | html} + +Or using the `filter` keyword for a `<%component>` or `<%call>` directive: + + <%component name="mycomp" filter="html"> + </%component> + +Standard built-in filters are included: `html`, `xml`, `url`. + +Creating your own filters is easy. Any callable that is in the template's namespace can be used, or you can declare functions: + + <%| + def myfilter(text): + return "text" + text + "filtered" + %> + + ${"hiya" | myfilter} + +Filters can also be defined using the `<%component>` tag. The text to be filtered is placed into the name 'text': + + <%component myfilter> + text${text}filtered + </%component> + + ${"hiya" | myfilter} + +Filters can take arguments ! Using a python function: + + <%| + def pythonfilter(text, arg1, arg2='foo'): + return "text" + text + "filtered" + %> + ${"hiya" | pythonfilter('hello', 'world')} + +Or a `<%component>`: + + <%component componentfilter(arg1, arg2='foo')> + text${text}filtered + </%component> + + ${"hiya" | componentfilter('hello', 'world')} + +### Caching + +Any template or component can be cached using the `cache` argument to the `%page` or `%component` directives: + + <%page cache="true"/> + + template text + + <%component name="mycomp" cache="true" cache_timeout="30" cache_type="memory"> + other text + </%component> + +Cache arguments: +- cache="false|true" - turn caching on +- cache_timeout - number of seconds in which to invalidate the cached data +- cache_type - type of caching. `memory`, `file`, `dbm`, or `memcached`. + +### Namespaces + +Namespaces are used to organize groups of components into categories, and also to "import" components from other files so that you don't have to type the full filename of the remote component file. + +If the file `components.html` defines these two components: + + # components.html + <%component name="comp1"> + this is comp1 + </%component> + + <%component name="comp2"> + this is comp2 + </%component> + +You can make another file, for example `index.html`, that pulls those two components into a namespace called `comp`: + + # index.html + <%namespace name="comp" file="components.html"/> + + Heres comp1: ${comp.comp1()} + Heres comp2: ${comp.comp2()} + +The `<%namespace>` tag is more powerful than that. You can also declare `<%components>` within the namespace: + + # define a namespace + <%namespace name="stuff"> + <%component name="comp1"> + comp1 + </%component> + </%namespace> + + # then call it + ${stuff:comp1()} + +Namespaces can also import modules containing regular Python callables. These callables need to take at least one argument, `context`: + +A module file `some/module.py` might contain the callable: + + def my_tag(context): + context.write("hello world") + +A template can use this module via: + + <%namespace name="hw" module="some.module"/> + + ${hw.my_tag()} + +Note that the `context` argument is not needed in the call; the `namespace` tag creates a locally-scoped callable which takes care of it. + +</body> + +</html>
diff --git a/examples/bench/basic.py b/examples/bench/basic.py index 81c7c67..4072692 100644 --- a/examples/bench/basic.py +++ b/examples/bench/basic.py
@@ -4,7 +4,7 @@ import sys import timeit -__all__ = ['myghty', 'django', 'kid', 'genshi', 'cheetah', 'mako'] +__all__ = ['mako', 'cheetah', 'django', 'myghty', 'genshi', 'kid'] def genshi(dirname, verbose=False): from genshi.template import TemplateLoader
diff --git a/examples/bench/mako/template.html b/examples/bench/mako/template.html index 8717fcc..d861d54 100644 --- a/examples/bench/mako/template.html +++ b/examples/bench/mako/template.html
@@ -13,7 +13,6 @@ <%include file="header.html"/> - ${greeting(user)} ${greeting('me')} ${greeting('world')}
diff --git a/lib/mako/runtime.py b/lib/mako/runtime.py index 6a4959f..4f2347c 100644 --- a/lib/mako/runtime.py +++ b/lib/mako/runtime.py
@@ -4,6 +4,7 @@ class Context(object): """provides runtime namespace and output buffer for templates.""" def __init__(self, template, buffer, **data): + # TODO: not sure if Context should need template + buffer etc. self.buffer = buffer self.data = data # the Template instance currently rendering with this context.