Browse Source

Add note to clarify that blocks are not interchangeable with model fields

Prompted by https://stackoverflow.com/questions/76973112/unknown-fields-specified-for-a-page-model-in-wagtail-at-content-panels/76973226?noredirect=1#comment135693718_76973226 and similar misconceptions people have made in the past.
Matt Westcott 1 year ago
parent
commit
151a386ff5
2 changed files with 9 additions and 0 deletions
  1. 4 0
      docs/reference/streamfield/blocks.md
  2. 5 0
      docs/topics/streamfield.md

+ 4 - 0
docs/reference/streamfield/blocks.md

@@ -4,6 +4,10 @@
 
 This document details the block types provided by Wagtail for use in [StreamField](streamfield), and how they can be combined into new block types.
 
+```{note}
+   While block definitions look similar to model fields, they are not the same thing. Blocks are only valid within a StreamField - using them in place of a model field will not work.
+```
+
 ```{eval-rst}
 .. class:: wagtail.fields.StreamField(blocks, use_json_field=None, blank=False, min_num=None, max_num=None, block_counts=None, collapsed=False)
 

+ 5 - 0
docs/topics/streamfield.md

@@ -45,6 +45,11 @@ You can find the complete list of available block types in the [](streamfield_bl
    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 [](streamfield_migrating_richtext).
 ```
 
+```{note}
+   While block definitions look similar to model fields, they are not the same thing. Blocks are only valid within a StreamField - using them in place of a model field will not work.
+```
+
+
 (streamfield_template_rendering)=
 
 ## Template rendering