mako模板语言

原文链接：https://blog.csdn.net/iweaming/article/details/49816165

原文链接：https://www.cnblogs.com/ubunoon/archive/2012/07/27/2611524.html

入门

Template类是创建模板和渲染模板的核心类

from mako.template import Template
mytemplate = Template("hello world")
print mytemplate.render()

Template方法的参数会编译成一个Python模块来处理.这个模块包含一个函数render_body(),模块的输出结果就是这个方法返回的.下面就是"hello ${name}"编译后的module.

# -*- encoding:ascii -*-
from mako import runtime, filters, cache
UNDEFINED = runtime.UNDEFINED
__M_dict_builtin = dict
__M_locals_builtin = locals
_magic_number = 8
_modified_time = 1385541516.897274
_enable_loop = True
_template_filename = 'hello.txt'
_template_uri = 'hello.txt'
_source_encoding = 'ascii'
_exports = []
 
 
def render_body(context,**pageargs):
    __M_caller = context.caller_stack._push_frame()
    try:
        __M_locals = __M_dict_builtin(pageargs=pageargs)
        name = context.get('name', UNDEFINED)
        __M_writer = context.writer()
        # SOURCE LINE 1
        __M_writer(u'hello ')
        __M_writer(unicode(name))
        __M_writer(u'
')
        return ''
    finally:
        context.caller_stack._pop_frame()

调用render()方法时,mako会创建一个Context对象,context对象存储了模板中的变量名.此外还存储了一个缓冲buffer,用于捕获输出结果.如果你要自定义一个Context,那么就要调用render_context()方法渲染模板.

from mako.template import Template
from mako.runtime import Context
from StringIO import StringIO
 
mytemplate = Template("hello, ${name}")
buf = StringIO()
ctx = Context(buf, name='jack')
mytemplate.render_context(ctx)
print buf.getvalue()

Template也可以加载文件模板,使用关键字参数filename

from mako.template import Template
mytemplate = Template(filename='/docs/mytmpel.mako')
print mytemplate.render()

为了提高性能,你还以添加参数module_directory='/tmp/moudle',指定生成的模块持久存储在文件系统中.

from mako.template import Template
 
mytemplate = Template(filename='/docs/mytmpl.txt', module_directory='/tmp/mako_modules')
print mytemplate.render()

语法

mako模板可以从xml,html,email等任何类型的字符流文件.模板文件可以包含mako指定的指令,如:变量,表达式,控制结构体(条件控制/循环控制),服务端注释,python代码,还有各种标签.所有这些最终都会编译成python代码,

表达式替换

最简单的表达式就是变量替换,语法是${}

this is x:${x}

导入静态资源

${request.static_path('项目名称：静态资源路径'}

<script type="text/javascript" src="${request.static_path('myshop:static/js/jquery-1.11.1.min_044d0927.js')}"></script>

mako表达式过滤器

默认支持的有

u - URL

h - HTML

x - XML

trim - string.strip()

entity - HTML entity

unicode - 默认的unicode字符串

decode

n - 取消所有的默认filter

多个filter时，用comma（,）隔开，也可以自己定义filter

<%!
     def myescape(text):
         return "<TAG>" + text + "</TAG>"
%>

Here's some tagged text : ${"text" | myescape }

自己定义的filter需要为支持一个字符串的参数并且返回过滤后结果。

在<%page>标签中使用expression_filter可以为整个页面使用该过滤器。

也可以为block和def设置filter

<%def name="foo()" filter="h, trim">
    <b>this is bold</b>
</%def>

在执行

${" results " + somedef() + " more results "}

时会返回（假定somedef返回“somedef's results”字符串）

somedef's results results more results

这是由于somedef()在字符串链接前被全部执行，链接字符串将得到一个空的字符串返回值，为避免该问题，mako有两种方法：

<%def name="somedef()" buffered="True">
    somedef's results
</%def>

上面的代码会生成类似下面的代码：

def somedef():
    context.push_buffer()
    try:
        context.write("somedef's results")
    finally:
        buf = context.pop_buffer()
    return buf.getvalue()

或者使用

${" results " + capture(somedef) + " more results "}

capture类似python的apply方法，传递给somedef的参数，可由capture传递给somedef。

在使得def更加灵活对待filter，decorator在template中也支持。

<%!
    def bar(fn):
        def decorate(context, *args, **kw):
            context.write("BAR")
            fn(*args, **kw)
            context.write("BAR")
            return ''
        return decorate
%>

<%def name="foo()" decorator="bar">
    this is foo
</%def>

${foo()}

mako拥有内建的转义机制,有针对html,url和xml的转义还有trim函数,这些转义符号可以用|操作符追加在替换表达式后面

${"this is some text" | u}  # url转义
${"this is some text" | n}  # 无l转义，原样输出，可输出html等样式

输出 this+is+some+text,u代表url转义,而h代表html转义,x代表xml转义,trim代表trim函数,用于去掉字符串两边的空格,n表示不对html转义

控制结构

控制结构的语法都是以%<name>开头,以%end<name>结尾 

有if/else/elif, while/for, try/except，用%开头，用%end<name>结尾，name为表达式名称，与python一样，需要尾部添加:来表示一个表达式开始，但缩进不是必须的。

由于%被特殊使用，所有想要表达%，得用%%

if

% if x==5:
    this is some output
% endif

for

% 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

在for循环中有个loop上下文,它提供了很多额外的信息,比如:

<ul>
% for a in ("one", "two", "three"):
    <li>Item ${loop.index}: ${a}</li>
% endfor
</u>l

loop.index显示当前的迭代的索引位置,index的起始为0

注释

单行注释: mako 以两个#作为注释

## this is a comment.

多行注释:

<%doc>
    these are comments
    more comments
</%doc>

换行符

mako 和python 一样一反斜缸\做为换行符

more and more people 
go home 
等价于:
more and more people go home

python代码块

mako中嵌入python代码块时,使用标签<%和%>

<% 
##这里就是python代码块
x = 10000
y = x
%>
 
y = ${y}

这里的python代码块是位于模板中的渲染函数中的,如果是模块级别的代码,比如,函数,那就要用下面这个:

模块级别代码快

模块级代码块用<!%和 %> 就多一个感叹号

<%!
    import mylib
    import re
 
    def filter(text):
        return re.sub(r'^@', '', text)
%>

这里的filter函数就是与渲染函数是平级的了.模块级代码块可以存在mako中的任何位置,可以出现任意次数,最终渲染会按照声明的顺序合并在一块.

标签

mako提供了很多标签,如:include, def ,page等等,她的写法是:<%name>开头,结尾是/>或者</%name>,比如:

<%include file="foo.txt"/>
<%def name="foo" buffered="True">
    this is a def
</%def>

标签都有属性,有些属性是必须的,同时属性还支持赋值,所以你也可以使用表达式给属性赋值. 如:

<%include file="/foo/bar/${myfile}.txt"/>

<%include>

在mako文件中可以用include标签包含另外一个文件进来,比如所有页面都应该有header.html和footer.html,就可以把这两部分提取出来.

<%include file="header.html"/>
 
    hello world
 
<%include file="footer.html"/>

include标签还有一个args的参数,用来传递值给被包含的文件中去.它与标签<%page相对应.

<%include file="toolbar.html" args="current_section='members', username='ed'"/>

<%page>

<%page args="x, y, z='default'"/>
<%page cached="True" cache_type="memory"/>

目前,在一个模板中只能存在一个page标签,其他的会被忽略.且page标签不能放在其他标签里面,如放在block标签里面的,就读不到args设定的值.

<%def>

def标签定义了一个python函数,它包含一些内容,可以在其他地方调用.

<%def name="myfunc(x)">
    this is myfunc, x is ${x}
</%def>
 
${myfunc(19)}

如果<%def>没有在<%def>中嵌套，就是所谓的顶层def，所有的def可以当前上下文中调用。

由于def是python的函数，所有可以定义和传递参数，需要符合普通的python函数规范

来自其他文件def调用

顶层的<%def>可以导出到其他模板模块中，类似用<%include>方式来进行其他模板的<%def>调用。

导入其他模板，

<%namespace name="mystuff" file="mystuff.html">

然后mystuff就会到当前的scope中，然后调用mystuff

${mystuff.somedef(x=5,y=7)}

<%namespace>标签页支持python的import语句

<%namespace file="mystuff.html" import="foo, bar" />

调用def编程

可以在Template对象用get_def获取DefTemplate对象。

def嵌套

    在此处，mako官方给出两个非常有趣的例子

<%
    x = 12
%>
<%def name="outer()">
<%
        y = 15
    %>
<%def name="inner()">
        inner, x is ${x}, y is ${y}
</%def>

    outer, x is ${x}, y is ${y}
</%def>

和

<%
    x = 10
%>
<%def name="somedef()">
    ## error !
    somedef, x is ${x}
<%
        x = 27
    %>
</%def>

第二个列子中，x将会引用局部变量的那个x，此时x还未赋值，会报错！

在嵌入内容或者其他Def中调用def

可以通过<%namespace:defname>来扩展自定义的tag系统，大部分情况下local或者self表示当前的模板namespace。

当目标def已经卷入进来时，caller变量用来代替该出内容，caller包含另外的含body和def定义的namespace。body内部用方法body（）来引入。

<%def name="buildtable()">
    <table>
        <tr><td>
${caller.body()}
        </td></tr>
    </table>
</%def>

<%self:buildtable>
    I am the table body.
</%self:buildtable>

此时的caller用来替换<%self:buildtable>，注意self后面的名称与def定义的名称要一致。

官方还提供了下面的例子:

<%def name="lister(count)">
    % for x in range(count):
${caller.body()}
    % endfor
</%def>

<%self:lister count="${3}">
    hi
</%self:lister>

count="${3}"使得用来提供的3会被当成表达式处理，从而得到整形的3，而不是字符串3，这个range的参数必须是整形决定的。

注意body函数也可以传递参数
　　
Bocks
<%block>标签类似<%def>，匿名的block在局部render中可用，命名的block行为类似Jinja2的block标签，

与def的差别：
1、block声明不允许参数参数签名
2、命名block仅在一个模板中定义一次，如果有同名的则出错，如果有同名的def，也会出错。
3、命名的block不能再def中定义或者内部的body调用。

为了能够使得命名block可以共享page的参数，使用args属性，类似的**pageargs变量也存在命名的blocks，这个参数在page标签中不是显式存在的。

<%block>

block 可以对这块区域代码执行制定的操作,比如:

<%block filter="h">
    some <html> stuff.
</%block>

对文本some <html> stuff执行过滤操作.,block可以没有名字, 更常用的一种方式是用在继承上,比如定义个base.html:

##base.html
<html>
    <body>
    <%block name="header">
        <h2><%block name="title"/></h2>
    </%block>
    ${self.body()}
    </body>
</html>

然后你就可以在其它页面继承base.html,block区别可以被继承者覆盖掉 如:

允许模板可以在继承链中安排其自身的位置要用inherit继承

## index.html
<%inherit file="base.html"/>  
 
<%block name="header">
    this is some header content
</%block>

mako的context是一个保留的名称，其包含了一些下面的方法

context[key]或者context.get(key,default=None)，类似dict

keys 所有context中定义的名称

kwargs，返回一个context的dict变量，通常在传播变量时有用

write 写到缓冲区

lookup 返回一个TemplateLookup的实例。

Loop上下文（new in version 0.7）

在%for的block中，有一个保留字loop，便于迭代，如${loop.index}

无论如何形式的循环，loop都是基于0的迭代索引。

loop.index, loop.even, loop.odd, loop.first(用来表明是否为第一个迭代），loop.reverse_index, loop.last。

在0.7版本中，cycling可以在是否提供__len__方法中使用，

<ul>

　　%for item in ('spam', 'ham', 'eggs'):

　　<li class="${loop.cycle('even', 'odd')}">${item}</li>

　　%endfor

</ul>

loop.parent用来访问上一级的loop循环

在mako 0.7版本中loop成为保留字，为了兼容之前的，可以在TemplateLookup中屏蔽，enable_loop=False，或者在<%page>中使用 <%page enable_loop="True" />

下面是所有内建的关键字

context

local

self

parent

next

caller

loop

capture

UNDEFINED

pageargs

其中这几个是保留字 context, UNDEFINED, loop

namespace

mako的namespace用这个<%namespace>形式处理

<%namespace file="a.html" import="comp1, comp2" />

用来导入a.html中的comp1和comp2两个函数，这两个函数用mako的def定义

可以用属性name来重名该模块，然后用name来引用。函数调用类似python的函数调用。

同时还有一项强大的功能，就是调用python模块代码，通过属性module来导入python模块，然后用name来引用模块函数

注意函数必须要至少存在一个context的参数，任何返回值都将被render，因此一般返回''。

如果需要使用context中的caller对象，需要supports_caller（在mako.runtime中），如下面两种方式

from mako.runtime import supports_caller

@supports_caller
def my_tag(context):
    context.write("<div>")
    context['caller'].body()
    context.write("</div>")
    return ''

from mako.runtime import supports_caller, capture

@supports_caller
def my_tag(context):
    return "<div>%s</div>" % 
            capture(context, context['caller'].body, x="foo", y="bar")

在namespace中也支持def，类似模块中def。

## define a namespace
<%namespace name="stuff">
    <%def name="comp1()">
        comp1
    </%def>
</%namespace>

## then call it
${stuff.comp1()}

每个namespace中都有一个body函数，一般情况下不接受参数，如果实在需要接受参数，mako推荐通过<%page>标签来接受参数

<%page args="x, y, someval=8, scope='foo', **kwargs"/>

 当顶层的模板被调用时（通过render或者<%inclue>标签，这些参数值将从Context中传递过来）。**kwargs会从**pageargs中得到参数值。其他情况下，调用body方法是可以传递参数

当在继承模板时，这个功能将非常有用！

在namespace中内建的有local和self，local表示当前执行的template，self表示在没有使用继承时和local一样，使用继承时，表示最顶层的template。

namespace中的inheritable属性为True时，表示可以将namespace部分加载到self的namespace中，那么在所有的继承链中可以访问到该模板信息