Remove references to StreamFieldPanel and ChooserPanels from docs

docs/advanced_topics/customisation/page_editing_interface.rst

@@ -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"),
         ]
 

docs/getting_started/tutorial.md

@@ -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):

docs/reference/contrib/forms/customisation.rst

@@ -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'),

docs/reference/contrib/modeladmin/index.rst

@@ -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:

docs/reference/contrib/settings.rst

@@ -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

docs/reference/pages/panels.rst

@@ -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
-
-        This is the name of the class property used in your model definition.
+    .. versionchanged:: 2.17
 
-    .. 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.
+       ``StreamFieldPanel`` is no longer required for ``StreamField``.
 
-        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,30 +173,12 @@ 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:
-
-    .. code-block:: python
-
-      from wagtail.images.models import Image
-      from wagtail.images.edit_handlers import ImageChooserPanel
-
-
-      class BookPage(Page):
-          cover = models.ForeignKey(
-              'wagtailimages.Image',
-              null=True,
-              blank=True,
-              on_delete=models.SET_NULL,
-              related_name='+'
-          )
+    Deprecated; use ``FieldPanel`` instead.
 
-          content_panels = Page.content_panels + [
-              ImageChooserPanel('cover'),
-          ]
+    .. versionchanged:: 2.17
 
-    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.
+       ``ImageChooserPanel`` is no longer required to obtain an image chooser interface.
 
-    Displaying ``Image`` objects in a template requires the use of a template tag. See :ref:`image_tag`.
 
 FormSubmissionsPanel
 ~~~~~~~~~~~~~~~~~~~~
@@ -226,28 +207,12 @@ DocumentChooserPanel
 
 .. class:: DocumentChooserPanel(field_name)
 
-    For files in other formats, Wagtail provides a generic file store through the :class:`~wagtail.documents.models.Document` model:
-
-    .. code-block:: python
-
-      from wagtail.documents.models import Document
-      from wagtail.documents.edit_handlers import DocumentChooserPanel
-
+    Deprecated; use ``FieldPanel`` instead.
 
-      class BookPage(Page):
-          book_file = models.ForeignKey(
-              'wagtaildocs.Document',
-              null=True,
-              blank=True,
-              on_delete=models.SET_NULL,
-              related_name='+'
-          )
+    .. versionchanged:: 2.17
 
-          content_panels = Page.content_panels + [
-              DocumentChooserPanel('book_file'),
-          ]
+       ``DocumentChooserPanel`` is no longer required to obtain a document chooser interface.
 
-    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.
-
-    .. code-block:: python
-
-      from wagtail.snippets.edit_handlers import SnippetChooserPanel
+    Deprecated; use ``FieldPanel`` instead.
 
-      class BookPage(Page):
-          advert = models.ForeignKey(
-              'demo.Advert',
-              null=True,
-              blank=True,
-              on_delete=models.SET_NULL,
-              related_name='+'
-          )
+    .. versionchanged:: 2.17
 
-          content_panels = Page.content_panels + [
-              SnippetChooserPanel('advert'),
-          ]
+       ``SnippetChooserPanel`` is no longer required to obtain a document chooser interface.
 
-    See :ref:`snippets` for more information.
 
 Field Customisation
 -------------------

docs/topics/pages.md

@@ -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
 

docs/topics/snippets.rst

@@ -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):