Page description (#8164)

Co-authored-by: Thibaud Colas <thibaudcolas@gmail.com>
Co-authored-by: Kalob Taulien <kalob.taulien@gmail.com>

CHANGELOG.txt

@@ -36,6 +36,7 @@ Changelog
  * Split up linting / formatting tasks in Makefile into client and server components (Hitansh Shah)
  * Add support for embedding Instagram reels (Luis Nell)
  * Use Django’s JavaScript catalog feature to manage translatable strings in JavaScript (Karl Hobley)
+ * Add a `page_description` to the Page model, to provide help text for a given page type (Kalob Taulien, Thibaud Colas, Matt Westcott)
  * Fix: When using `simple_translations` ensure that the user is redirected to the page edit view when submitting for a single locale (Mitchel Cabuloy)
  * Fix: When previewing unsaved changes to `Form` pages, ensure that all added fields are correctly shown in the preview (Joshua Munn)
  * Fix: When Documents (e.g. PDFs) have been configured to be served inline via `WAGTAILDOCS_CONTENT_TYPES` & `WAGTAILDOCS_INLINE_CONTENT_TYPES` ensure that the filename is correctly set in the `Content-Disposition` header so that saving the files will use the correct filename (John-Scott Atlakson)

docs/releases/3.0.md

@@ -27,6 +27,15 @@ The panel types `StreamFieldPanel`, `RichTextFieldPanel`, `ImageChooserPanel`, `
 
 [`FieldPanel`](wagtail.admin.panels.FieldPanel) now accepts a `permission` keyword argument to specify that the field should only be available to users with a given permission level. This feature was developed by Matt Westcott and sponsored by Google as part of Wagtail's page editor redevelopment.
 
+### Page descriptions
+
+With every Wagtail Page you are able to add a helpful description text, similar to a `help_text` model attribute. By adding `page_description` to your Page model you'll be adding a short description that can be seen in different places within Wagtail:
+
+```python
+class LandingPage(Page):
+    
+    page_description = "Use this page for converting users"
+```
 
 ### Other features
 

docs/topics/pages.md

@@ -163,6 +163,17 @@ By default, any page type can be created under any page type and it is not neces
 
 Setting `parent_page_types` to an empty list is a good way of preventing a particular page type from being created in the editor interface.
 
+(page_descriptions)=
+### Page descriptions
+
+With every Wagtail Page you are able to add a helpful description text, similar to a ``help_text`` model attribute. By adding ``page_description`` to your Page model you'll be adding a short description that can be seen when you create a new page, edit an existing page or when you're prompted to select a child page type.
+
+```python
+class LandingPage(Page):
+
+    page_description = "Use this page for converting users"
+```
+
 (page_urls)=
 ### Page URLs
 

wagtail/admin/templates/wagtailadmin/pages/add_subpage.html

@@ -13,14 +13,19 @@
 
         {% if page_types %}
             <ul class="listing">
-                {% for verbose_name, app_label, model_name in page_types %}
+                {% for verbose_name, app_label, model_name, page_description in page_types %}
                     <li>
                         <div class="row row-flush">
-                            <div class="col6">
-                                <a href="{% url 'wagtailadmin_pages:add' app_label model_name parent_page.id %}{% if next %}?next={{ next }}{% endif %}" class="icon icon-plus-inverse icon-larger">{{ verbose_name }}</a>
+                            <div class="col8">
+                                <a href="{% url 'wagtailadmin_pages:add' app_label model_name parent_page.id %}{% if next %}?next={{ next }}{% endif %}" class="icon icon-plus-inverse icon-larger">
+                                    {{ verbose_name }}
+                                    {% if page_description %}
+                                        <div><span class="visuallyhidden">.</span><small>{{ page_description }}</small></div>
+                                    {% endif %}
+                                </a>
                             </div>
 
-                            <small class="col6" style="text-align:end">
+                            <small class="col4" style="text-align:end">
                                 <a href="{% url 'wagtailadmin_pages:type_use' app_label model_name %}" class="nolink">{% blocktrans with page_type=verbose_name %}Pages using {{ page_type }}{% endblocktrans %}</a>
                             </small>
 

wagtail/admin/templates/wagtailadmin/pages/create.html

@@ -12,7 +12,13 @@
 
         <div class="row">
             <div class="left col9 header-title">
-                <h1>{% trans 'New' %} <span>{{ content_type.model_class.get_verbose_name }}</span></h1>
+                <h1>
+                    {% icon "doc-empty-inverse" class_name="header-title-icon" %}
+                    {% trans 'New' %} <span>{{ content_type.model_class.get_verbose_name }}</span>
+                </h1>
+                {% if content_type.model_class.get_page_description %}
+                    <p>{{ content_type.model_class.get_page_description }}</p>
+                {% endif %}
             </div>
         </div>
 

wagtail/admin/templates/wagtailadmin/pages/edit.html

@@ -11,11 +11,13 @@
     <header class="merged tab-merged">
         {% explorer_breadcrumb page page_perms=page_perms show_header_buttons=True %}
 
-        <div class="row">
-            <h1 class="left col9 header-title" title="{% blocktrans with title=page.get_admin_display_title page_type=content_type.model_class.get_verbose_name %}Editing {{ page_type }}{% endblocktrans %}">
-                {{ page.get_admin_display_title }}
-            </h1>
-
+        <div class="row row-flush">
+            <div class="left col9 header-title" title="{% blocktrans with title=page.get_admin_display_title page_type=content_type.model_class.get_verbose_name %}Editing {{ page_type }}{% endblocktrans %}">
+                <h1>
+                    {% icon name="doc-empty-inverse" class_name="header-title-icon" %}
+                    {% blocktrans with title=page.get_admin_display_title page_type=content_type.model_class.get_verbose_name %}Editing {{ page_type }} <span>{{ title }}</span>{% endblocktrans %}
+                </h1>
+            </div>
             <div class="right col3">
                 {% include "wagtailadmin/pages/_page_view_live_tag.html" with page=page_for_status %}
             </div>
@@ -34,6 +36,14 @@
                 {% icon name="doc-empty-inverse" class_name="default" %}
                 {{ content_type.model_class.get_verbose_name }}
             </li>
+            {% if content_type.model_class.get_page_description %}
+                <li class="header-meta--type">
+                    {% icon name="help" class_name="default" %}
+                    <span data-wagtail-tooltip="{{ content_type.model_class.get_page_description }}">
+                        {{ content_type.model_class.get_page_description|truncatewords:4 }}
+                    </span>
+                </li>
+            {% endif %}
             {% if locale %}
                 <li class="header-meta--locale">
                     {% include "wagtailadmin/shared/locale_selector.html" %}

wagtail/admin/tests/pages/test_create_page.py

@@ -46,6 +46,7 @@ class TestPageCreation(TestCase, WagtailTestUtils):
             "wagtailadmin_pages:add", args=("tests", "simplepage", self.root_page.id)
         )
         self.assertContains(response, 'href="%s"' % target_url)
+        self.assertContains(response, "A simple page description")
         # List of available page types should not contain pages with is_creatable = False
         self.assertNotContains(response, "MTI base page")
         # List of available page types should not contain abstract pages

wagtail/admin/views/pages/create.py

@@ -24,7 +24,12 @@ def add_subpage(request, parent_page_id):
         raise PermissionDenied
 
     page_types = [
-        (model.get_verbose_name(), model._meta.app_label, model._meta.model_name)
+        (
+            model.get_verbose_name(),
+            model._meta.app_label,
+            model._meta.model_name,
+            model.get_page_description(),
+        )
         for model in type(parent_page).creatable_subpage_models()
         if model.can_create_at(parent_page)
     ]
@@ -34,7 +39,7 @@ def add_subpage(request, parent_page_id):
     if len(page_types) == 1:
         # Only one page type is available - redirect straight to the create form rather than
         # making the user choose
-        verbose_name, app_label, model_name = page_types[0]
+        verbose_name, app_label, model_name, description = page_types[0]
         return redirect("wagtailadmin_pages:add", app_label, model_name, parent_page.id)
 
     return TemplateResponse(

wagtail/models/__init__.py

@@ -1499,6 +1499,19 @@ class Page(AbstractPage, index.Indexed, ClusterableModel, metaclass=PageBase):
         # except this doesn't convert any characters to lowercase
         return capfirst(cls._meta.verbose_name)
 
+    @classmethod
+    def get_page_description(cls):
+        """
+        Returns a page description if it's set. For example "A multi-purpose web page".
+        """
+        description = getattr(cls, "page_description", None)
+
+        # make sure that page_description is actually a string rather than a model field
+        if isinstance(description, str):
+            return description
+        else:
+            return ""
+
     @property
     def status_string(self):
         if not self.live:

wagtail/test/testapp/models.py

@@ -162,6 +162,7 @@ class RelatedLink(LinkFields):
 # Simple page
 class SimplePage(Page):
     content = models.TextField()
+    page_description = "A simple page description"
 
     content_panels = [
         FieldPanel("title", classname="full title"),