编写模板¶

Wagtail 使用 Django 模板语言。如果开发对 Django 不太熟悉，应先学习一下模板开发的文档：模板

做为 Django/Wagtail 的新手 Python 程序员也可以参考更多的文档： Django 模板语言：写给 Python 程序员

在继续阅读这篇文档之前一定要对 Django 模板基础知识有一定的了解。

模板¶

Wagtail 每种类型的页面或内容都定义在模型文件，一般命名为 models.py。对于博客应用一般会有一个 BlogPage 模型及另一个 BlogPageListing 模型。对于 models.py 每个模型， Wagtail 假定有一个同名的 HTML 模板文件。前端开发者应参考 models.py 文件中每个模型创建对应的模板。根据模型要映射到对应的模板，按照模型的驼峰命名规则，需要大写字母转换成下划线+小写字母，比如 BlogPage 模型缺省对应的模板是 blog_page.html。模板文件名在模型中也可以再重新定义。

模板文件存放的目录结构可参考如下:

name_of_project/
    name_of_app/
        templates/
            name_of_app/
                blog_page.html
        models.py

更多信息可参考 Django 文档应用目录模板加载.

页面内容¶

页面中引用数据/内容是通过 Django 的 {{ double-brace }} 标记。页面模型中的字段通过上下文中的 page 变量引用，使用 page. 格式，页面标题可通过 {{ page.title }}，作者可通过 {{ page.author }} 引用。要定制变量名可参考 配置页面模型 实现。即使定制了变量名， page 仍然在各个模板中使用。

另外 request. 也是可以使用的，里面存放了 Django 的 HTTP 请求对象。

静态资源¶

表态文件如 CSS, JS 及 images 通常保存在如下目录:

name_of_project/
    name_of_app/
        static/
            name_of_app/
                css/
                js/
                images/
        models.py

(“css”, “js” 等的文件名字并不重要，没有标示出来，只显示了它们存放的目录结构。)

静态目录中的文件在模板中引用时使用 {% static %} 标签，更详细的说明请参考：静态资源文件 (标签).

用户图片¶

上传到 Wagtail 网站图片(并不是上面所述的开发者预设的静态文件) 是放入图片库的，加到页面中时参考页面编辑界面。

不像其它 CMS，页面中增加图片时不涉及使用的图片版本。 Wagtail 没有预定义的 “formats” 或 “sizes”，而是通过开发者在模板中使用图片标签及特定语法生成 img 标签。只有图片库的图片才能使用这种方法。

这里所讲的图片标签及语法格式请参考在模板中使用图片。

模板标签及过滤器¶

在 Django 标签及过滤器基础上， Wagtail 还提供了一些预定义的标签及过滤器就像其它标签一样被加载。

图片 (标签)¶

image 图片标签能插入 HTML 兼容的 img 元素到页面中，同时设置图片的 src, width, height 及 alt 等属性。可参考设置 img 标签更多的属性.

image 标签的语法如下:

{% image [image] [resize-rule] %}

例如:

{% load wagtailimages_tags %}
...

{% image page.photo width-400 %}

<!-- or a square thumbnail: -->
{% image page.photo fill-80x80 %}

查看在模板中使用图片可以看到全面的说明文档。

富文本 (过滤器)¶

这个过滤器将一段 HTML 文本内容做为安全文本渲染到页面中。特别要说明的是过滤器可以内嵌图片的快捷引用及链接（在后面管理界面中编辑加入的），生成 HTML 显示时可正常引用的全链接。

只有 RichTextField 类型的字段才需要在模板中使用这种过滤器。

{% load wagtailcore_tags %}
...
{{ page.body|richtext }}

响应式嵌入对象¶

Wagtail 在模板上不会引用自身任何的样式，图片和嵌入媒体由 HTML 决定显示宽度。图片可以通过 CSS 设定的样式来自适应宽度变化，如：

.body img {
    max-width: 100%;
    height: auto;
}

定义 HTML body 容器中的图片是 100% 宽度，并且高度是自适应的。

要使用嵌入的媒体内容可以自适应大小，也可以采用这种方式， Wagtail 内部提供了自适应的模式，要打开这个选项，需要修改项目设置文件，将 WAGTAILEMBEDS_RESPONSIVE_HTML = True。这样生成内嵌对象时会增加 responsive-object 及 padding-bottom CSS 样式, 在 CSS 文件中可以定义这些样式的显示属性:

.responsive-object {
    position: relative;
}

.responsive-object iframe,
.responsive-object object,
.responsive-object embed {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
}

内部链接 (标签)¶

`pageurl`¶

使用页面对象做为参数，如果页面对象与当前页面在同一个站点则生成一个相对 URL (如 /foo/bar/) 地址，否则生成一个绝对 URL (如 http://example.com/foo/bar/) 地址。

{% load wagtailcore_tags %}
...
<a href="{% pageurl page.get_parent %}">Back to index</a>

另外还可以加一个 fallback 关键字参数，用在传入的页面对象为``None``时使用这个参数生成访问地址。参数取值应该是一个无参数的 URL 路由名。

{% load wagtailcore_tags %}

{% for publication in page.related_publications.all %}
    <li>
        <a href="{% pageurl publication.detail_page fallback='coming_soon' %}">
            {{ publication.title }}
        </a>
    </li>
{% endfor %}

`slugurl`¶

使用 “推广（Promote）” Tab 页中定义的网址缩写名 slug 来匹配并升成页面的 URL，如果能匹配的多个页面，则显示哪个页面是随机的。

和 pageurl 一样，也是先尝试显示相对 URL，然后页面如果和当前不在同一个站点时，显示绝对地址。这个标签一般用于分享或在页面导航及菜单中使用。

{% load wagtailcore_tags %}
...
<a href="{% slugurl 'news' %}">News index</a>

静态资源文件 (标签)¶

从静态资源文件目录中加载内容应用这个标签，而不应的模板中直接使用 “/static/” 等字符串进行拼接。使用这个标签方便将来改变静态资源路径，或者在开发与生产环境中使用相同的方式。

{% load static %}
...
<img src="{% static "name_of_app/myimage.jpg" %}" alt="My image"/>

注意不要使用相对项目的全路径名，只使用相对于应用（app）目录的相对路径即可，不需要包含 static。

多站点支持¶

`wagtail_site`¶

返回当前请求的站点对象。

{% load wagtailcore_tags %}

{% wagtail_site as current_site %}

Wagtail 用户菜单栏¶

为登录用户提供悬浮的用户菜单栏。菜单栏提供子菜单项，让页面编辑者可以快速编辑当前页面或向当前页面增加子页面，以及快速访问后台管理主页面。

显示在通常的没有页面对象的 Django 视图时，只有访问后台管理主页面的子菜单项。

{% load wagtailuserbar %}
...
{% wagtailuserbar %}

通常用户菜单栏显示在窗口的右下角，如果与界面内容有冲突，也可以在模板标签中加参数改变显示位置。这些例子展示如何将其显示在屏幕的四个角上:

...
{% wagtailuserbar 'top-left' %}
{% wagtailuserbar 'top-right' %}
{% wagtailuserbar 'bottom-left' %}
{% wagtailuserbar 'bottom-right' %}
...

另外通过 CSS 样式也可以定义用户菜单栏的显示位置。如：

.wagtail-userbar {
     top: 200px !important;
     left: 10px !important;
}

区分预览与实时查看¶

有时【预览】与【实时】查看想使用不同的展示效果，例如在实际运行时想加入 Google 访问分析，而编辑预览时不需要，Wagtail 提供了 request.is_preview 变量来区分【预览】与【实时】，示例代码如下：

{% if not request.is_preview %}
    <script>
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      ...
    </script>
{% endif %}