Add use_json_field=True to all StreamField examples (#8359)

This argument should be used on all new StreamFields created under Wagtail 3. It does add some clutter to the examples, but only using it in select cases would create more confusion...

docs/advanced_topics/boundblocks_and_values.rst

@@ -26,7 +26,7 @@ This gives us a block that behaves as an ordinary text field, but wraps its outp
             # ...
             ('heading', HeadingBlock()),
             # ...
-        ])
+        ], use_json_field=True)
 
 .. code-block:: html+django
 

docs/reference/streamfield/blocks.rst

@@ -381,7 +381,7 @@ Structural block types
                ('photo', ImageChooserBlock(required=False)),
                ('biography', blocks.RichTextBlock()),
            ], icon='user')),
-       ])
+       ], use_json_field=True)
 
 
    Alternatively, StructBlock can be subclassed to specify a reusable set of sub-blocks:
@@ -409,7 +409,7 @@ Structural block types
            ('paragraph', blocks.RichTextBlock()),
            ('image', ImageChooserBlock()),
            ('person', PersonBlock()),
-       ])
+       ], use_json_field=True)
 
    The following additional options are available as either keyword arguments or Meta class attributes:
 
@@ -429,7 +429,7 @@ Structural block types
        body = StreamField([
            # ...
            ('ingredients_list', blocks.ListBlock(blocks.CharBlock(label="Ingredient"))),
-       ])
+       ], use_json_field=True)
 
 
    Any block type is valid as the sub-block type, including structural types:
@@ -442,7 +442,7 @@ Structural block types
                ('ingredient', blocks.CharBlock()),
                ('amount', blocks.CharBlock(required=False)),
            ]))),
-       ])
+       ], use_json_field=True)
 
    The following additional options are available as either keyword arguments or Meta class attributes:
 
@@ -471,7 +471,7 @@ Structural block types
                ],
                icon='cogs'
            )),
-       ])
+       ], use_json_field=True)
 
 
    As with StructBlock, the list of sub-blocks can also be provided as a subclass of StreamBlock:
@@ -496,7 +496,10 @@ Structural block types
    .. code-block:: python
 
        class HomePage(Page):
-           carousel = StreamField(CarouselBlock(max_num=10, block_counts={'video': {'max_num': 2}}))
+           carousel = StreamField(
+               CarouselBlock(max_num=10, block_counts={'video': {'max_num': 2}}),
+               use_json_field=True
+            )
 
    ``StreamBlock`` accepts the following additional options as either keyword arguments or ``Meta`` properties:
 
@@ -516,7 +519,7 @@ Structural block types
                ('hashtag', blocks.CharBlock()),
                ('post_date', blocks.DateBlock()),
            ], form_classname='event-promotions')),
-       ])
+       ], use_json_field=True)
 
     .. code-block:: python
         :emphasize-lines: 6

docs/topics/streamfield.rst

@@ -22,7 +22,7 @@ Using StreamField
     from wagtail.models import Page
     from wagtail.fields import StreamField
     from wagtail import blocks
-    from wagtail.admin.panels import FieldPanel, StreamFieldPanel
+    from wagtail.admin.panels import FieldPanel
     from wagtail.images.blocks import ImageChooserBlock
 
     class BlogPage(Page):
@@ -32,15 +32,14 @@ Using StreamField
             ('heading', blocks.CharBlock(form_classname="full title")),
             ('paragraph', blocks.RichTextBlock()),
             ('image', ImageChooserBlock()),
-        ])
+        ], use_json_field=True)
 
         content_panels = Page.content_panels + [
             FieldPanel('author'),
             FieldPanel('date'),
-            StreamFieldPanel('body'),
+            FieldPanel('body'),
         ]
 
-
 In this example, the body field of ``BlogPage`` is defined as a ``StreamField`` where authors can compose content from three different block types: headings, paragraphs, and images, which can be used and repeated in any order. The block types available to authors are defined as a list of ``(name, block_type)`` tuples: 'name' is used to identify the block type within templates, and should follow the standard Python conventions for variable names: lower-case and underscores, no spaces.
 
 You can find the complete list of available block types in the :ref:`StreamField block reference <streamfield_block_reference>`.
@@ -48,6 +47,10 @@ You can find the complete list of available block types in the :ref:`StreamField
 .. note::
    StreamField is not a direct replacement for other field types such as RichTextField. If you need to migrate an existing field to StreamField, refer to :ref:`streamfield_migrating_richtext`.
 
+.. versionchanged:: 3.0
+
+  The ``use_json_field=True`` argument was added. This indicates that the database's native JSONField support should be used for this field, and is a temporary measure to assist in migrating StreamFields created on earlier Wagtail versions; it will become the default in a future release.
+
 
 .. _streamfield_template_rendering:
 
@@ -130,7 +133,7 @@ StructBlock
         ('heading', blocks.CharBlock(form_classname="full title")),
         ('paragraph', blocks.RichTextBlock()),
         ('image', ImageChooserBlock()),
-    ])
+    ], use_json_field=True)
 
 When reading back the content of a StreamField (such as when rendering a template), the value of a StructBlock is a dict-like object with keys corresponding to the block names given in the definition:
 
@@ -173,7 +176,7 @@ Placing a StructBlock's list of child blocks inside a ``StreamField`` definition
         ('heading', blocks.CharBlock(form_classname="full title")),
         ('paragraph', blocks.RichTextBlock()),
         ('image', ImageChooserBlock()),
-    ])
+    ], use_json_field=True)
 
 
 Block icons
@@ -194,7 +197,7 @@ In the menu that content authors use to add new blocks to a StreamField, each bl
         ('heading', blocks.CharBlock(form_classname="full title")),
         ('paragraph', blocks.RichTextBlock()),
         ('image', ImageChooserBlock()),
-    ])
+    ], use_json_field=True)
 
 .. code-block:: python
    :emphasize-lines: 7-8
@@ -224,7 +227,7 @@ ListBlock
         ('heading', blocks.CharBlock(form_classname="full title")),
         ('paragraph', blocks.RichTextBlock()),
         ('image', ImageChooserBlock()),
-    ])
+    ], use_json_field=True)
 
 When reading back the content of a StreamField (such as when rendering a template), the value of a ListBlock is a list of child values:
 
@@ -261,7 +264,7 @@ StreamBlock
         ('heading', blocks.CharBlock(form_classname="full title")),
         ('paragraph', blocks.RichTextBlock()),
         ('image', ImageChooserBlock()),
-    ])
+    ], use_json_field=True)
 
 ``StreamBlock`` can also be subclassed in the same way as ``StructBlock``, with the child blocks being specified as attributes on the class:
 
@@ -285,7 +288,7 @@ A StreamBlock subclass defined in this way can also be passed to a ``StreamField
 
 
     class BlogPage(Page):
-        body = StreamField(CommonContentBlock())
+        body = StreamField(CommonContentBlock(), use_json_field=True)
 
 
 When reading back the content of a StreamField, the value of a StreamBlock is a sequence of block objects with ``block_type`` and ``value`` properties, just like the top-level value of the StreamField itself.
@@ -322,7 +325,7 @@ By default, a StreamField can contain an unlimited number of blocks. The ``min_n
         ('heading', blocks.CharBlock(form_classname="full title")),
         ('paragraph', blocks.RichTextBlock()),
         ('image', ImageChooserBlock()),
-    ], min_num=2, max_num=5)
+    ], min_num=2, max_num=5, use_json_field=True)
 
 Or equivalently:
 
@@ -348,7 +351,7 @@ The ``block_counts`` option can be used to set a minimum or maximum count for sp
         ('image', ImageChooserBlock()),
     ], block_counts={
         'heading': {'min_num': 1, 'max_num': 3},
-    })
+    }, use_json_field=True)
 
 Or equivalently:
 
@@ -545,7 +548,7 @@ A StreamField's value behaves as a list, and blocks can be inserted, overwritten
 Migrating RichTextFields to StreamField
 ---------------------------------------
 
-If you change an existing RichTextField to a StreamField, the database migration will complete with no errors, since both fields use a text column within the database. However, StreamField uses a JSON representation for its data, so the existing text requires an extra conversion step in order to become accessible again. For this to work, the StreamField needs to include a RichTextBlock as one of the available block types. (When updating the model, don't forget to change ``FieldPanel`` to ``StreamFieldPanel`` too.) Create the migration as normal using ``./manage.py makemigrations``, then edit it as follows (in this example, the 'body' field of the ``demo.BlogPage`` model is being converted to a StreamField with a RichTextBlock named ``rich_text``):
+If you change an existing RichTextField to a StreamField, the database migration will complete with no errors, since both fields use a text column within the database. However, StreamField uses a JSON representation for its data, so the existing text requires an extra conversion step in order to become accessible again. For this to work, the StreamField needs to include a RichTextBlock as one of the available block types. Create the migration as normal using ``./manage.py makemigrations``, then edit it as follows (in this example, the 'body' field of the ``demo.BlogPage`` model is being converted to a StreamField with a RichTextBlock named ``rich_text``):
 
 .. note::
     This migration cannot be used if the StreamField has the ``use_json_field`` argument set to ``True``. To migrate, set the ``use_json_field`` argument to ``False`` first, migrate the data, then set it back to ``True``.