From fb0742802f2d738ae3de8b589139a5a93559bcc5 Mon Sep 17 00:00:00 2001
From: Dan Braghis <dan.braghis@torchbox.com>
Date: Fri, 3 Jul 2020 13:26:18 +0100
Subject: [PATCH] Include task description in choosers, if defined (#6200)

---
 docs/advanced_topics/custom_tasks.rst               | 13 +++++++++++++
 .../wagtailadmin/workflows/select_task_type.html    |  5 ++++-
 .../task_chooser/includes/select_task_type.html     |  5 ++++-
 wagtail/admin/tests/test_workflows.py               |  1 +
 wagtail/admin/views/workflows.py                    |  6 +++---
 wagtail/core/models.py                              |  9 +++++++++
 6 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/docs/advanced_topics/custom_tasks.rst b/docs/advanced_topics/custom_tasks.rst
index 07c15d7905..a191464571 100644
--- a/docs/advanced_topics/custom_tasks.rst
+++ b/docs/advanced_topics/custom_tasks.rst
@@ -195,6 +195,19 @@ For example:
             return TaskState.objects.none()
 
 
+``Task.get_description()```
+
+A class method that returns the human-readable description for the task.
+
+For example:
+
+.. code-block:: python
+
+    @classmethod
+    def get_description(cls):
+        return _("Members of the chosen Wagtail Groups can approve this task")
+
+
 Adding notifications
 ~~~~~~~~~~~~~~~~~~~~
 
diff --git a/wagtail/admin/templates/wagtailadmin/workflows/select_task_type.html b/wagtail/admin/templates/wagtailadmin/workflows/select_task_type.html
index fd298084d5..8245cc424a 100644
--- a/wagtail/admin/templates/wagtailadmin/workflows/select_task_type.html
+++ b/wagtail/admin/templates/wagtailadmin/workflows/select_task_type.html
@@ -12,12 +12,15 @@
 
         {% if task_types %}
             <ul class="listing">
-                {% for verbose_name, app_label, model_name in task_types %}
+                {% for verbose_name, app_label, model_name, description in task_types %}
                     <li>
                         <div class="row row-flush">
                             <div class="col6">
                                 <a href="{% url 'wagtailadmin_workflows:add_task' app_label model_name %}" class="icon icon-plus-inverse icon-larger">{{ verbose_name }}</a>
                             </div>
+                            <div class="col6">
+                                {{ description }}
+                            </div>
                         </div>
                     </li>
                 {% endfor %}
diff --git a/wagtail/admin/templates/wagtailadmin/workflows/task_chooser/includes/select_task_type.html b/wagtail/admin/templates/wagtailadmin/workflows/task_chooser/includes/select_task_type.html
index 356f9cbbb1..af713cb6fb 100644
--- a/wagtail/admin/templates/wagtailadmin/workflows/task_chooser/includes/select_task_type.html
+++ b/wagtail/admin/templates/wagtailadmin/workflows/task_chooser/includes/select_task_type.html
@@ -4,12 +4,15 @@
 
 {% if task_types %}
     <ul class="listing">
-        {% for verbose_name, app_label, model_name in task_types %}
+        {% for verbose_name, app_label, model_name, description in task_types %}
             <li>
                 <div class="row row-flush">
                     <div class="col6">
                         <a href="{% url 'wagtailadmin_workflows:task_chooser' %}?create_model={{ app_label|urlencode }}.{{ model_name|urlencode }}" class="icon icon-plus-inverse icon-larger task-type-choice">{{ verbose_name }}</a>
                     </div>
+                    <div class="col6">
+                        {{ description }}
+                    </div>
                 </div>
             </li>
         {% endfor %}
diff --git a/wagtail/admin/tests/test_workflows.py b/wagtail/admin/tests/test_workflows.py
index a506e5d40b..6ce96db359 100644
--- a/wagtail/admin/tests/test_workflows.py
+++ b/wagtail/admin/tests/test_workflows.py
@@ -589,6 +589,7 @@ class TestSelectTaskTypeView(TestCase, WagtailTestUtils):
         # Check that the list of available task types includes SimpleTask and GroupApprovalTask
         self.assertContains(response, SimpleTask.get_verbose_name())
         self.assertContains(response, GroupApprovalTask.get_verbose_name())
+        self.assertContains(response, GroupApprovalTask.get_description())
 
 
 class TestEditTaskView(TestCase, WagtailTestUtils):
diff --git a/wagtail/admin/views/workflows.py b/wagtail/admin/views/workflows.py
index e9e986caf9..db934b4cd5 100644
--- a/wagtail/admin/views/workflows.py
+++ b/wagtail/admin/views/workflows.py
@@ -331,7 +331,7 @@ def select_task_type(request):
         raise PermissionDenied
 
     task_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_description())
         for model in get_task_types()
     ]
     # sort by lower-cased version of verbose name
@@ -340,7 +340,7 @@ def select_task_type(request):
     if len(task_types) == 1:
         # Only one task type is available - redirect straight to the create form rather than
         # making the user choose
-        verbose_name, app_label, model_name = task_types[0]
+        verbose_name, app_label, model_name, description = task_types[0]
         return redirect('wagtailadmin_workflows:add_task', app_label, model_name)
 
     return render(request, 'wagtailadmin/workflows/select_task_type.html', {
@@ -525,7 +525,7 @@ def task_chooser(request):
 
     # Build task types list for "select task type" view
     task_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_description())
         for model in task_models
     ]
     # sort by lower-cased version of verbose name
diff --git a/wagtail/core/models.py b/wagtail/core/models.py
index eb2f0ed4b5..7967a3e2d8 100644
--- a/wagtail/core/models.py
+++ b/wagtail/core/models.py
@@ -2719,6 +2719,11 @@ class Task(models.Model):
         """Returns a ``QuerySet`` of the task states the current user can moderate"""
         return TaskState.objects.none()
 
+    @classmethod
+    def get_description(cls):
+        """Returns the task description."""
+        return ''
+
     @property
     def get_workflows(self):
         """Returns a ``QuerySet`` of the workflows that this task is part of """
@@ -2839,6 +2844,10 @@ class GroupApprovalTask(Task):
         else:
             return TaskState.objects.none()
 
+    @classmethod
+    def get_description(cls):
+        return _("Members of the chosen Wagtail Groups can approve this task")
+
     class Meta:
         verbose_name = _('Group approval task')
         verbose_name_plural = _('Group approval tasks')