.. _integrating_into_django:

在 Django 项目中集成 Wagtail
=========================================

对于新建项目 Wagtail 提供了 ``wagtail start`` 命令来快速创建一个新的 Wagtail 项目。但对于已存在 Django 项目，需要参考本节介绍的内容将 Wagtail 集成到现有的 Django 项目中。

Wagtail 2.x 版本兼容 Django 2.2, 3.0 以及 3.1。首先使用 pip 命令从 PyPI 安装 ``wagtail`` 软件包:

.. code-block:: console

    $ pip install wagtail

或者也可以将 wagtail 加入到项目的 requirements 文件中。 Wagtail 依赖的 **Pillow** 也将安装, 在这之前需要先安装操作系统
的 libjpeg 和 zlib 库，参考 Pillow 的 `各个操作系统安装命令 <https://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_ 。

配置
--------

在配置文件的 ``INSTALLED_APPS`` 列表中增加 Wagtail 相关应用:

.. code-block:: python

    'wagtail.contrib.forms',
    'wagtail.contrib.redirects',
    'wagtail.embeds',
    'wagtail.sites',
    'wagtail.users',
    'wagtail.snippets',
    'wagtail.documents',
    'wagtail.images',
    'wagtail.search',
    'wagtail.admin',
    'wagtail.core',

    'modelcluster',
    'taggit',

在 ``MIDDLEWARE`` 列表中增加 Wagtail 相关中间件:

.. code-block:: python

    'wagtail.contrib.redirects.middleware.RedirectMiddleware',

如果项目没有配置 ``STATIC_ROOT`` 则增加并配置 static 目录:

.. code-block:: python

    STATIC_ROOT = os.path.join(BASE_DIR, 'static')

如果项目没有配置 ``MEDIA_ROOT`` 和 ``MEDIA_URL``，则增加相应配置:

.. code-block:: python

    MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
    MEDIA_URL = '/media/'

增加 ``WAGTAIL_SITE_NAME`` 配置 - 显示在后台管理界面上的网站名称:

.. code-block:: python

    WAGTAIL_SITE_NAME = 'My Example Site'

其它 Wagtail 的进一步配置可参考 :doc:`/reference/settings`。

URL 配置
-----------------

将如下 url 配置加入到 ``urls.py`` 文件中:

.. code-block:: python

    from django.urls import path, re_path, include

    from wagtail.admin import urls as wagtailadmin_urls
    from wagtail.core import urls as wagtail_urls
    from wagtail.documents import urls as wagtaildocs_urls

    urlpatterns = [
        ...
        path('cms/', include(wagtailadmin_urls)),
        path('documents/', include(wagtaildocs_urls)),
        path('pages/', include(wagtail_urls)),
        ...
    ]

这些 URL 路径可根据项目规划进行一些必要修改。

``wagtailadmin_urls`` 提供 Wagtail 管理界面的 url 配置，它独立于 Django 的管理界面 (``django.contrib.admin``); 通常新建的 Wagtail 项目会使用 ``/admin/`` 路径,
但如果当前项目已经使用的 ``/admin/``， Wagtail 后台管理界面的访问地址就需要变更，这里使用 ``/cms/``。

``wagtaildocs_urls`` 是文档文件服务地址。如果不打算使用 Wagtail 的文档文件管理功能，也可以省略。

``wagtail_urls`` 是 Wagtail 网站服务地址。在上面的配置中, Wagtail 将处理请求地址映射于 ``/pages/`` 路径下, 其余根目录下的地址交由当前的 Django 项目处理。
如果需要 Wagtail 处理所有 URL 包括根 URL 地址空间, 配置语句可替换成:

.. code-block:: python

    re_path(r'', include(wagtail_urls)),

这种情况下，语句应放在 ``urlpatterns`` 列表最后，这样就不会覆盖其它项目中指定的 URL 模式。

最后，项目工程应配置用户上传文件目录 ``MEDIA_ROOT``。 如果当前项目 URL 配置没有配置，需要增加如下内容到 ``urls.py`` 文件中:

.. code-block:: python

    from django.conf import settings
    from django.conf.urls.static import static

    urlpatterns = [
        # ... the rest of your URLconf goes here ...
    ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

注意这只是运行在 (``DEBUG = True``) 开发环境下配置方法; 在生产环境下应该配置 Web 服务器来读取 ``MEDIA_ROOT`` 中的文件。
进一步的说明请参考 Django 文档: `Serving files uploaded by a user during development <https://docs.djangoproject.com/en/stable/howto/static-files/#serving-files-uploaded-by-a-user-during-development>`_ and `Deploying static files <https://docs.djangoproject.com/en/stable/howto/static-files/deployment/>`_.

当这些配置完成后，就可以执行 ``./manage.py migrate`` 创建 Wagtail 使用到的数据库表了。

用户账户
-------------

Django 超级用户有 Wagtail 管理界面的操作权限。在当前系统没有创建超级用户时，可使用 ``./manage.py createsuperuser`` 命令创建。
Wagtail 扩展了 Django 的用户模型及权限架构, 当前项目工程使用自定义的用户模型，需要满足一定条件，即当前项目工程的用户模型应保证至少继承了
Django 的``AbstractBaseUser`` 以及 ``PermissionsMixin`` 类。

应用开发
----------------

完成上面的系统配置后，就可以继续开发包含 Wagtail 模块的 Django 项目了。例如，新增一个应用到 Django 项目（通过 ``./manage.py startapp`` 命令，
并记着要将新增应用添加到 ``INSTALLED_APPS`` 列表)。 页面模型的开发请参考 :doc:`/getting_started/tutorial` 中的说明。

注意，使用 Wagtail 创建新项目时，会基于 ``Page`` 基础类型创建站点主页（虽然主页只有一个标题内容）。但在当前已有项目中加入 Wagtail 模块时这个主页不会自动创建，
需要在后台管理界面中，先配置站点，然后增加网站的起始主页。