Switch register_setting, register_settings_menu_item to use SVG icons (#6107, #6649)

CHANGELOG.txt

@@ -12,6 +12,7 @@ Changelog
  * Update `PageQueryset.specific(defer=True)` to only perform a single database query (Andy Babic)
  * Add `PageQueryset.defer_streamfields()` (Andy Babic)
  * Utilize `PageQuerySet.defer_streamfields()` to improve efficiency in a few key places (Andy Babic)
+ * Switch ``register_setting``, ``register_settings_menu_item`` to use SVG icons (Thibaud Colas)
  * Fix: StreamField required status is now consistently handled by the `blank` keyword argument (Matt Westcott)
  * Fix: Show 'required' asterisks for blocks inside required StreamFields (Matt Westcott)
  * Fix: Make image chooser "Select format" fields translatable (Helen Chapman, Thibaud Colas)

docs/releases/2.13.rst

@@ -21,7 +21,7 @@ Other features
 * Support passing multiple models as arguments to ``type()``, ``not_type()``, ``exact_type()`` and ``not_exact_type()`` methods on ``PageQuerySet`` (Andy Babic)
 * Update default attribute copying behaviour of ``Page.get_specific()`` and added the ``copy_attrs_exclude`` option (Andy Babic)
 * Update ``PageQueryset.specific(defer=True)`` to only perform a single database query (Andy Babic)
-
+* Switched ``register_setting``, ``register_settings_menu_item`` to use SVG icons (Thibaud Colas)
 
 Bug fixes
 ~~~~~~~~~
@@ -38,3 +38,24 @@ Updated handling of non-required StreamFields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The rules for determining whether a StreamField is required (i.e. at least one block must be provided) have been simplified and made consistent with other field types. Non-required fields are now indicated by ``blank=True`` on the ``StreamField`` definition; the default is ``blank=False`` (the field is required). In previous versions, to make a field non-required, it was necessary to define :ref:`a top-level StreamBlock<streamfield_top_level_streamblock>` with ``required=False`` (which applied the validation rule) as well as setting ``blank=True`` (which removed the asterisk from the form field). You should review your use of StreamField to check that ``blank=True`` is used on the fields you wish to make optional.
+
+Switched ``register_setting``, ``register_settings_menu_item`` to use SVG icons
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting menu items now use SVG icons by default. For sites reusing built-in Wagtail icons, no changes should be required. For sites using custom font icons, update the menu items’ definition to use the ``classnames`` attribute:
+
+.. code-block:: python
+
+    # With register_setting,
+    # Before:
+    @register_setting(icon='custom-cog')
+    # After:
+    @register_setting(icon='', classnames='icon icon-custom-cog')
+
+    # Or with register_settings_menu_item,
+    @hooks.register('register_settings_menu_item')
+    def register_frank_menu_item():
+        # Before:
+        return SettingMenuItem(CustomSetting, icon='custom-cog')
+        # After:
+        return SettingMenuItem(CustomSetting, icon='', classnames='icon icon-custom-cog')

wagtail/contrib/settings/registry.py

@@ -12,11 +12,16 @@ from .permissions import user_can_edit_setting_type
 class SettingMenuItem(MenuItem):
     def __init__(self, model, icon='cog', classnames='', **kwargs):
 
-        icon_classes = 'icon icon-' + icon
-        if classnames:
-            classnames += ' ' + icon_classes
+        # Special-case FontAwesome icons to avoid the breaking changes for those customizations.
+        if icon.startswith('fa-'):
+            icon_name = ''
+            icon_classes = 'icon icon-' + icon
+            if classnames:
+                classnames += ' ' + icon_classes
+            else:
+                classnames = icon_classes
         else:
-            classnames = icon_classes
+            icon_name = icon
 
         self.model = model
         super().__init__(
@@ -24,6 +29,7 @@ class SettingMenuItem(MenuItem):
             url=reverse('wagtailsettings:edit', args=[
                 model._meta.app_label, model._meta.model_name]),
             classnames=classnames,
+            icon_name=icon_name,
             **kwargs)
 
     def is_shown(self, request):

wagtail/contrib/settings/tests/test_admin.py

@@ -40,8 +40,13 @@ class TestSettingMenu(TestCase, WagtailTestUtils):
 
     def test_menu_item_icon(self):
         menu_item = SettingMenuItem(IconSetting, icon='tag', classnames='test-class')
-        classnames = set(menu_item.classnames.split(' '))
-        self.assertEqual(classnames, {'icon', 'icon-tag', 'test-class'})
+        self.assertEqual(menu_item.icon_name, 'tag')
+        self.assertEqual(menu_item.classnames, 'test-class')
+
+    def test_menu_item_icon_fontawesome(self):
+        menu_item = SettingMenuItem(IconSetting, icon='fa-suitcase', classnames='test-class')
+        self.assertEqual(menu_item.icon_name, '')
+        self.assertEqual(set(menu_item.classnames.split(' ')), {'icon', 'icon-fa-suitcase', 'test-class'})
 
 
 class BaseTestSettingView(TestCase, WagtailTestUtils):