Document Hallo extension points in docs, CHANGELOG, upgrade considerations

CHANGELOG.txt

@@ -49,6 +49,7 @@ Changelog
  * Made 'add/change/delete collection' permissions configurable from the group edit page (Matt Westcott)
  * Update autoprefixer configuration to better match browser support targets (Janneke Janssen)
  * Update React and related dependencies to latest versions (Janneke Janssen, Hugo van den Berg)
+ * Remove Hallo editor `.richtext` CSS class in favour of more explicit extension points (Thibaud Colas)
  * Fix: Do not remove stopwords when generating slugs from non-ASCII titles, to avoid issues with incorrect word boundaries (Sævar Öfjörð Magnússon)
  * Fix: The PostgreSQL search backend now preserves ordering of the `QuerySet` when searching with `order_by_relevance=False` (Bertrand Bordage)
  * Fix: Using `modeladmin_register` as a decorator no longer replaces the decorated class with `None` (Tim Heap)

docs/advanced_topics/customisation/page_editing_interface.rst

@@ -156,6 +156,11 @@ The constructor for ``HalloPlugin`` accepts the following keyword arguments:
  * ``css`` - a dictionary of CSS files to be imported for this plugin, defined in the same way as a `Django form media <https://docs.djangoproject.com/en/1.11/topics/forms/media/>`_ definition
  * ``order`` - an index number (default 100) specifying the order in which plugins should be listed, which in turn determines the order buttons will appear in the toolbar
 
+When writing the front-end code for the plugin, Wagtail’s Hallo implementation offers two extension points:
+
+* In JavaScript, use the ``[data-hallo-editor]`` attribute selector to target the editor, eg. ``var $editor = $('[data-hallo-editor]');``.
+* In CSS, use the ``.halloeditor`` class selector.
+
 
 .. _whitelisting_rich_text_elements:
 

docs/releases/2.0.rst

@@ -60,6 +60,7 @@ Other features
  * Upgraded jQuery to version 3.2.1 (Janneke Janssen)
  * Update autoprefixer configuration to better match browser support targets (Janneke Janssen)
  * Update React and related dependencies to latest versions (Janneke Janssen, Hugo van den Berg)
+ * Remove Hallo editor ``.richtext`` CSS class in favour of more explicit extension points (Thibaud Colas)
  * Updated documentation styling (LB (Ben Johnston))
  * Rich text fields now take feature lists into account when whitelisting HTML elements (Matt Westcott)
  * FormPage lists and Form submission lists in admin now use class based views for easy overriding (Johan Arensman)
@@ -288,3 +289,29 @@ from  ``wagtail.wagtailsearch.urls`` in your project's ``urls.py``), you will ne
 own implementation.
 
 See the search view in Wagtail demo for a guide: https://github.com/wagtail/wagtaildemo/blob/master/demo/views.py
+
+New Hallo editor extension points
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With the introduction of a new editor, we want to make sure existing editor plugins meant for Hallo only target
+Hallo editors for extension.
+
+* The existing ``.richtext`` CSS class is no longer applied to the Hallo editor’s DOM element.
+* In JavaScript, use the ``[data-hallo-editor]`` attribute selector to target the editor, eg. ``var $editor = $('[data-hallo-editor]');``.
+* In CSS, use the ``.halloeditor`` class selector.
+
+For example,
+
+  .. code-block:: diff
+
+    /* JS */
+    - var widget = $(elem).parent('.richtext').data('IKS-hallo');
+    + var widget = $(elem).parent('[data-hallo-editor]').data('IKS-hallo');
+
+    [...]
+
+    /* Styles */
+    - .richtext {
+    + .halloeditor {
+        font-family: monospace;
+    }