Add Block.get_description() to be used in block preview

wagtail/blocks/base.py

@@ -293,6 +293,9 @@ class Block(metaclass=BaseBlock):
             return self.normalize(self.meta.preview_value)
         return self.get_default()
 
+    def get_description(self):
+        return getattr(self.meta, "description", "")
+
     def get_api_representation(self, value, context=None):
         """
         Can be used to customise the API response and defaults to the value returned by get_prep_value.

wagtail/blocks/field_block.py

@@ -81,6 +81,9 @@ class FieldBlock(Block):
             self.field.prepare_value(self.value_for_form(value))
         )
 
+    def get_description(self):
+        return super().get_description() or self.field.help_text or ""
+
     class Meta:
         # No icon specified here, because that depends on the purpose that the
         # block is being used for. Feel encouraged to specify an icon in your
@@ -110,6 +113,7 @@ class FieldBlockAdapter(Adapter):
 
         meta = {
             "label": block.label,
+            "description": block.get_description(),
             "required": block.required,
             "icon": block.meta.icon,
             "blockDefId": block.definition_prefix,

wagtail/blocks/list_block.py

@@ -449,6 +449,7 @@ class ListBlockAdapter(Adapter):
     def js_args(self, block):
         meta = {
             "label": block.label,
+            "description": block.get_description(),
             "icon": block.meta.icon,
             "blockDefId": block.definition_prefix,
             "classname": block.meta.form_classname,

wagtail/blocks/static_block.py

@@ -58,6 +58,7 @@ class StaticBlockAdapter(Adapter):
                 text_or_html: admin_text,
                 "icon": block.meta.icon,
                 "label": block.label,
+                "description": block.get_description(),
                 "blockDefId": block.definition_prefix,
             },
         ]

wagtail/blocks/stream_block.py

@@ -826,6 +826,7 @@ class StreamBlockAdapter(Adapter):
     def js_args(self, block):
         meta = {
             "label": block.label,
+            "description": block.get_description(),
             "required": block.required,
             "icon": block.meta.icon,
             "blockDefId": block.definition_prefix,

wagtail/blocks/struct_block.py

@@ -360,6 +360,9 @@ class BaseStructBlock(Block):
         )
         return mark_safe(render_to_string(self.meta.form_template, context))
 
+    def get_description(self):
+        return super().get_description() or getattr(self.meta, "help_text", "")
+
     def get_form_context(self, value, prefix="", errors=None):
         return {
             "children": collections.OrderedDict(
@@ -401,6 +404,7 @@ class StructBlockAdapter(Adapter):
     def js_args(self, block):
         meta = {
             "label": block.label,
+            "description": block.get_description(),
             "required": block.required,
             "icon": block.meta.icon,
             "blockDefId": block.definition_prefix,

wagtail/contrib/table_block/tests.py

@@ -558,7 +558,7 @@ class TestTableBlockForm(WagtailTestUtils, SimpleTestCase):
         self.assertIs(block_3_opts["allowEmpty"], False)
 
     def test_adapt(self):
-        block = TableBlock()
+        block = TableBlock(description="A table to display data.")
 
         block.set_name("test_tableblock")
         js_args = FieldBlockAdapter().js_args(block)
@@ -569,6 +569,7 @@ class TestTableBlockForm(WagtailTestUtils, SimpleTestCase):
             js_args[2],
             {
                 "label": "Test tableblock",
+                "description": "A table to display data.",
                 "required": True,
                 "icon": "table",
                 "blockDefId": block.definition_prefix,

wagtail/contrib/typed_table_block/blocks.py

@@ -332,6 +332,7 @@ class TypedTableBlockAdapter(Adapter):
     def js_args(self, block):
         meta = {
             "label": block.label,
+            "description": block.get_description(),
             "required": block.required,
             "icon": block.meta.icon,
             "blockDefId": block.definition_prefix,

wagtail/contrib/typed_table_block/tests.py

@@ -225,7 +225,7 @@ class TestTableBlock(TestCase):
         self.assertIn("<td>FR</td>", html)
 
     def test_adapt(self):
-        block = TypedTableBlock()
+        block = TypedTableBlock(description="A table of countries and their food")
 
         block.set_name("test_typedtableblock")
         js_args = TypedTableBlockAdapter().js_args(block)
@@ -235,6 +235,7 @@ class TestTableBlock(TestCase):
             js_args[-1],
             {
                 "label": "Test typedtableblock",
+                "description": "A table of countries and their food",
                 "required": False,
                 "icon": "table",
                 "blockDefId": block.definition_prefix,

wagtail/snippets/tests/test_snippets.py

@@ -5524,7 +5524,11 @@ class TestSnippetChooserBlock(TestCase):
         self.assertEqual(block.to_python(test_advert.id), test_advert)
 
     def test_adapt(self):
-        block = SnippetChooserBlock(Advert, help_text="pick an advert, any advert")
+        block = SnippetChooserBlock(
+            Advert,
+            help_text="pick an advert, any advert",
+            description="An advert to be displayed on the sidebar.",
+        )
 
         block.set_name("test_snippetchooserblock")
         js_args = FieldBlockAdapter().js_args(block)
@@ -5536,6 +5540,7 @@ class TestSnippetChooserBlock(TestCase):
             js_args[2],
             {
                 "label": "Test snippetchooserblock",
+                "description": "An advert to be displayed on the sidebar.",
                 "required": True,
                 "icon": "snippet",
                 "blockDefId": block.definition_prefix,
@@ -5832,7 +5837,9 @@ class TestSnippetChooserBlockWithCustomPrimaryKey(TestCase):
 
     def test_adapt(self):
         block = SnippetChooserBlock(
-            AdvertWithCustomPrimaryKey, help_text="pick an advert, any advert"
+            AdvertWithCustomPrimaryKey,
+            help_text="pick an advert, any advert",
+            description="An advert to be displayed on the footer.",
         )
 
         block.set_name("test_snippetchooserblock")
@@ -5845,6 +5852,7 @@ class TestSnippetChooserBlockWithCustomPrimaryKey(TestCase):
             js_args[2],
             {
                 "label": "Test snippetchooserblock",
+                "description": "An advert to be displayed on the footer.",
                 "required": True,
                 "icon": "snippet",
                 "blockDefId": block.definition_prefix,

wagtail/tests/test_blocks.py

@@ -95,6 +95,7 @@ class TestFieldBlock(WagtailTestUtils, SimpleTestCase):
             js_args[2],
             {
                 "label": "Test block",
+                "description": "Some helpful text",
                 "helpText": "Some helpful text",
                 "required": True,
                 "icon": "placeholder",
@@ -185,7 +186,7 @@ class TestFieldBlock(WagtailTestUtils, SimpleTestCase):
                 )
             )
 
-        block = ChoiceBlock()
+        block = ChoiceBlock(description="A selection of two choices")
 
         block.set_name("test_choiceblock")
         js_args = FieldBlockAdapter().js_args(block)
@@ -203,6 +204,7 @@ class TestFieldBlock(WagtailTestUtils, SimpleTestCase):
             js_args[2],
             {
                 "label": "Test choiceblock",
+                "description": "A selection of two choices",
                 "required": True,
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
@@ -615,6 +617,7 @@ class TestRichTextBlock(TestCase):
                 "classname": "w-field w-field--char_field w-field--custom_rich_text_area",
                 "icon": "pilcrow",
                 "label": "Test richtextblock",
+                "description": "",
                 "blockDefId": block.definition_prefix,
                 "required": True,
                 "showAddCommentButton": True,
@@ -636,6 +639,7 @@ class TestRichTextBlock(TestCase):
             js_args[2],
             {
                 "label": "Test richtextblock",
+                "description": "",
                 "required": True,
                 "icon": "pilcrow",
                 "blockDefId": block.definition_prefix,
@@ -659,6 +663,7 @@ class TestRichTextBlock(TestCase):
             js_args[2],
             {
                 "label": "Test richtextblock",
+                "description": "",
                 "required": True,
                 "icon": "pilcrow",
                 "blockDefId": block.definition_prefix,
@@ -775,6 +780,7 @@ class TestChoiceBlock(WagtailTestUtils, SimpleTestCase):
             js_args[2],
             {
                 "label": "Test choiceblock",
+                "description": "",
                 "required": True,
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
@@ -1177,6 +1183,7 @@ class TestMultipleChoiceBlock(WagtailTestUtils, SimpleTestCase):
             js_args[2],
             {
                 "label": "Test choiceblock",
+                "description": "",
                 "required": True,
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
@@ -1614,6 +1621,7 @@ class TestRawHTMLBlock(unittest.TestCase):
             js_args[2],
             {
                 "label": "Test rawhtmlblock",
+                "description": "",
                 "required": True,
                 "icon": "code",
                 "blockDefId": block.definition_prefix,
@@ -1957,6 +1965,7 @@ class TestStructBlock(SimpleTestCase):
             js_args[2],
             {
                 "label": "Test structblock",
+                "description": "",
                 "required": False,
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
@@ -1987,6 +1996,7 @@ class TestStructBlock(SimpleTestCase):
             js_args[2],
             {
                 "label": "Test structblock",
+                "description": "",
                 "required": False,
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
@@ -2012,6 +2022,7 @@ class TestStructBlock(SimpleTestCase):
             js_args[2],
             {
                 "label": "Test structblock",
+                "description": "",
                 "required": False,
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
@@ -2046,6 +2057,7 @@ class TestStructBlock(SimpleTestCase):
             js_args[2],
             {
                 "label": "Test structblock",
+                "description": "Self-promotion is encouraged",
                 "required": False,
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
@@ -2072,6 +2084,7 @@ class TestStructBlock(SimpleTestCase):
             js_args[2],
             {
                 "label": "Test structblock",
+                "description": "Self-promotion is encouraged",
                 "required": False,
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
@@ -2702,6 +2715,7 @@ class TestListBlock(WagtailTestUtils, SimpleTestCase):
             js_args[3],
             {
                 "label": "Test listblock",
+                "description": "",
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "classname": None,
@@ -2733,6 +2747,7 @@ class TestListBlock(WagtailTestUtils, SimpleTestCase):
             js_args[3],
             {
                 "label": "Test listblock",
+                "description": "",
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "classname": None,
@@ -2908,6 +2923,7 @@ class TestListBlock(WagtailTestUtils, SimpleTestCase):
             js_args[3],
             {
                 "label": "Test listblock",
+                "description": "",
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "classname": "special-list-class",
@@ -2942,6 +2958,7 @@ class TestListBlock(WagtailTestUtils, SimpleTestCase):
             js_args[3],
             {
                 "label": "Test listblock",
+                "description": "",
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "classname": "custom-list-class",
@@ -3580,6 +3597,7 @@ class TestStreamBlock(WagtailTestUtils, SimpleTestCase):
             js_args[3],
             {
                 "label": "Test streamblock",
+                "description": "",
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "classname": None,
@@ -4307,6 +4325,7 @@ class TestStreamBlock(WagtailTestUtils, SimpleTestCase):
             js_args[3],
             {
                 "label": "Test streamblock",
+                "description": "",
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "minNum": None,
@@ -4410,6 +4429,7 @@ class TestStreamBlock(WagtailTestUtils, SimpleTestCase):
             js_args[3],
             {
                 "label": "Test streamblock",
+                "description": "",
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "minNum": None,
@@ -4742,7 +4762,9 @@ class TestPageChooserBlock(TestCase):
     def test_adapt(self):
         from wagtail.admin.widgets.chooser import AdminPageChooser
 
-        block = blocks.PageChooserBlock(help_text="pick a page, any page")
+        block = blocks.PageChooserBlock(
+            help_text="pick a page, any page", description="A featured page"
+        )
 
         block.set_name("test_pagechooserblock")
         js_args = FieldBlockAdapter().js_args(block)
@@ -4755,6 +4777,7 @@ class TestPageChooserBlock(TestCase):
             js_args[2],
             {
                 "label": "Test pagechooserblock",
+                "description": "A featured page",
                 "required": True,
                 "icon": "doc-empty-inverse",
                 "blockDefId": block.definition_prefix,
@@ -4963,6 +4986,7 @@ class TestStaticBlock(unittest.TestCase):
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "label": "Posts static block",
+                "description": "",
             },
         )
 
@@ -4985,6 +5009,7 @@ class TestStaticBlock(unittest.TestCase):
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "label": "Posts static block",
+                "description": "",
             },
         )
 
@@ -5006,6 +5031,7 @@ class TestStaticBlock(unittest.TestCase):
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "label": "Latest posts",
+                "description": "",
             },
         )
 
@@ -5028,6 +5054,7 @@ class TestStaticBlock(unittest.TestCase):
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "label": "Posts static block",
+                "description": "",
             },
         )
 
@@ -5050,6 +5077,7 @@ class TestStaticBlock(unittest.TestCase):
                 "icon": "placeholder",
                 "blockDefId": block.definition_prefix,
                 "label": "Posts static block",
+                "description": "",
             },
         )
 
@@ -5101,6 +5129,7 @@ class TestDateBlock(TestCase):
             js_args[2],
             {
                 "label": "Test dateblock",
+                "description": "",
                 "required": True,
                 "icon": "date",
                 "blockDefId": block.definition_prefix,
@@ -5135,6 +5164,7 @@ class TestTimeBlock(TestCase):
             js_args[2],
             {
                 "label": "Test timeblock",
+                "description": "",
                 "required": True,
                 "icon": "time",
                 "blockDefId": block.definition_prefix,
@@ -5169,6 +5199,7 @@ class TestDateTimeBlock(TestCase):
             js_args[2],
             {
                 "label": "Test datetimeblock",
+                "description": "",
                 "required": True,
                 "icon": "date",
                 "blockDefId": block.definition_prefix,