Wagtail Documentation Release 2.5.2

Wagtail Documentation Release 2.5.2 Torchbox May 04, 2020 Contents 1 Index 3 1.1 Getting started..............................................3 1.2 Usage guide............................................... 28 1.3 Advanced topics............................................. 87 1.4 Reference................................................. 168 1.5 Support.................................................. 273 1.6 Using Wagtail: an Editor’s guide..................................... 274 1.7 Contributing to Wagtail......................................... 305 1.8 Release notes............................................... 322 Python Module Index 431 Index 433 i ii Wagtail Documentation, Release 2.5.2 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, explore the Wagtail Bakery, a fully-functional interactive demo (hosted at Divio Cloud). • First steps – Getting started – Your first Wagtail site – Demo site • Using Wagtail – Page models – Writing templates – Using images in templates – Search – Third-party tutorials • For editors – Editors guide Contents 1 Wagtail Documentation, Release 2.5.2 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 instructions. 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.5.2 $ 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.4, 3.5, 3.6, and 3.7. 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.4, 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 provides an isolated Python environment. 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 Unix or MacOS (bash): 4 Chapter 1. Index Wagtail Documentation, Release 2.5.2 $ 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 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 Create an admin user $ python manage.py createsuperuser 1.1. Getting started 5 Wagtail Documentation, Release 2.5.2 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 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 (continues on next page) 6 Chapter 1. Index Wagtail Documentation, Release 2.5.2 1.1. Getting started 7 Wagtail Documentation, Release 2.5.2 (continued from previous page) class HomePage(Page): body= RichTextField(blank=True) content_panels= Page.content_panels+[ FieldPanel('body', classname="full"), ] body is defined as RichTextField, a special Wagtail field. You can use any of the Django core fields. content_panels define the capabilities and the layout of the editing interface. More on creating Page models. Run python manage.py makemigrations, then python manage.py migrate to update 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. The page template now needs to be updated to reflect the changes made to the model. Wagtail uses normal Django templates 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 %} 8 Chapter 1. Index Wagtail Documentation, Release 2.5.2 Wagtail template tags Wagtail provides a number of 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: <div class="rich-text"> <p> <b>Welcome</b> to our new site! </p> </div> 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. Blog Index and Posts Lets start with a simple index page for our blog. In blog/models.py: from wagtail.core.models import Page from wagtail.core.fields import RichTextField from wagtail.admin.edit_handlers import FieldPanel class BlogIndexPage(Page): intro= RichTextField(blank=True) content_panels= Page.content_panels+[ FieldPanel('intro', classname="full") ] Run python manage.py makemigrations and python manage.py migrate. Since the model is called BlogIndexPage, the default template name (unless we override it) will be blog/ templates/blog/blog_index_page.html. Create this file with the following content: {% extends "base.html" %} {% load wagtailcore_tags %} {% block body_class %}template-blogindexpage{% endblock %} (continues on next page) 1.1. Getting started 9 Wagtail Documentation, Release 2.5.2 (continued from previous page) {% block content %} <h1>{{ page.title }}</h1> <div class="intro">{{ page.intro|richtext }}</div> {% for post in page.get_children %} <h2><a href="{% pageurl post %}">{{ post.title }}</a></h2> {{ post.specific.intro }} {{ post.specific.body|richtext

Load more