Wagtail Documentation Release 2.15a0 Torchbox Oct 02, 2021 Contents 1 Index 3 1.1 Getting started..............................................3 1.2 Usage guide............................................... 28 1.3 Advanced topics............................................. 84 1.4 Extending Wagtail............................................ 174 1.5 Reference................................................. 211 1.6 Support.................................................. 387 1.7 Using Wagtail: an Editor’s guide..................................... 388 1.8 Contributing to Wagtail......................................... 436 1.9 Release notes............................................... 464 Python Module Index 619 Index 621 i ii Wagtail Documentation, Release 2.15a0 Wagtail is an open source CMS written in Python and built on the Django web framework. Below are some useful links to help you get started with Wagtail. If you’d like to get a quick feel for Wagtail, try spinning up a temporary developer environment in your browser (running on Gitpod - here’s how it works). • First steps – Getting started – Your first Wagtail site – Demo site • Using Wagtail – Page models – Writing templates – How to use images in templates – Search – Third-party tutorials • For editors – Editors guide Contents 1 Wagtail Documentation, Release 2.15a0 2 Contents CHAPTER 1 Index 1.1 Getting started Note: These instructions assume familiarity with virtual environments and the Django web framework. For more detailed instructions, see Your first Wagtail site. To add Wagtail to an existing Django project, see Integrating Wagtail into a Django project. 1.1.1 Dependencies needed for installation • Python 3 • libjpeg and zlib, libraries required for Django’s Pillow library. See Pillow’s platform-specific installation in- structions. 1.1.2 Quick install Run the following in a virtual environment of your choice: $ pip install wagtail (Installing outside a virtual environment may require sudo.) Once installed, Wagtail provides a command similar to Django’s django-admin startproject to generate a new site/project: $ wagtail start mysite This will create a new folder mysite, based on a template containing everything you need to get started. More information on that template is available in the project template reference. Inside your mysite folder, run the setup steps necessary for any Django project: 3 Wagtail Documentation, Release 2.15a0 $ pip install -r requirements.txt $ ./manage.py migrate $ ./manage.py createsuperuser $ ./manage.py runserver Your site is now accessible at http://localhost:8000, with the admin backend available at http:// localhost:8000/admin/. This will set you up with a new stand-alone Wagtail project. If you’d like to add Wagtail to an existing Django project instead, see Integrating Wagtail into a Django project. There are a few optional packages which are not installed by default but are recommended to improve performance or add features to Wagtail, including: • Elasticsearch. • Feature Detection. Your first Wagtail site Note: This tutorial covers setting up a brand new Wagtail project. If you’d like to add Wagtail to an existing Django project instead, see Integrating Wagtail into a Django project. Install and run Wagtail Install dependencies Wagtail supports Python 3.6, 3.7, 3.8 and 3.9. To check whether you have an appropriate version of Python 3: $ python3 --version If this does not return a version number or returns a version lower than 3.6, you will need to install Python 3. Important: Before installing Wagtail, it is necessary to install the libjpeg and zlib libraries, which provide support for working with JPEG, PNG and GIF images (via the Python Pillow library). The way to do this varies by platform—see Pillow’s platform-specific installation instructions. Create and activate a virtual environment We recommend using a virtual environment, which isolates installed dependencies from other projects. This tutorial uses venv, which is packaged with Python 3. On Windows (cmd.exe): > python3 -m venv mysite\env > mysite\env\Scripts\activate.bat On GNU/Linux or MacOS (bash): 4 Chapter 1. Index Wagtail Documentation, Release 2.15a0 $ python3 -m venv mysite/env $ source mysite/env/bin/activate For other shells see the venv documentation. Note: If you’re using version control (e.g. git), mysite will be the directory for your project. The env directory inside of it should be excluded from any version control. Install Wagtail Use pip, which is packaged with Python, to install Wagtail and its dependencies: $ pip install wagtail Generate your site Wagtail provides a start command similar to django-admin startproject. Running wagtail start mysite in your project will generate a new mysite folder with a few Wagtail-specific extras, including the required project settings, a “home” app with a blank HomePage model and basic templates, and a sample “search” app. Because the folder mysite was already created by venv, run wagtail start with an additional argument to specify the destination directory: $ wagtail start mysite mysite Note: Generally, in Wagtail, each page type, or content type, is represented by a single app. However, differ- ent apps can be aware of each other and access each other’s data. All of the apps need to be registered within the INSTALLED_APPS section of the settings file. Look at this file to see how the start command has listed them in there. Install project dependencies $ cd mysite $ pip install -r requirements.txt This ensures that you have the relevant versions of Wagtail, Django, and any other dependencies for the project you have just created. Create the database If you haven’t updated the project settings, this will be a SQLite database file in the project directory. $ python manage.py migrate This command ensures that the tables in your database are matched to the models in your project. Every time you alter your model (eg. you may add a field to a model) you will need to run this command in order to update the database. 1.1. Getting started 5 Wagtail Documentation, Release 2.15a0 Create an admin user $ python manage.py createsuperuser When logged into the admin site, a superuser has full permissions and is able to view/create/manage the database. Start the server $ python manage.py runserver If everything worked, http://127.0.0.1:8000 will show you a welcome page: You can now access the administrative area at http://127.0.0.1:8000/admin 6 Chapter 1. Index Wagtail Documentation, Release 2.15a0 Extend the HomePage model Out of the box, the “home” app defines a blank HomePage model in models.py, along with a migration that creates a homepage and configures Wagtail to use it. Edit home/models.py as follows, to add a body field to the model: from django.db import models from wagtail.core.models import Page from wagtail.core.fields import RichTextField from wagtail.admin.edit_handlers import FieldPanel class HomePage(Page): body= RichTextField(blank= True) (continues on next page) 1.1. Getting started 7 Wagtail Documentation, Release 2.15a0 (continued from previous page) content_panels= Page.content_panels+[ FieldPanel('body', classname="full"), ] body is defined as RichTextField, a special Wagtail field. When blank=True, it means that this field is not required and can be empty. You can use any of the Django core fields. content_panels define the capabilities and the layout of the editing interface. When you add fields to content_panels, it enables them to be edited on the Wagtail interface. More on creating Page models. Run python manage.py makemigrations (this will create the migrations file), then python manage.py migrate (this executes the migrations and updates the database with your model changes). You must run the above commands each time you make changes to the model definition. You can now edit the homepage within the Wagtail admin area (go to Pages, Homepage, then Edit) to see the new body field. Enter some text into the body field, and publish the page by selecting Publish at the bottom of the page editor, rather than Save Draft. The page template now needs to be updated to reflect the changes made to the model. Wagtail uses normal Django tem- plates to render each page type. By default, it will look for a template filename formed from the app and model name, separating capital letters with underscores (e.g. HomePage within the ‘home’ app becomes home/home_page. html). This template file can exist in any location recognised by Django’s template rules; conventionally it is placed under a templates folder within the app. Edit home/templates/home/home_page.html to contain the following: {% extends "base.html" %} {% load wagtailcore_tags %} {% block body_class %}template-homepage{% endblock %} {% block content %} {{ page.body|richtext }} {% endblock %} base.html refers to a parent template and must always be the first template tag used in a template. Extending from this template saves you from rewriting code and allows pages across your app to share a similar frame (by using block tags in the child template, you are able to override specific content within the parent template). wagtailcore_tags must also be loaded at the top of the template and provide additional tags to those provided by Django. 8 Chapter 1. Index Wagtail Documentation, Release 2.15a0 Wagtail template tags In addition to Django’s template tags and filters, Wagtail provides a number of its own template tags & filters which can be loaded by including {% load wagtailcore_tags %} at the top of your template file. In this tutorial, we use the richtext filter to escape and print the contents of a RichTextField: {% load wagtailcore_tags %} {{ page.body|richtext }} Produces: <p> <b>Welcome</b> to our new site! </p> Note: You’ll need to include {% load wagtailcore_tags %} in each template that uses Wagtail’s tags. Django will throw a TemplateSyntaxError if the tags aren’t loaded. A basic blog We are now ready to create a blog. To do so, run python manage.py startapp blog to create a new app in your Wagtail site. Add the new blog app to INSTALLED_APPS in mysite/settings/base.py.