Use default icons for FieldPanels and add docs/tests for Panel icon customisation

[laymonage]

Fixes #10274

• Add documentation on how to set custom icons to panels, to a similar extent to what we do for StreamField
• Review possible default icons based on what we do for StreamField
• Add unit tests for the icon support to make sure default and custom icons are correctly picked up

Notes:

• I changed the default icon mechanism to check the model field first (instead of the form field). This is because model fields do not always have a 1:1 mapping to the form fields. For example, models.TextField and models.CharField both use forms.CharField.

  I spoke with Ben and he said we should use the pilcrow icon for TextFields and RichTextFields, but not for CharField. This is because the pilcrow generally represents a paragraph, which doesn't mean much in the context of CharFields. If we check for the form field, we cannot differentiate between TextField and CharField, unless we check the widget as well. Thus, I made the code to check for the model field first.

• That said, apparently FieldPanel can be used without a model field:

  wagtail/wagtail/admin/tests/test_edit_handlers.py

  Lines 678 to 685 in 18e5757

  	def test_non_model_field(self):
  	# defining a FieldPanel for a field which isn't part of a model is OK,
  	# because it might be defined on the form instead
  	field_panel = FieldPanel("barbecue").bind_to_model(Page)
  	# however, accessing db_field will fail
  	with self.assertRaises(FieldDoesNotExist):
  	field_panel.db_field

  
  So, I added a fallback code to use the form field to check for the default icon if the field does not exist on the model.

• For the same reason as the model vs form fields discrepancy, this means that the RegexField default will not be used unless either (a) the user creates a custom RegexField model field, or (b) the specified field does not exist on the model, and the form field is RegexField.

• I tweaked the field class checking to also look through the MRO. This allows us to use TaggableManager to define the default icon, and it works for both TaggableManager and ClusterableTaggableManager. This also allows custom fields that are subclasses of the known fields to use our default icons.

• For chooser panels, this was slightly trickier. We need to check if the field is a ForeignKey, and if so, we have two options that I can think of:

  • Look at the remote field's model. If it's a subclass of Page, Image, or Document, use the custom icon accordingly.
  • Look at our form field overrides. Then, see the widget's icon based on the override.

• I've revamped the docs for the panel types and the Panel API. There are some liberties that I took, and we might want Matthew to review the docs changes.

To test this, I've made a branch based on @thibaudcolas' "everything page" branch:
https://github.com/laymonage/bakerydemo/tree/feature/10274-everything-page-icons

The branch has been updated to remove the custom icon="..." argument in the FieldPanels. You can verify that even with the argument removed, the default icon will still be shown for the known fields.

Please check the following:

• Do the tests still pass?¹
• Does the code comply with the style guide?
  • Run make lint from the Wagtail root.
• For Python changes: Have you added tests to cover the new/fixed behaviour?
• For front-end changes: Did you test on all of Wagtail’s supported environments?²
  • Please list the exact browser and operating system versions you tested:
  • Please list which assistive technologies ³ you tested:
• For new features: Has the documentation been updated accordingly?

Please describe additional details for testing this change.

Footnotes

1. Development Testing ↩

2. Browser and device support ↩

3. Accessibility Target ↩

[squash-labs]

Manage this branch in Squash

Test this branch here: https://laymonagepanel-icons-mx0in.squash.io

[thibaudcolas]

Nice one @laymonage! All working as far as I can tell, just needed to SVGO-compress the new icons and add licensing information within.

[thibaudcolas]

Nice one!