kopia lustrzana https://github.com/wagtail/wagtail
Remove references to StreamFieldPanel and ChooserPanels from docs
Matt Westcott
Matt Westcott
rodzic
b8fd95ee86
commit
31139e8b24
docs
advanced_topics/customisation
getting_started
reference
contrib
pages
topics
|
|
@ -21,7 +21,7 @@ As standard, Wagtail organises panels for pages into three tabs: 'Content', 'Pro
|
|||
FieldPanel('body', classname="full"),
|
||||
]
|
||||
sidebar_content_panels = [
|
||||
SnippetChooserPanel('advert'),
|
||||
FieldPanel('advert'),
|
||||
InlinePanel('related_links', label="Related links"),
|
||||
]
|
||||
|
||||
|
|
|
|||
|
|
@ -466,14 +466,13 @@ Add a new `BlogPageGalleryImage` model to `models.py`:
|
|||
```python
|
||||
from django.db import models
|
||||
|
||||
# New imports added for ParentalKey, Orderable, InlinePanel, ImageChooserPanel
|
||||
# New imports added for ParentalKey, Orderable, InlinePanel
|
||||
|
||||
from modelcluster.fields import ParentalKey
|
||||
|
||||
from wagtail.core.models import Page, Orderable
|
||||
from wagtail.core.fields import RichTextField
|
||||
from wagtail.admin.edit_handlers import FieldPanel, InlinePanel
|
||||
from wagtail.images.edit_handlers import ImageChooserPanel
|
||||
from wagtail.search import index
|
||||
|
||||
|
||||
|
|
@ -506,7 +505,7 @@ class BlogPageGalleryImage(Orderable):
|
|||
caption = models.CharField(blank=True, max_length=250)
|
||||
|
||||
panels = [
|
||||
ImageChooserPanel('image'),
|
||||
FieldPanel('image'),
|
||||
FieldPanel('caption'),
|
||||
]
|
||||
```
|
||||
|
|
@ -519,7 +518,7 @@ Inheriting from `Orderable` adds a `sort_order` field to the model, to keep trac
|
|||
|
||||
The `ParentalKey` to `BlogPage` is what attaches the gallery images to a specific page. A `ParentalKey` works similarly to a `ForeignKey`, but also defines `BlogPageGalleryImage` as a "child" of the `BlogPage` model, so that it's treated as a fundamental part of the page in operations like submitting for moderation, and tracking revision history.
|
||||
|
||||
`image` is a `ForeignKey` to Wagtail's built-in `Image` model, where the images themselves are stored. This comes with a dedicated panel type, `ImageChooserPanel`, which provides a pop-up interface for choosing an existing image or uploading a new one. This way, we allow an image to exist in multiple galleries - effectively, we've created a many-to-many relationship between pages and images.
|
||||
`image` is a `ForeignKey` to Wagtail's built-in `Image` model, where the images themselves are stored. This appears in the page editor as a pop-up interface for choosing an existing image or uploading a new one. This way, we allow an image to exist in multiple galleries - effectively, we've created a many-to-many relationship between pages and images.
|
||||
|
||||
Specifying `on_delete=models.CASCADE` on the foreign key means that if the image is deleted from the system, the gallery entry is deleted as well. (In other situations, it might be appropriate to leave the entry in place - for example, if an "our staff" page included a list of people with headshots, and one of those photos was deleted, we'd rather leave the person in place on the page without a photo. In this case, we'd set the foreign key to `blank=True, null=True, on_delete=models.SET_NULL`.)
|
||||
|
||||
|
|
@ -629,7 +628,6 @@ from taggit.models import TaggedItemBase
|
|||
from wagtail.core.models import Page, Orderable
|
||||
from wagtail.core.fields import RichTextField
|
||||
from wagtail.admin.edit_handlers import FieldPanel, InlinePanel, MultiFieldPanel
|
||||
from wagtail.images.edit_handlers import ImageChooserPanel
|
||||
from wagtail.search import index
|
||||
|
||||
|
||||
|
|
@ -787,7 +785,7 @@ class BlogCategory(models.Model):
|
|||
|
||||
panels = [
|
||||
FieldPanel('name'),
|
||||
ImageChooserPanel('icon'),
|
||||
FieldPanel('icon'),
|
||||
]
|
||||
|
||||
def __str__(self):
|
||||
|
|
|
|||
|
|
@ -563,8 +563,7 @@ Finally, we add a URL param of `id` based on the ``form_submission`` if it exist
|
|||
.. code-block:: python
|
||||
|
||||
from django.shortcuts import redirect
|
||||
from wagtail.admin.edit_handlers import (
|
||||
FieldPanel, FieldRowPanel, InlinePanel, MultiFieldPanel, PageChooserPanel)
|
||||
from wagtail.admin.edit_handlers import FieldPanel, FieldRowPanel, InlinePanel, MultiFieldPanel
|
||||
from wagtail.contrib.forms.models import AbstractEmailForm
|
||||
|
||||
class FormPage(AbstractEmailForm):
|
||||
|
|
@ -594,7 +593,7 @@ Finally, we add a URL param of `id` based on the ``form_submission`` if it exist
|
|||
FieldPanel('intro', classname='full'),
|
||||
InlinePanel('form_fields'),
|
||||
FieldPanel('thank_you_text', classname='full'),
|
||||
PageChooserPanel('thank_you_page'),
|
||||
FieldPanel('thank_you_page'),
|
||||
MultiFieldPanel([
|
||||
FieldRowPanel([
|
||||
FieldPanel('from_address', classname='col6'),
|
||||
|
|
|
|||
|
|
@ -83,7 +83,6 @@ to create, view, and edit ``Book`` entries.
|
|||
|
||||
from django.db import models
|
||||
from wagtail.admin.edit_handlers import FieldPanel
|
||||
from wagtail.images.edit_handlers import ImageChooserPanel
|
||||
|
||||
class Book(models.Model):
|
||||
title = models.CharField(max_length=255)
|
||||
|
|
@ -98,15 +97,13 @@ to create, view, and edit ``Book`` entries.
|
|||
panels = [
|
||||
FieldPanel('title'),
|
||||
FieldPanel('author'),
|
||||
ImageChooserPanel('cover_photo')
|
||||
FieldPanel('cover_photo')
|
||||
]
|
||||
|
||||
.. tip::
|
||||
|
||||
You can specify ``FieldPanels`` like ``ImageChooserPanel``, ``PageChooserPanel``,
|
||||
and ``DocumentChooserPanel`` within the ``panels`` attribute of the model.
|
||||
This lets you use Wagtail-specific features in an otherwise traditional
|
||||
Django model.
|
||||
You can specify panels like ``MultiFieldPanel`` within the ``panels`` attribute of the model.
|
||||
This lets you use Wagtail-specific layouts in an otherwise traditional Django model.
|
||||
|
||||
|
||||
``wagtail_hooks.py`` in your app directory would look something like this:
|
||||
|
|
|
|||
|
|
@ -56,8 +56,8 @@ Settings use edit handlers much like the rest of Wagtail. Add a ``panels`` sett
|
|||
'wagtailcore.Page', null=True, on_delete=models.SET_NULL, related_name='+')
|
||||
|
||||
panels = [
|
||||
PageChooserPanel('donate_page'),
|
||||
PageChooserPanel('sign_up_page'),
|
||||
FieldPanel('donate_page'),
|
||||
FieldPanel('sign_up_page'),
|
||||
]
|
||||
|
||||
You can also customize the editor handlers :ref:`like you would do for Page model <customising_the_tabbed_interface>`
|
||||
|
|
@ -263,8 +263,8 @@ following shows how ``select_related`` can be set to improve efficiency:
|
|||
'wagtailcore.Page', null=True, on_delete=models.SET_NULL, related_name='+')
|
||||
|
||||
panels = [
|
||||
PageChooserPanel('donate_page'),
|
||||
PageChooserPanel('sign_up_page'),
|
||||
FieldPanel('donate_page'),
|
||||
FieldPanel('sign_up_page'),
|
||||
]
|
||||
|
||||
With these additions, the following template code will now trigger
|
||||
|
|
|
|||
|
|
@ -48,17 +48,12 @@ StreamFieldPanel
|
|||
|
||||
.. class:: StreamFieldPanel(field_name, classname=None, widget=None)
|
||||
|
||||
This is the panel used for Wagtail's StreamField type (see :ref:`streamfield`).
|
||||
Deprecated; use ``FieldPanel`` instead.
|
||||
|
||||
.. attribute:: FieldPanel.field_name
|
||||
.. versionchanged:: 2.17
|
||||
|
||||
This is the name of the class property used in your model definition.
|
||||
``StreamFieldPanel`` is no longer required for ``StreamField``.
|
||||
|
||||
.. attribute:: FieldPanel.classname (optional)
|
||||
|
||||
This is a string of optional CSS classes given to the panel which are used in formatting and scripted interactivity. By default, panels are formatted as inset fields.
|
||||
|
||||
The CSS class ``full`` can be used to format the panel so it covers the full width of the Wagtail page editor.
|
||||
|
||||
MultiFieldPanel
|
||||
~~~~~~~~~~~~~~~
|
||||
|
|
@ -166,6 +161,10 @@ PageChooserPanel
|
|||
|
||||
Passing ``can_choose_root=True`` will allow the editor to choose the tree root as a page. Normally this would be undesirable, since the tree root is never a usable page, but in some specialised cases it may be appropriate; for example, a page with an automatic "related articles" feed could use a PageChooserPanel to select which subsection articles will be taken from, with the root corresponding to 'everywhere'.
|
||||
|
||||
.. versionchanged:: 2.17
|
||||
|
||||
``FieldPanel`` now also provides a page chooser interface for foreign keys to page models. ``PageChooserPanel`` is only required when specifying the ``page_type`` or ``can_choose_root`` parameters.
|
||||
|
||||
|
||||
ImageChooserPanel
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -174,31 +173,13 @@ ImageChooserPanel
|
|||
|
||||
.. class:: ImageChooserPanel(field_name)
|
||||
|
||||
Wagtail includes a unified image library, which you can access in your models through the :class:`~wagtail.images.models.Image` model and the ``ImageChooserPanel`` chooser. Here's how:
|
||||
Deprecated; use ``FieldPanel`` instead.
|
||||
|
||||
.. code-block:: python
|
||||
.. versionchanged:: 2.17
|
||||
|
||||
from wagtail.images.models import Image
|
||||
from wagtail.images.edit_handlers import ImageChooserPanel
|
||||
``ImageChooserPanel`` is no longer required to obtain an image chooser interface.
|
||||
|
||||
|
||||
class BookPage(Page):
|
||||
cover = models.ForeignKey(
|
||||
'wagtailimages.Image',
|
||||
null=True,
|
||||
blank=True,
|
||||
on_delete=models.SET_NULL,
|
||||
related_name='+'
|
||||
)
|
||||
|
||||
content_panels = Page.content_panels + [
|
||||
ImageChooserPanel('cover'),
|
||||
]
|
||||
|
||||
Django's default behaviour is to "cascade" deletions through a ForeignKey relationship, which may not be what you want. This is why the :attr:`~django.db.models.Field.null`, :attr:`~django.db.models.Field.blank`, and :attr:`~django.db.models.ForeignKey.on_delete` parameters should be set to allow for an empty field. ``ImageChooserPanel`` takes only one argument: the name of the field.
|
||||
|
||||
Displaying ``Image`` objects in a template requires the use of a template tag. See :ref:`image_tag`.
|
||||
|
||||
FormSubmissionsPanel
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
@ -226,29 +207,13 @@ DocumentChooserPanel
|
|||
|
||||
.. class:: DocumentChooserPanel(field_name)
|
||||
|
||||
For files in other formats, Wagtail provides a generic file store through the :class:`~wagtail.documents.models.Document` model:
|
||||
Deprecated; use ``FieldPanel`` instead.
|
||||
|
||||
.. code-block:: python
|
||||
.. versionchanged:: 2.17
|
||||
|
||||
from wagtail.documents.models import Document
|
||||
from wagtail.documents.edit_handlers import DocumentChooserPanel
|
||||
``DocumentChooserPanel`` is no longer required to obtain a document chooser interface.
|
||||
|
||||
|
||||
class BookPage(Page):
|
||||
book_file = models.ForeignKey(
|
||||
'wagtaildocs.Document',
|
||||
null=True,
|
||||
blank=True,
|
||||
on_delete=models.SET_NULL,
|
||||
related_name='+'
|
||||
)
|
||||
|
||||
content_panels = Page.content_panels + [
|
||||
DocumentChooserPanel('book_file'),
|
||||
]
|
||||
|
||||
As with images, Wagtail documents should also have the appropriate extra parameters to prevent cascade deletions across a ForeignKey relationship. ``DocumentChooserPanel`` takes only one argument: the name of the field.
|
||||
|
||||
SnippetChooserPanel
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
@ -256,26 +221,12 @@ SnippetChooserPanel
|
|||
|
||||
.. class:: SnippetChooserPanel(field_name, snippet_type=None)
|
||||
|
||||
Snippets are vanilla Django models you create yourself without a Wagtail-provided base class. A chooser, ``SnippetChooserPanel``, is provided which takes the field name as an argument.
|
||||
Deprecated; use ``FieldPanel`` instead.
|
||||
|
||||
.. code-block:: python
|
||||
.. versionchanged:: 2.17
|
||||
|
||||
from wagtail.snippets.edit_handlers import SnippetChooserPanel
|
||||
``SnippetChooserPanel`` is no longer required to obtain a document chooser interface.
|
||||
|
||||
class BookPage(Page):
|
||||
advert = models.ForeignKey(
|
||||
'demo.Advert',
|
||||
null=True,
|
||||
blank=True,
|
||||
on_delete=models.SET_NULL,
|
||||
related_name='+'
|
||||
)
|
||||
|
||||
content_panels = Page.content_panels + [
|
||||
SnippetChooserPanel('advert'),
|
||||
]
|
||||
|
||||
See :ref:`snippets` for more information.
|
||||
|
||||
Field Customisation
|
||||
-------------------
|
||||
|
|
|
|||
|
|
@ -27,7 +27,6 @@ from modelcluster.fields import ParentalKey
|
|||
from wagtail.core.models import Page, Orderable
|
||||
from wagtail.core.fields import RichTextField
|
||||
from wagtail.admin.edit_handlers import FieldPanel, MultiFieldPanel, InlinePanel
|
||||
from wagtail.images.edit_handlers import ImageChooserPanel
|
||||
from wagtail.search import index
|
||||
|
||||
|
||||
|
|
@ -64,7 +63,7 @@ class BlogPage(Page):
|
|||
|
||||
promote_panels = [
|
||||
MultiFieldPanel(Page.promote_panels, "Common page configuration"),
|
||||
ImageChooserPanel('feed_image'),
|
||||
FieldPanel('feed_image'),
|
||||
]
|
||||
|
||||
|
||||
|
|
@ -134,13 +133,18 @@ Here's a summary of the `EditHandler` classes that Wagtail provides out of the b
|
|||
|
||||
**Basic**
|
||||
|
||||
These allow editing of model fields. The `FieldPanel` class will choose the correct widget based on the type of the field, though `StreamField` fields need to use a specialised panel class.
|
||||
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.StreamFieldPanel`
|
||||
- :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``.
|
||||
```
|
||||
|
||||
|
||||
**Structural**
|
||||
|
||||
These are used for structuring fields in the interface.
|
||||
|
|
@ -151,23 +155,6 @@ These are used for structuring fields in the interface.
|
|||
- :class:`~wagtail.admin.edit_handlers.FieldRowPanel`
|
||||
```
|
||||
|
||||
**Chooser**
|
||||
|
||||
`ForeignKey` fields to certain models can use one of the below `ChooserPanel` classes. These add a nice modal chooser interface, and the image/document choosers also allow uploading new files without leaving the page editor.
|
||||
|
||||
```eval_rst
|
||||
- :class:`~wagtail.admin.edit_handlers.PageChooserPanel`
|
||||
- :class:`~wagtail.images.edit_handlers.ImageChooserPanel`
|
||||
- :class:`~wagtail.documents.edit_handlers.DocumentChooserPanel`
|
||||
- :class:`~wagtail.snippets.edit_handlers.SnippetChooserPanel`
|
||||
|
||||
.. note::
|
||||
|
||||
In order to use one of these choosers, the model being linked to must either be a page, image, document or snippet.
|
||||
|
||||
Linking to any other model type is currently unsupported, you will need to use ``FieldPanel`` which will create a dropdown box.
|
||||
```
|
||||
|
||||
|
||||
#### Customising the page editor interface
|
||||
|
||||
|
|
|
|||
|
|
@ -97,11 +97,10 @@ Then, in your own page templates, you can include your snippet template tag with
|
|||
Binding Pages to Snippets
|
||||
-------------------------
|
||||
|
||||
In the above example, the list of adverts is a fixed list that is displayed via the custom template tag independent of any other content on the page. This might be what you want for a common panel in a sidebar, but, in another scenario, you might wish to display just one specific instance of a snippet on a particular page. This can be accomplished by defining a foreign key to the snippet model within your page model and adding a ``SnippetChooserPanel`` to the page's ``content_panels`` list. For example, if you wanted to display a specific advert on a ``BookPage`` instance:
|
||||
In the above example, the list of adverts is a fixed list that is displayed via the custom template tag independent of any other content on the page. This might be what you want for a common panel in a sidebar, but, in another scenario, you might wish to display just one specific instance of a snippet on a particular page. This can be accomplished by defining a foreign key to the snippet model within your page model and adding a ``FieldPanel`` to the page's ``content_panels`` list. For example, if you wanted to display a specific advert on a ``BookPage`` instance:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.snippets.edit_handlers import SnippetChooserPanel
|
||||
# ...
|
||||
class BookPage(Page):
|
||||
advert = models.ForeignKey(
|
||||
|
|
@ -113,14 +112,14 @@ In the above example, the list of adverts is a fixed list that is displayed via
|
|||
)
|
||||
|
||||
content_panels = Page.content_panels + [
|
||||
SnippetChooserPanel('advert'),
|
||||
FieldPanel('advert'),
|
||||
# ...
|
||||
]
|
||||
|
||||
|
||||
The snippet could then be accessed within your template as ``page.advert``.
|
||||
|
||||
To attach multiple adverts to a page, the ``SnippetChooserPanel`` can be placed on an inline child object of ``BookPage`` rather than on ``BookPage`` itself. Here, this child model is named ``BookPageAdvertPlacement`` (so called because there is one such object for each time that an advert is placed on a BookPage):
|
||||
To attach multiple adverts to a page, the ``FieldPanel`` can be placed on an inline child object of ``BookPage`` rather than on ``BookPage`` itself. Here, this child model is named ``BookPageAdvertPlacement`` (so called because there is one such object for each time that an advert is placed on a BookPage):
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
|
@ -128,7 +127,6 @@ To attach multiple adverts to a page, the ``SnippetChooserPanel`` can be placed
|
|||
from django.db import models
|
||||
|
||||
from wagtail.core.models import Page, Orderable
|
||||
from wagtail.snippets.edit_handlers import SnippetChooserPanel
|
||||
|
||||
from modelcluster.fields import ParentalKey
|
||||
|
||||
|
|
@ -143,7 +141,7 @@ To attach multiple adverts to a page, the ``SnippetChooserPanel`` can be placed
|
|||
verbose_name_plural = "advert placements"
|
||||
|
||||
panels = [
|
||||
SnippetChooserPanel('advert'),
|
||||
FieldPanel('advert'),
|
||||
]
|
||||
|
||||
def __str__(self):
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue