display help text message for tag field

- resolves #1874
- ensure message is dynamic based on the setting TAG_SPACES_ALLOWED
- Update wagtail/admin/templates/wagtailadmin/widgets/tag_widget.html

CHANGELOG.txt

@@ -51,6 +51,7 @@ Changelog
  * Support chunking in `PageQuerySet.specific()` to reduce memory consumption (Andy Babic)
  * Implement new tabs design across the admin interface (Steven Steinwand)
  * Move page meta information from the header to a new status side panel component inside of the page editing UI (Steven Steinwand, Karl Hobley)
+ * Add useful help text to Tag fields to advise what content is allowed inside tags, including when `TAG_SPACES_ALLOWED` is `True` or `False` (Abdulmajeed Isa)
  * 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

@@ -80,6 +80,7 @@ class LandingPage(Page):
  * Add the ability for choices to be separated by new lines instead of just commas within the form builder, commas will still be supported if used (Abdulmajeed Isa)
  * Add internationalisation UI to modeladmin (Andrés Martano)
  * Support chunking in `PageQuerySet.specific()` to reduce memory consumption (Andy Babic)
+ * Add useful help text to Tag fields to advise what content is allowed inside tags, including when `TAG_SPACES_ALLOWED` is `True` or `False` (Abdulmajeed Isa)
  * Fix: Implement ARIA tabs markup and keyboards interactions for admin tabs (Steven Steinwand)
 
 ### Bug fixes

wagtail/admin/templates/wagtailadmin/widgets/tag_widget.html

@@ -1,4 +1,5 @@
 {% include 'django/forms/widgets/text.html' %}
+<p class="help">{{ widget.help_text }}</p>
 <script>
     initTagField(
         "{{ widget.attrs.id|escapejs }}",

wagtail/admin/tests/test_widgets.py

@@ -361,6 +361,16 @@ class TestAdminTagWidget(TestCase):
                 return json.loads("[%s]" % params_raw)
         return []
 
+    def get_help_text_html_element(self, html):
+        """Return a help text html element with content as string"""
+        start = """<input type="text" name="tags">"""
+        end = "<script>"
+        items_after_input_tag = html.split(start)[1]
+        if items_after_input_tag:
+            help_text_element = items_after_input_tag.split(end)[0].strip()
+            return help_text_element
+        return []
+
     def test_render_js_init_basic(self):
         """Checks that the 'initTagField' is correctly added to the inline script for tag widgets"""
         widget = widgets.AdminTagWidget()
@@ -462,6 +472,43 @@ class TestAdminTagWidget(TestCase):
             ],
         )
 
+    @override_settings(TAG_SPACES_ALLOWED=True)
+    def test_tags_help_text_spaces_allowed(self):
+        """Checks that the tags help text html element content is correct when TAG_SPACES_ALLOWED is True"""
+        widget = widgets.AdminTagWidget()
+        help_text = widget.get_context(None, None, {})["widget"]["help_text"]
+
+        html = widget.render("tags", None, {})
+        help_text_html_element = self.get_help_text_html_element(html)
+
+        self.assertEqual(
+            help_text,
+            'Multi-word tags with spaces will automatically be enclosed in double quotes (").',
+        )
+
+        self.assertHTMLEqual(
+            help_text_html_element,
+            """<p class="help">%s</p>""" % help_text,
+        )
+
+    @override_settings(TAG_SPACES_ALLOWED=False)
+    def test_tags_help_text_no_spaces_allowed(self):
+        """Checks that the tags help text html element content is correct when TAG_SPACES_ALLOWED is False"""
+        widget = widgets.AdminTagWidget()
+        help_text = widget.get_context(None, None, {})["widget"]["help_text"]
+
+        html = widget.render("tags", None, {})
+        help_text_html_element = self.get_help_text_html_element(html)
+
+        self.assertEqual(
+            help_text, "Tags can only consist of a single word, no spaces allowed."
+        )
+
+        self.assertHTMLEqual(
+            help_text_html_element,
+            """<p class="help">%s</p>""" % help_text,
+        )
+
 
 class TestTagField(TestCase):
     def setUp(self):

wagtail/admin/widgets/tags.py

@@ -2,6 +2,7 @@ import json
 
 from django.conf import settings
 from django.urls import reverse
+from django.utils.translation import gettext_lazy as _
 from taggit.forms import TagWidget
 from taggit.models import Tag
 
@@ -31,6 +32,15 @@ class AdminTagWidget(TagWidget):
         else:
             free_tagging = self.free_tagging
 
+        tag_spaces_allowed = getattr(settings, "TAG_SPACES_ALLOWED", True)
+        if tag_spaces_allowed:
+            help_text = _(
+                'Multi-word tags with spaces will automatically be enclosed in double quotes (").'
+            )
+        else:
+            help_text = _("Tags can only consist of a single word, no spaces allowed.")
+
+        context["widget"]["help_text"] = help_text
         context["widget"]["autocomplete_url"] = autocomplete_url
         context["widget"]["options_json"] = json.dumps(
             {