| .. _syntax_toplevel: |
| |
| ====== |
| Syntax |
| ====== |
| |
| A Mako template is parsed from a text stream containing any kind |
| of content, XML, HTML, email text, etc. The template can further |
| contain Mako-specific directives which represent variable and/or |
| expression substitutions, control structures (i.e. conditionals |
| and loops), server-side comments, full blocks of Python code, as |
| well as various tags that offer additional functionality. All of |
| these constructs compile into real Python code. This means that |
| you can leverage the full power of Python in almost every aspect |
| of a Mako template. |
| |
| Expression Substitution |
| ======================== |
| |
| The simplest expression is just a variable substitution. The |
| syntax for this is the ``${}`` construct, which is inspired by |
| Perl, Genshi, JSP EL, and others: |
| |
| .. sourcecode:: mako |
| |
| this is x: ${x} |
| |
| Above, the string representation of ``x`` is applied to the |
| template's output stream. If you're wondering where ``x`` comes |
| from, its usually from the ``Context`` supplied to the |
| template's rendering function. If ``x`` was not supplied to the |
| template and was not otherwise assigned locally, it evaluates to |
| a special value ``UNDEFINED``. More on that later. |
| |
| The contents within the ``${}`` tag are evaluated by Python |
| directly, so full expressions are OK: |
| |
| .. sourcecode:: mako |
| |
| pythagorean theorem: ${pow(x,2) + pow(y,2)} |
| |
| The results of the expression are evaluated into a string result |
| in all cases before being rendered to the output stream, such as |
| the above example where the expression produces a numeric |
| result. |
| |
| Expression Escaping |
| =================== |
| |
| Mako includes a number of built-in escaping mechanisms, |
| including HTML, URI and XML escaping, as well as a "trim" |
| function. These escapes can be added to an expression |
| substituion using the ``|`` operator: |
| |
| .. sourcecode:: mako |
| |
| ${"this is some text" | u} |
| |
| The above expression applies URL escaping to the expression, and |
| produces ``this+is+some+text``. The ``u`` name indicates URL |
| escaping, whereas ``h`` represents HTML escaping, ``x`` |
| represents XML escaping, and ``trim`` applies a trim function. |
| |
| Read more about built in filtering functions, including how to |
| make your own filter functions, in :ref:`filtering_toplevel`. |
| |
| Control Structures |
| ================== |
| |
| A control structure refers to all those things that control the |
| flow of a program - conditionals (i.e. if/else), loops (like |
| while and for), as well as things like ``try/except``. In Mako, |
| control structures are written using the ``%`` marker followed |
| by a regular Python control expression, and are "closed" by |
| using another ``%`` marker with the tag "``end<name>``", where |
| "``<name>``" is the keyword of the expression: |
| |
| .. sourcecode:: mako |
| |
| % if x==5: |
| this is some output |
| % endif |
| |
| The ``%`` can appear anywhere on the line as long as no text |
| precedes it; indentation is not signficant. The full range of |
| Python "colon" expressions are allowed here, including |
| ``if/elif/else``, ``while``, ``for``, and even ``def``, although |
| Mako has a built-in tag for defs which is more full-featured. |
| |
| .. sourcecode:: mako |
| |
| % for a in ['one', 'two', 'three', 'four', 'five']: |
| % if a[0] == 't': |
| its two or three |
| % elif a[0] == 'f': |
| four/five |
| % else: |
| one |
| %endif |
| % endfor |
| |
| The ``%`` sign can also be "escaped", if you actually want to |
| emit a percent sign as the first non whitespace character on a |
| line, by escaping it as in ``%%``: |
| |
| .. sourcecode:: mako |
| |
| %% some text |
| |
| %% some more text |
| |
| Comments |
| ======== |
| |
| Comments come in two varieties. The single line comment uses |
| ``##`` as the first non-space characters on a line: |
| |
| .. sourcecode:: mako |
| |
| ## this is a comment. |
| ...text ... |
| |
| A multiline version exists using ``<%doc> ...text... </%doc>``: |
| |
| .. sourcecode:: mako |
| |
| <%doc> |
| these are comments |
| more comments |
| </%doc> |
| |
| Newline Filters |
| ================ |
| |
| The backslash ("``\``") character, placed at the end of any |
| line, will consume the newline character before continuing to |
| the next line: |
| |
| .. sourcecode:: mako |
| |
| here is a line that goes onto \ |
| another line. |
| |
| The above text evaluates to:: |
| |
| here is a line that goes onto another line. |
| |
| Python Blocks |
| ============= |
| |
| Any arbitrary block of python can be dropped in using the ``<% |
| %>`` tags: |
| |
| .. sourcecode:: mako |
| |
| this is a template |
| <% |
| x = db.get_resource('foo') |
| y = [z.element for z in x if x.frobnizzle==5] |
| %> |
| % for elem in y: |
| element: ${elem} |
| % endfor |
| |
| Within ``<% %>``, you're writing a regular block of Python code. |
| While the code can appear with an arbitrary level of preceding |
| whitespace, it has to be consistently formatted with itself. |
| Mako's compiler will adjust the block of Python to be consistent |
| with the surrounding generated Python code. |
| |
| Module-level Blocks |
| ==================== |
| |
| A variant on ``<% %>`` is the module-level code block, denoted |
| by ``<%! %>``. Code within these tags is executed at the module |
| level of the template, and not within the rendering function of |
| the template. Therefore, this code does not have access to the |
| template's context and is only executed when the template is |
| loaded into memory (which can be only once per application, or |
| more, depending on the runtime environment). Use the ``<%! %>`` |
| tags to declare your template's imports, as well as any |
| pure-Python functions you might want to declare: |
| |
| .. sourcecode:: mako |
| |
| <%! |
| import mylib |
| import re |
| |
| def filter(text): |
| return re.sub(r'^@', '', text) |
| %> |
| |
| Any number of ``<%! %>`` blocks can be declared anywhere in a |
| template; they will be rendered in the resulting module |
| in a single contiguous block above all render callables, |
| in the order in which they appear in the source template. |
| |
| Tags |
| ==== |
| |
| The rest of what Mako offers takes place in the form of tags. |
| All tags use the same syntax, which is similar to an XML tag |
| except that the first character of the tag name is a ``%`` |
| character. The tag is closed either by a contained slash |
| character, or an explicit closing tag: |
| |
| .. sourcecode:: mako |
| |
| <%include file="foo.txt"/> |
| |
| <%def name="foo" buffered="True"> |
| this is a def |
| </%def> |
| |
| All tags have a set of attributes which are defined for each |
| tag. Some of these attributes are required. Also, many |
| attributes support **evaluation**, meaning you can embed an |
| expression (using ``${}``) inside the attribute text: |
| |
| .. sourcecode:: mako |
| |
| <%include file="/foo/bar/${myfile}.txt"/> |
| |
| Whether or not an attribute accepts runtime evaluation depends |
| on the type of tag and how that tag is compiled into the |
| template. The best way to find out if you can stick an |
| expression in is to try it ! The lexer will tell you if its not |
| valid. |
| |
| Heres a quick summary of all the tags: |
| |
| <%page> |
| ------- |
| |
| This tag defines general characteristics of the template, |
| including caching arguments, and optional lists of arguments |
| which the template expects when invoked. |
| |
| .. sourcecode:: mako |
| |
| <%page args="x, y, z='default'"/> |
| |
| Or a page tag that defines caching characteristics: |
| |
| .. sourcecode:: mako |
| |
| <%page cached="True" cache_type="memory"/> |
| |
| Currently, only one ``<%page>`` tag gets used per template, the |
| rest get ignored. While this will be improved in a future |
| release, for now make sure you have only one ``<%page>`` tag |
| defined in your template, else you may not get the results you |
| want. The details of what ``<%page>`` is used for are described |
| further in :ref:`namespaces_body` as well as :ref:`caching_toplevel`. |
| |
| <%include> |
| ----------- |
| |
| A tag that is familiar from other template languages, %include |
| is a regular joe that just accepts a file argument and calls in |
| the rendered result of that file: |
| |
| .. sourcecode:: mako |
| |
| <%include file="header.html"/> |
| |
| hello world |
| |
| <%include file="footer.html"/> |
| |
| Include also accepts arguments which are available as ``<%page>`` arguments in the receiving template: |
| |
| .. sourcecode:: mako |
| |
| <%include file="toolbar.html" args="current_section='members', username='ed'"/> |
| |
| <%def> |
| ------ |
| |
| The ``%def`` tag defines a Python function which contains a set |
| of content, that can be called at some other point in the |
| template. The basic idea is simple: |
| |
| .. sourcecode:: mako |
| |
| <%def name="myfunc(x)"> |
| this is myfunc, x is ${x} |
| </%def> |
| |
| ${myfunc(7)} |
| |
| The %def tag is a lot more powerful than a plain Python def, as |
| the Mako compiler provides many extra services with %def that |
| you wouldn't normally have, such as the ability to export defs |
| as template "methods", automatic propagation of the current |
| ``Context``, buffering/filtering/caching flags, and def calls |
| with content, which enable packages of defs to be sent as |
| arguments to other def calls (not as hard as it sounds). Get the |
| full deal on what %def can do in :ref:`defs_toplevel`. |
| |
| <%block> |
| --------- |
| |
| ``%block`` is a tag that's new as of Mako 0.4.1. It's close to |
| a ``%def``, except executes itself immediately in its base-most scope, |
| and can also be anonymous (i.e. with no name): |
| |
| .. sourcecode:: mako |
| |
| <%block filter="h"> |
| some <html> stuff. |
| </%block> |
| |
| Inspired by Jinja2 blocks, named blocks offer a syntactically pleasing way |
| to do inheritance: |
| |
| .. sourcecode:: mako |
| |
| <html> |
| <body> |
| <%block name="header"> |
| <h2><%block name="title"/></h2> |
| </%block> |
| ${self.body()} |
| </body> |
| </html> |
| |
| Blocks are introduced in :ref:`blocks` and further described in :ref:`inheritance_toplevel`. |
| |
| <%namespace> |
| ------------- |
| |
| %namespace is Mako's equivalent of Python's ``import`` |
| statement. It allows access to all the rendering functions and |
| metadata of other template files, plain Python modules, as well |
| as locally defined "packages" of functions. |
| |
| .. sourcecode:: mako |
| |
| <%namespace file="functions.html" import="*"/> |
| |
| The underlying object generated by %namespace, an instance of |
| :class:`.mako.runtime.Namespace`, is a central construct used in |
| templates to reference template-specific information such as the |
| current URI, inheritance structures, and other things that are |
| not as hard as they sound right here. Namespaces are described |
| in :ref:`namespaces_toplevel`. |
| |
| <%inherit> |
| ---------- |
| |
| Inherit allows templates to arrange themselves in **inheritance |
| chains**. This is a concept familiar in many other template |
| languages. |
| |
| .. sourcecode:: mako |
| |
| <%inherit file="base.html"/> |
| |
| When using the %inherit tag, control is passed to the topmost |
| inherited template first, which then decides how to handle |
| calling areas of content from its inheriting templates. Mako |
| offers a lot of flexbility in this area, including dynamic |
| inheritance, content wrapping, and polymorphic method calls. |
| Check it out in :ref:`inheritance_toplevel`. |
| |
| <%nsname:defname> |
| ------------------------- |
| |
| As of Mako 0.2.3, any user-defined "tag" can be created against |
| a namespace by using a tag with a name of the form |
| ``<%<namespacename>:<defname>>``. The closed and open formats of such a |
| tag are equivalent to an inline expression and the ``<%call>`` |
| tag, respectively. |
| |
| .. sourcecode:: mako |
| |
| <%mynamespace:somedef param="some value"> |
| this is the body |
| </%mynamespace:somedef> |
| |
| To create custom tags which accept a body, see |
| :ref:`defs_with_content`. |
| |
| <%call> |
| ------- |
| |
| The call tag is the "classic" form of a user-defined tag, and is |
| roughly equiavlent to the ``<%namespacename:defname>`` syntax |
| described above. This tag is also described in :ref:`defs_with_content`. |
| |
| <%doc> |
| ------ |
| |
| The doc tag handles multiline comments: |
| |
| .. sourcecode:: mako |
| |
| <%doc> |
| these are comments |
| more comments |
| </%doc> |
| |
| Also the ``##`` symbol as the first non-space characters on a line can be used for single line comments. |
| |
| <%text> |
| ------- |
| |
| This tag suspends the Mako lexer's normal parsing of Mako |
| template directives, and returns its entire body contents as |
| plain text. It is used pretty much to write documentation about |
| Mako: |
| |
| .. sourcecode:: mako |
| |
| <%text filter="h"> |
| heres some fake mako ${syntax} |
| <%def name="x()">${x}</%def> |
| %CLOSETEXT |
| |
| Returning early from a template |
| =============================== |
| |
| Sometimes you want to stop processing a template or ``<%def>`` |
| method in the middle and just use the text you've accumulated so |
| far. You can use a ````return```` statement inside a Python |
| block to do that. |
| |
| .. sourcecode:: mako |
| |
| % if not len(records): |
| No records found. |
| <% return %> |
| % endif |
| |
| Or perhaps: |
| |
| .. sourcecode:: mako |
| |
| <% |
| if not len(records): |
| return |
| %> |
| |