.. _writing_templates:

=================
编写模板
=================

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

做为 Django/Wagtail 的新手 Python 程序员也可以参考更多的文档：
:doc:`ref/templates/api`

在继续阅读这篇文档之前一定要对 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 文档 :doc:`应用目录模板加载 <ref/templates/api>`.

页面内容
~~~~~~~~~~~~

页面中引用数据/内容是通过 Django 的 ``{{ double-brace }}`` 标记。页面模型中的字段通过上下文中的 page 变量引用，使用 ``page.`` 格式，页面标题可通过 ``{{ page.title }}``，作者可通过 ``{{ page.author }}`` 引用。
要定制变量名可参考 :attr:`配置页面模型 <wagtail.core.models.Page.context_object_name>` 实现。即使定制了变量名， ``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 %}`` 标签，更详细的说明请参考： :ref:`static_tag`.

用户图片
~~~~~~~~~~~

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

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

这里所讲的图片标签及语法格式请参考 :ref:`image_tag`。

.. _template-tags-and-filters:

模板标签及过滤器
=======================

在 Django 标签及过滤器基础上， Wagtail 还提供了一些预定义的标签及过滤器 :doc:`就像其它标签 <howto/custom-template-tags>` 一样被加载。


图片 (标签)
~~~~~~~~~~~~

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

``image`` 标签的语法如下:

.. code-block:: html+django

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

例如:

.. code-block:: html+django

    {% load wagtailimages_tags %}
    ...

    {% image page.photo width-400 %}

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


查看 :ref:`image_tag` 可以看到全面的说明文档。


.. _rich-text-filter:

富文本 (过滤器)
~~~~~~~~~~~~~~~~~~

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

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

.. code-block:: html+django

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


.. _responsive-embeds:

响应式嵌入对象
-----------------

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

.. code-block:: css

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

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

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

.. code-block:: 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_tag:

``pageurl``
-----------

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

.. code-block:: html+django

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


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

.. code-block:: html+django

    {% 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_tag:

``slugurl``
------------

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

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

.. code-block:: html+django

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


.. _static_tag:

静态资源文件 (标签)
~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


.. code-block:: html+django

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

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


多站点支持
~~~~~~~~~~~~~~~~~~

.. _wagtail_site_tag:

``wagtail_site``
----------------

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

.. code-block:: html+django

    {% load wagtailcore_tags %}

    {% wagtail_site as current_site %}

.. _wagtailuserbar_tag:

Wagtail 用户菜单栏
======================

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

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

.. code-block:: html+django

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

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

.. code-block:: html+django

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

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

.. code-block:: css

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


区分预览与实时查看
=======================================

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

.. code-block:: html+django

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