在 Django 项目中集成 Wagtail¶

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

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

$ pip install wagtail

或者也可以将 wagtail 加入到项目的 requirements 文件中。 Wagtail 依赖的 Pillow 也将安装, 在这之前需要先安装操作系统的 libjpeg 和 zlib 库，参考 Pillow 的各个操作系统安装命令。

配置¶

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

'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 相关中间件:

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

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

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

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

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

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

WAGTAIL_SITE_NAME = 'My Example Site'

其它 Wagtail 的进一步配置可参考配置项。

URL 配置¶

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

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 地址空间, 配置语句可替换成:

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

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

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

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 and Deploying static files.

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

用户账户¶

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

应用开发¶

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

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