From 06ea3fb3015547e9e4b3b63004539fc6991c5851 Mon Sep 17 00:00:00 2001 From: Matt Westcott Date: Mon, 18 Sep 2017 21:05:19 +0100 Subject: [PATCH] Clarify interaction between StreamField's blank property and StreamBlock's required property --- docs/releases/1.12.rst | 2 ++ docs/topics/streamfield.rst | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/releases/1.12.rst b/docs/releases/1.12.rst index b5a27364f..eaf04ebfe 100644 --- a/docs/releases/1.12.rst +++ b/docs/releases/1.12.rst @@ -62,6 +62,8 @@ StreamField now defaults to ``blank=False`` StreamField now respects the ``blank`` field setting; when this is false, at least one block must be supplied for the field to pass validation. To match the behaviour of other model fields, ``blank`` defaults to ``False``; if you wish to allow a StreamField to be left empty, you must now add ``blank=True`` to the field. +When passing an explicit ``StreamBlock`` as the top-level block of a StreamField definition, note that the StreamField's ``blank`` keyword argument always takes precedence over the block's ``required`` property, including when it is left as the default value of ``blank=False``. Consequently, setting ``required=False`` on a top-level ``StreamBlock`` has no effect. + Old configuration settings for embeds are deprecated ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/streamfield.rst b/docs/topics/streamfield.rst index 00de5b3a1..ff72e1ed6 100644 --- a/docs/topics/streamfield.rst +++ b/docs/topics/streamfield.rst @@ -47,6 +47,8 @@ The parameter to ``StreamField`` is a list of ``(name, block_type)`` tuples. 'na This defines the set of available block types that can be used within this field. The author of the page is free to use these blocks as many times as desired, in any order. +``StreamField`` also accepts an optional keyword argument ``blank``, defaulting to false; when this is false, at least one block must be provided for the field to be considered valid. + Basic block types ----------------- @@ -446,7 +448,7 @@ Since ``StreamField`` accepts an instance of ``StreamBlock`` as a parameter, in ``StreamBlock`` accepts the following options as either keyword arguments or ``Meta`` properties: ``required`` (default: True) - If true, at least one sub-block must be supplied. + If true, at least one sub-block must be supplied. This is ignored when using the ``StreamBlock`` as the top-level block of a StreamField; in this case the StreamField's ``blank`` property is respected instead. ``min_num`` Minimum number of sub-blocks that the stream must have.