kopia lustrzana https://github.com/wagtail/wagtail
LB (Ben Johnston)
GitHub
rodzic
58a8a31dd6
commit
6ed65f14c6
|
|
@ -1,6 +1,6 @@
|
|||
# Third-party tutorials
|
||||
|
||||
```eval_rst warning::
|
||||
```{warning}
|
||||
The following list is a collection of tutorials and development notes
|
||||
from third-party developers. Some of the older links may not apply to
|
||||
the latest Wagtail versions.
|
||||
|
|
|
|||
14
docs/conf.py
14
docs/conf.py
|
|
@ -18,7 +18,6 @@ from datetime import datetime
|
|||
|
||||
import django
|
||||
import sphinx_wagtail_theme
|
||||
from recommonmark.transform import AutoStructify
|
||||
|
||||
from wagtail import VERSION, __version__
|
||||
|
||||
|
|
@ -57,7 +56,7 @@ os.environ["DATABASE_ENGINE"] = "django.db.backends.sqlite3"
|
|||
extensions = [
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.intersphinx",
|
||||
"recommonmark",
|
||||
"myst_parser",
|
||||
"sphinx_wagtail_theme",
|
||||
]
|
||||
|
||||
|
|
@ -299,14 +298,3 @@ texinfo_documents = [
|
|||
|
||||
def setup(app):
|
||||
app.add_js_file("js/banner.js")
|
||||
|
||||
github_doc_root = "https://github.com/wagtail/wagtail/tree/main/docs/"
|
||||
|
||||
app.add_config_value(
|
||||
"recommonmark_config",
|
||||
{
|
||||
"url_resolver": lambda url: github_doc_root + url,
|
||||
},
|
||||
True,
|
||||
)
|
||||
app.add_transform(AutoStructify)
|
||||
|
|
|
|||
|
|
@ -1,14 +1,15 @@
|
|||
# Documentation guidelines
|
||||
|
||||
```eval_rst
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
```{contents}
|
||||
---
|
||||
local:
|
||||
depth: 1
|
||||
---
|
||||
```
|
||||
|
||||
## Formatting recommendations
|
||||
|
||||
Wagtail’s documentation uses a mixture of [Markdown](https://commonmark.org/help/) and [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). We encourage writing documentation in Markdown first, and only reaching for more advanced reStructuredText formatting if there is a compelling reason.
|
||||
Wagtail’s documentation uses a mixture of [Markdown](https://myst-parser.readthedocs.io/en/stable/syntax/syntax.html) and [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). We encourage writing documentation in Markdown first, and only reaching for more advanced reStructuredText formatting if there is a compelling reason.
|
||||
|
||||
Here are formats we encourage using when writing documentation for Wagtail.
|
||||
|
||||
|
|
@ -89,7 +90,7 @@ Don’t rely on [`links over code`](https://www.example.com/), as they are impos
|
|||
|
||||
```md
|
||||
An [external link](https://wwww.example.com).
|
||||
An [internal link to another document](/reference/contrib/legacy_richtext.md).
|
||||
An [internal link to another document](/reference/contrib/legacy_richtext).
|
||||
A [link to a reference](register_reports_menu_item).
|
||||
```
|
||||
|
||||
|
|
@ -98,35 +99,66 @@ A [link to a reference](register_reports_menu_item).
|
|||
<summary>Rendered output</summary>
|
||||
|
||||
An [external link](https://wwww.example.com).
|
||||
An [internal link to another document](/reference/contrib/legacy_richtext.md).
|
||||
An [internal link to another document](/reference/contrib/legacy_richtext).
|
||||
A [link to a reference](register_reports_menu_item).
|
||||
|
||||
</details>
|
||||
|
||||
Reference links rely on creating a reference in reStructuredText. Prefer linking to the whole document if at all possible, otherwise create a reference by embedding reStructuredText with `eval_rst`:
|
||||
#### Reference links
|
||||
|
||||
```eval_rst
|
||||
.. _register_reports_menu_item:
|
||||
```
|
||||
Reference links (links to a target within a page) rely on the page having a reference created, this can be added as follows:
|
||||
|
||||
```md
|
||||
|
||||
(my_awesome_section)=
|
||||
##### Some awesome section title
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
The reference can be linked to, with an auto-generated label, using the Markdown link syntax as follows:
|
||||
|
||||
```md
|
||||
[](my_awesome_section)
|
||||
```
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Rendered output</summary>
|
||||
|
||||
(my_awesome_section)=
|
||||
##### Some awesome section title
|
||||
|
||||
...
|
||||
|
||||
[](my_awesome_section)
|
||||
|
||||
</details>
|
||||
|
||||
You can read more about other methods of linking to, and creating references in the MyST parser docs section on [Targets and cross-referencing](https://myst-parser.readthedocs.io/en/stable/syntax/syntax.html#targets-and-cross-referencing).
|
||||
|
||||
### Note and warning call-outs
|
||||
|
||||
Use notes and warnings sparingly, as they rely on reStructuredText syntax which is more complicated for future editors.
|
||||
|
||||
```eval_rst note:: Notes can provide complementary information.
|
||||
```{note}
|
||||
Notes can provide complementary information.
|
||||
```
|
||||
|
||||
```eval_rst warning:: Warnings can be scary.
|
||||
```{warning}
|
||||
Warnings can be scary.
|
||||
```
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Rendered output</summary>
|
||||
|
||||
```eval_rst note:: Notes can provide complementary information.
|
||||
```{note}
|
||||
Notes can provide complementary information.
|
||||
```
|
||||
|
||||
```eval_rst warning:: Warnings can be scary.
|
||||
```{warning}
|
||||
Warnings can be scary.
|
||||
```
|
||||
|
||||
</details>
|
||||
|
|
@ -155,7 +187,7 @@ Images are hard to keep up-to-date as documentation evolves, but can be worthwhi
|
|||
|
||||
With its [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) feature, Sphinx supports writing documentation in Python docstrings for subsequent integration in the project’s documentation pages. This is a very powerful feature which we highly recommend using to document Wagtail’s APIs.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. module:: wagtail.core.utils
|
||||
|
||||
.. autofunction:: cautious_slugify
|
||||
|
|
@ -164,7 +196,7 @@ With its [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc
|
|||
<details>
|
||||
<summary>Rendered output</summary>
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. module:: wagtail.core.utils
|
||||
|
||||
.. autofunction:: cautious_slugify
|
||||
|
|
@ -176,7 +208,7 @@ With its [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc
|
|||
|
||||
Only use tables when needed, with the “simple” reStructuredText syntax, which is hard enough to format as it is.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
============= =============
|
||||
Browser Device/OS
|
||||
============= =============
|
||||
|
|
@ -190,7 +222,7 @@ Only use tables when needed, with the “simple” reStructuredText syntax, whic
|
|||
|
||||
<summary>Rendered output</summary>
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
============= =============
|
||||
Browser Device/OS
|
||||
============= =============
|
||||
|
|
@ -202,45 +234,44 @@ Safari Windows
|
|||
|
||||
</details>
|
||||
|
||||
### Tables of content
|
||||
### Tables of contents
|
||||
|
||||
`toctree` and `contents` can be used as reStructuredText embeds.
|
||||
`toctree` and `contents` can be used as reStructuredText directives.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:titlesonly:
|
||||
|
||||
getting_started/index
|
||||
topics/index
|
||||
```{toctree}
|
||||
---
|
||||
maxdepth: 2
|
||||
titlesonly:
|
||||
---
|
||||
getting_started/index
|
||||
topics/index
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. contents::
|
||||
```{contents}
|
||||
---
|
||||
local:
|
||||
depth: 1
|
||||
---
|
||||
```
|
||||
|
||||
### Version added, changed, deprecations
|
||||
|
||||
Sphinx offers release-metadata directives to generate this information consistently. Use as appropriate.
|
||||
|
||||
```eval_rst
|
||||
.. versionadded:: 2.15
|
||||
```{versionadded} 2.15
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. versionchanged:: 2.15
|
||||
```{versionchanged} 2.15
|
||||
```
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Rendered output</summary>
|
||||
|
||||
```eval_rst
|
||||
.. versionadded:: 2.15
|
||||
```{versionadded} 2.15
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. versionchanged:: 2.15
|
||||
```{versionchanged} 2.15
|
||||
```
|
||||
|
||||
</details>
|
||||
|
|
@ -275,7 +306,7 @@ There is some formatting in the documentation which is technically supported, bu
|
|||
|
||||
### Call-outs
|
||||
|
||||
We only use `note::` and `warning::` call-outs. Avoid `important::`, `topic::`, and `tip::`. If you find one of these, please replace it with `note::`.
|
||||
We only use `{note}` and `{warning}` call-outs. Avoid `{important}`, `{topic}`, and `{tip}`. If you find one of these, please replace it with `{note}`.
|
||||
|
||||
### Glossary
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,7 @@
|
|||
# Reporting security issues
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
Please report security issues **only** to `security@wagtail.org <mailto:security@wagtail.org>`_.
|
||||
```{note}
|
||||
Please report security issues **only** to [security@wagtail.org](mailto:security@wagtail.org).
|
||||
```
|
||||
|
||||
Most normal bugs in Wagtail are reported as [GitHub issues](https://github.com/wagtail/wagtail/issues), but due to the sensitive nature of security issues, we ask that they not be publicly reported in this fashion.
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ the `date` and `image` fields on the form will use a date picker and image choos
|
|||
|
||||
If you have implemented a form widget of your own, you can configure `WagtailAdminModelForm` to select it for a given model field type. This is done by calling the `wagtail.admin.forms.models.register_form_field_override` function, typically in an `AppConfig.ready` method.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. function:: register_form_field_override(model_field_class, to=None, override=None, exact_class=False)
|
||||
|
||||
Specify a set of options that will override the form field's defaults when ``WagtailAdminModelForm`` encounters a given model field type.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# Template components
|
||||
|
||||
Working with objects that know how to render themselves as elements on an HTML template is a common pattern seen throughout the Wagtail admin. For example, the admin homepage is a view provided by the central `wagtail.admin` app, but brings together information panels sourced from various other modules of Wagtail, such as images and documents (potentially along with others provided by third-party packages). These panels are passed to the homepage via the [`construct_homepage_panels`](../reference/hooks.html#construct-homepage-panels) hook, and each one is responsible for providing its own HTML rendering. In this way, the module providing the panel has full control over how it appears on the homepage.
|
||||
Working with objects that know how to render themselves as elements on an HTML template is a common pattern seen throughout the Wagtail admin. For example, the admin homepage is a view provided by the central `wagtail.admin` app, but brings together information panels sourced from various other modules of Wagtail, such as images and documents (potentially along with others provided by third-party packages). These panels are passed to the homepage via the [`construct_homepage_panels`](construct_homepage_panels) hook, and each one is responsible for providing its own HTML rendering. In this way, the module providing the panel has full control over how it appears on the homepage.
|
||||
|
||||
Wagtail implements this pattern using a standard object type known as a **component**. A component is a Python object that provides the following methods and properties:
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. method:: render_html(self, parent_context=None)
|
||||
|
||||
Given a context dictionary from the calling template (which may be a :py:class:`Context <django.template.Context>` object or a plain ``dict`` of context variables), returns the string representation to be inserted into the template. This will be subject to Django's HTML escaping rules, so a return value consisting of HTML should typically be returned as a :py:mod:`SafeString <django.utils.safestring>` instance.
|
||||
|
|
@ -12,14 +12,14 @@ Given a context dictionary from the calling template (which may be a :py:class:`
|
|||
.. attribute:: media
|
||||
|
||||
A (possibly empty) :doc:`form media <django:topics/forms/media>` object defining JavaScript and CSS resources used by the component.
|
||||
|
||||
.. note::
|
||||
Any object implementing this API can be considered a valid component; it does not necessarily have to inherit from the ``Component`` class described below, and user code that works with components should not assume this (for example, it must not use ``isinstance`` to check whether a given value is a component).
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. _creating_template_components:
|
||||
```{note}
|
||||
Any object implementing this API can be considered a valid component; it does not necessarily have to inherit from the `Component` class described below, and user code that works with components should not assume this (for example, it must not use `isinstance` to check whether a given value is a component).
|
||||
```
|
||||
|
||||
(creating_template_components)=
|
||||
|
||||
## Creating components
|
||||
|
||||
The preferred way to create a component is to define a subclass of `wagtail.admin.ui.components.Component` and specify a `template_name` attribute on it. The rendered template will then be used as the component's HTML representation:
|
||||
|
|
|
|||
|
|
@ -1,15 +1,14 @@
|
|||
```eval_rst
|
||||
```{eval-rst}
|
||||
:hidetoc: 1
|
||||
```
|
||||
|
||||
# Getting started
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
```{note}
|
||||
These instructions assume familiarity with virtual environments and the
|
||||
`Django web framework <https://www.djangoproject.com/>`_.
|
||||
For more detailed instructions, see :doc:`tutorial`.
|
||||
To add Wagtail to an existing Django project, see :doc:`integrating_into_django`.
|
||||
[Django web framework](https://www.djangoproject.com/).
|
||||
For more detailed instructions, see [](tutorial).
|
||||
To add Wagtail to an existing Django project, see [](integrating_into_django).
|
||||
```
|
||||
|
||||
## Dependencies needed for installation
|
||||
|
|
@ -54,15 +53,15 @@ If you\'d like to add Wagtail to an existing Django project instead, see [Integr
|
|||
|
||||
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](/advanced_topics/performance).
|
||||
> - [Feature Detection](image_feature_detection).
|
||||
- [Elasticsearch](/advanced_topics/performance).
|
||||
- [Feature Detection](image_feature_detection).
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
tutorial
|
||||
demo_site
|
||||
integrating_into_django
|
||||
the_zen_of_wagtail
|
||||
```{toctree}
|
||||
---
|
||||
maxdepth: 1
|
||||
---
|
||||
tutorial
|
||||
demo_site
|
||||
integrating_into_django
|
||||
the_zen_of_wagtail
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,3 @@
|
|||
```eval_rst
|
||||
.. _integrating_into_django:
|
||||
```
|
||||
# Integrating Wagtail into a Django project
|
||||
|
||||
Wagtail provides the `wagtail start` command and project template to get you started with a new Wagtail project as quickly as possible, but it's easy to integrate Wagtail into an existing Django project too.
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ Suppose a content author comes to you with a request: "We need this text to be i
|
|||
|
||||
A common sight in content management systems is a point-and-click interface to let you define the data model that makes up a page:
|
||||
|
||||
|
||||
|
||||
|
||||
It looks nice in the sales pitch, but in reality, no CMS end-user can realistically make that kind of fundamental change - on a live site, no less - unless they have a programmer's insight into how the site is built, and what impact the change will have. As such, it will always be the programmer's job to negotiate that point-and-click interface - all you've done is taken them away from the comfortable world of writing code, where they have a whole ecosystem of tools, from text editors to version control systems, to help them develop, test and deploy their code changes.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,8 @@
|
|||
# Your first Wagtail site
|
||||
|
||||
```eval_rst
|
||||
.. 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 :doc:`integrating_into_django`.
|
||||
```{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_into_django).
|
||||
```
|
||||
|
||||
## Install and run Wagtail
|
||||
|
|
@ -20,11 +19,10 @@ $ python3 --version
|
|||
|
||||
If this does not return a version number or returns a version lower than 3.7, you will need to [install Python 3](https://www.python.org/downloads/).
|
||||
|
||||
```eval_rst
|
||||
.. important::
|
||||
```{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 <https://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_.
|
||||
[platform-specific installation instructions](https://pillow.readthedocs.org/en/latest/installation.html#external-libraries).
|
||||
```
|
||||
|
||||
### Create and activate a virtual environment
|
||||
|
|
@ -48,11 +46,9 @@ $ source mysite/env/bin/activate
|
|||
|
||||
**For other shells** see the [`venv` documentation](https://docs.python.org/3/library/venv.html).
|
||||
|
||||
```eval_rst
|
||||
.. 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.
|
||||
```{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
|
||||
|
|
@ -77,10 +73,8 @@ Because the folder `mysite` was already created by `venv`, run `wagtail start` w
|
|||
$ wagtail start mysite mysite
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
|
||||
Generally, in Wagtail, each page type, or content type, is represented by a single app. However, different 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.
|
||||
```{note}
|
||||
Generally, in Wagtail, each page type, or content type, is represented by a single app. However, different 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
|
||||
|
|
@ -761,9 +755,7 @@ something like this:
|
|||
|
||||
|
||||
|
||||
```eval_rst
|
||||
.. _tutorial_categories:
|
||||
```
|
||||
(tutorial_categories)=
|
||||
|
||||
### Categories
|
||||
|
||||
|
|
@ -795,9 +787,8 @@ class BlogCategory(models.Model):
|
|||
verbose_name_plural = 'blog categories'
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
Note that we are using ``panels`` rather than ``content_panels`` here - since snippets generally have no need for fields such as slug or publish date, the editing interface for them is not split into separate 'content' / 'promote' / 'settings' tabs as standard, and so there is no need to distinguish between 'content panels' and 'promote panels'.
|
||||
```{note}
|
||||
Note that we are using `panels` rather than `content_panels` here - since snippets generally have no need for fields such as slug or publish date, the editing interface for them is not split into separate 'content' / 'promote' / 'settings' tabs as standard, and so there is no need to distinguish between 'content panels' and 'promote panels'.
|
||||
```
|
||||
|
||||
Migrate this change in, and create a few categories through the Snippets area which now appears in the admin menu.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
# Legacy richtext
|
||||
|
||||
```eval_rst
|
||||
.. module:: wagtail.contrib.legacy.richtext
|
||||
```{module} wagtail.contrib.legacy.richtext
|
||||
```
|
||||
|
||||
Provides the legacy richtext wrapper.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,10 @@
|
|||
# Wagtail 2.16.2 release notes - IN DEVELOPMENT
|
||||
|
||||
```eval_rst
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
```{contents}
|
||||
---
|
||||
local:
|
||||
depth: 1
|
||||
---
|
||||
```
|
||||
|
||||
## What's new
|
||||
|
|
|
|||
|
|
@ -1,9 +1,10 @@
|
|||
# Wagtail 2.16 release notes
|
||||
|
||||
```eval_rst
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
```{contents}
|
||||
---
|
||||
local:
|
||||
depth: 1
|
||||
---
|
||||
```
|
||||
|
||||
## What's new
|
||||
|
|
|
|||
|
|
@ -1,9 +1,10 @@
|
|||
# Wagtail 2.17 release notes - IN DEVELOPMENT
|
||||
|
||||
```eval_rst
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
```{contents}
|
||||
---
|
||||
local:
|
||||
depth: 1
|
||||
---
|
||||
```
|
||||
|
||||
## What's new
|
||||
|
|
|
|||
|
|
@ -1,2 +1,3 @@
|
|||
docutils==0.16 # Pinned to work around https://github.com/sphinx-doc/sphinx/issues/9049
|
||||
docutils==0.17
|
||||
myst_parser==0.17.0
|
||||
sphinx-wagtail-theme==5.0.4
|
||||
|
|
|
|||
|
|
@ -1,15 +1,15 @@
|
|||
# Usage guide
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:titlesonly:
|
||||
|
||||
pages
|
||||
writing_templates
|
||||
images
|
||||
search/index
|
||||
snippets
|
||||
streamfield
|
||||
permissions
|
||||
```{toctree}
|
||||
---
|
||||
maxdepth: 2
|
||||
titlesonly:
|
||||
---
|
||||
pages
|
||||
writing_templates
|
||||
images
|
||||
search/index
|
||||
snippets
|
||||
streamfield
|
||||
permissions
|
||||
```
|
||||
|
|
@ -1,18 +1,14 @@
|
|||
# Page models
|
||||
|
||||
```eval_rst
|
||||
Each page type (a.k.a. content type) in Wagtail is represented by a Django model. All page models must inherit from the :class:`wagtail.core.models.Page` class.
|
||||
```
|
||||
Each page type (a.k.a. content type) in Wagtail is represented by a Django model. All page models must inherit from the {class}`wagtail.core.models.Page` class.
|
||||
|
||||
As all page types are Django models, you can use any field type that Django provides. See [Model field reference](https://docs.djangoproject.com/en/stable/ref/models/fields/) for a complete list of field types you can use. Wagtail also provides `wagtail.core.fields.RichTextField` which provides a WYSIWYG editor for editing rich-text content.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
```{note}
|
||||
If you're not yet familiar with Django models, have a quick look at the following links to get you started:
|
||||
|
||||
If you're not yet familiar with Django models, have a quick look at the following links to get you started:
|
||||
|
||||
* :ref:`Creating models <django:creating-models>`
|
||||
* :doc:`Model syntax <django:topics/db/models>`
|
||||
* {ref}`Creating models <django:creating-models>`
|
||||
* {doc}`Model syntax <django:topics/db/models>`
|
||||
```
|
||||
|
||||
## An example Wagtail page model
|
||||
|
|
@ -84,10 +80,8 @@ class BlogPageRelatedLink(Orderable):
|
|||
]
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
|
||||
Ensure that none of your field names are the same as your class names. This will cause errors due to the way Django handles relations (`read more <https://github.com/wagtail/wagtail/issues/503>`_). In our examples we have avoided this by appending "Page" to each model name.
|
||||
```{note}
|
||||
Ensure that none of your field names are the same as your class names. This will cause errors due to the way Django handles relations ([read more](https://github.com/wagtail/wagtail/issues/503)). In our examples we have avoided this by appending "Page" to each model name.
|
||||
```
|
||||
|
||||
## Writing page models
|
||||
|
|
@ -135,34 +129,27 @@ Here's a summary of the `EditHandler` classes that Wagtail provides out of the b
|
|||
|
||||
These allow editing of model fields. The `FieldPanel` class will choose the correct widget based on the type of the field, such as a rich text editor for `RichTextField`, or an image chooser for a `ForeignKey` to an image model. `FieldPanel` also provides a page chooser interface for `ForeignKey`s to page models, but for more fine-grained control over which page types can be chosen, `PageChooserPanel` provides additional configuration options.
|
||||
|
||||
```eval_rst
|
||||
- :class:`~wagtail.admin.edit_handlers.FieldPanel`
|
||||
- :class:`~wagtail.admin.edit_handlers.PageChooserPanel`
|
||||
- {class}`~wagtail.admin.edit_handlers.FieldPanel`
|
||||
- {class}`~wagtail.admin.edit_handlers.PageChooserPanel`
|
||||
|
||||
.. versionchanged:: 2.17
|
||||
|
||||
Previously, certain field types required special-purpose panels: ``StreamFieldPanel``, ``ImageChooserPanel``, ``DocumentChooserPanel`` and ``SnippetChooserPanel``. These are now all handled by ``FieldPanel``.
|
||||
```{versionchanged} 2.17
|
||||
Previously, certain field types required special-purpose panels: `StreamFieldPanel`, `ImageChooserPanel`, `DocumentChooserPanel` and `SnippetChooserPanel`. These are now all handled by `FieldPanel`.
|
||||
```
|
||||
|
||||
|
||||
**Structural**
|
||||
|
||||
These are used for structuring fields in the interface.
|
||||
|
||||
```eval_rst
|
||||
- :class:`~wagtail.admin.edit_handlers.MultiFieldPanel`
|
||||
- :class:`~wagtail.admin.edit_handlers.InlinePanel`
|
||||
- :class:`~wagtail.admin.edit_handlers.FieldRowPanel`
|
||||
```
|
||||
- {class}`~wagtail.admin.edit_handlers.MultiFieldPanel`
|
||||
- {class}`~wagtail.admin.edit_handlers.InlinePanel`
|
||||
- {class}`~wagtail.admin.edit_handlers.FieldRowPanel`
|
||||
|
||||
|
||||
#### Customising the page editor interface
|
||||
|
||||
The page editor can be customised further. See [Customising the editing interface](/advanced_topics/customisation/page_editing_interface).
|
||||
|
||||
```eval_rst
|
||||
.. _page_type_business_rules:
|
||||
```
|
||||
(page_type_business_rules)=
|
||||
### Parent page / subpage type rules
|
||||
|
||||
These two attributes allow you to control where page types may be used in your site. It allows you to define rules like "blog entries may only be created under a blog index".
|
||||
|
|
@ -176,9 +163,7 @@ By default, any page type can be created under any page type and it is not neces
|
|||
|
||||
Setting `parent_page_types` to an empty list is a good way of preventing a particular page type from being created in the editor interface.
|
||||
|
||||
```eval_rst
|
||||
.. _page_urls:
|
||||
```
|
||||
(page_urls)=
|
||||
### Page URLs
|
||||
|
||||
The most common method of retrieving page URLs is by using the `{% pageurl %}` template tag. Since it's called from a template, `pageurl` automatically includes the optimizations mentioned below. For more information, see [pageurl](pageurl_tag).
|
||||
|
|
@ -204,9 +189,7 @@ super().get_url_parts(*args, **kwargs)
|
|||
While you could pass only the `request` keyword argument, passing all arguments as-is ensures compatibility with any
|
||||
future changes to these method signatures.
|
||||
|
||||
```eval_rst
|
||||
For more information, please see :meth:`wagtail.core.models.Page.get_url_parts`.
|
||||
```
|
||||
For more information, please see {meth}`wagtail.core.models.Page.get_url_parts`.
|
||||
|
||||
#### Obtaining URLs for page instances
|
||||
|
||||
|
|
@ -215,15 +198,11 @@ The `Page.get_url(request)` method can be called whenever a page URL is needed.
|
|||
A common use case for `get_url(request)` is in any custom template tag your project may include for generating navigation menus. When writing such a custom template tag, ensure that it includes `takes_context=True` and use `context.get('request')` to safely pass the
|
||||
request or `None` if no request exists in the context.
|
||||
|
||||
```eval_rst
|
||||
For more information, please see :meth:`wagtail.core.models.Page.get_url`.
|
||||
```
|
||||
For more information, please see {meth}`wagtail.core.models.Page.get_url`.
|
||||
|
||||
In the event a full URL (including the protocol and domain) is needed, `Page.get_full_url(request)` can be used instead. Whenever possible, the optional `request` argument should be included to enable per-request caching of site-level URL information.
|
||||
|
||||
```eval_rst
|
||||
For more information, please see :meth:`wagtail.core.models.Page.get_full_url`.
|
||||
```
|
||||
For more information, please see {meth}`wagtail.core.models.Page.get_full_url`.
|
||||
|
||||
## Template rendering
|
||||
|
||||
|
|
@ -345,19 +324,17 @@ Wagtail can nest the content of other models within the page. This is useful for
|
|||
|
||||
Each inline model requires the following:
|
||||
|
||||
```eval_rst
|
||||
- It must inherit from :class:`wagtail.core.models.Orderable`
|
||||
- It must have a `ParentalKey` to the parent model
|
||||
- It must inherit from {class}`wagtail.core.models.Orderable`
|
||||
- It must have a `ParentalKey` to the parent model
|
||||
|
||||
.. note:: django-modelcluster and ParentalKey
|
||||
```{note} django-modelcluster and ParentalKey
|
||||
The model inlining feature is provided by [django-modelcluster](https://github.com/torchbox/django-modelcluster) and the `ParentalKey` field type must be imported from there:
|
||||
|
||||
The model inlining feature is provided by `django-modelcluster <https://github.com/torchbox/django-modelcluster>`_ and the ``ParentalKey`` field type must be imported from there:
|
||||
```python
|
||||
from modelcluster.fields import ParentalKey
|
||||
```
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from modelcluster.fields import ParentalKey
|
||||
|
||||
``ParentalKey`` is a subclass of Django's ``ForeignKey``, and takes the same arguments.
|
||||
`ParentalKey` is a subclass of Django's `ForeignKey`, and takes the same arguments.
|
||||
```
|
||||
|
||||
For example, the following inline model can be used to add related links (a list of name, url pairs) to the `BlogPage` model:
|
||||
|
|
@ -379,9 +356,7 @@ class BlogPageRelatedLink(Orderable):
|
|||
]
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
To add this to the admin interface, use the :class:`~wagtail.admin.edit_handlers.InlinePanel` edit panel class:
|
||||
```
|
||||
To add this to the admin interface, use the {class}`~wagtail.admin.edit_handlers.InlinePanel` edit panel class:
|
||||
|
||||
```python
|
||||
content_panels = [
|
||||
|
|
@ -397,9 +372,7 @@ The first argument must match the value of the `related_name` attribute of the `
|
|||
|
||||
Wagtail uses Django's [multi-table inheritance](https://docs.djangoproject.com/en/3.1/topics/db/models/#multi-table-inheritance) feature to allow multiple page models to be used in the same tree.
|
||||
|
||||
```eval_rst
|
||||
Each page is added to both Wagtail's builtin :class:`~wagtail.core.models.Page` model as well as its user-defined model (such as the `BlogPage` model created earlier).
|
||||
```
|
||||
Each page is added to both Wagtail's builtin {class}`~wagtail.core.models.Page` model as well as its user-defined model (such as the `BlogPage` model created earlier).
|
||||
|
||||
Pages can exist in Python code in two forms, an instance of `Page` or an instance of the page model.
|
||||
|
||||
|
|
@ -468,9 +441,7 @@ This is because `Page` enforces ordering QuerySets by path. Instead, you must ap
|
|||
news_items = NewsItemPage.objects.live().order_by('-publication_date')
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. _custom_page_managers:
|
||||
```
|
||||
(custom_page_managers)=
|
||||
### Custom Page managers
|
||||
|
||||
You can add a custom `Manager` to your `Page` class. Any custom Managers should inherit from `wagtail.core.models.PageManager`:
|
||||
|
|
|
|||
2
setup.py
2
setup.py
|
|
@ -79,7 +79,7 @@ documentation_extras = [
|
|||
"Sphinx>=1.5.2",
|
||||
"sphinx-autobuild>=0.6.0",
|
||||
"sphinx-wagtail-theme==5.0.4",
|
||||
"recommonmark>=0.7.1",
|
||||
"myst_parser==0.17.0",
|
||||
]
|
||||
|
||||
setup(
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue