kopia lustrzana https://github.com/wagtail/wagtail
Move Hallo & Draftail extension docs to their own pages
Thibaud Colas
Matt Westcott
rodzic
4285b9f1cc
commit
5c00b843c5
|
|
@ -0,0 +1,158 @@
|
|||
Extending the Draftail Editor
|
||||
=============================
|
||||
|
||||
Wagtail’s rich text editor is built with `Draftail <https://github.com/springload/draftail>`_, and its functionality can be extended through plugins.
|
||||
|
||||
Plugins come in three types:
|
||||
|
||||
* Inline styles – To format a portion of a line, eg. ``bold``, ``italic``, ``monospace``.
|
||||
* Blocks – To indicate the structure of the content, eg. ``blockquote``, ``ol``.
|
||||
* Entities – To enter additional data/metadata, eg. ``link`` (with a URL), ``image`` (with a file).
|
||||
|
||||
All of these plugins are created with a similar baseline, which we can demonstrate with one of the simplest examples – a custom feature for an inline style of ``strikethrough``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import wagtail.admin.rich_text.editors.draftail.features as draftail_features
|
||||
from wagtail.admin.rich_text.converters.html_to_contentstate import InlineStyleElementHandler
|
||||
from wagtail.core import hooks
|
||||
|
||||
# 1. Use the register_rich_text_features hook.
|
||||
@hooks.register('register_rich_text_features')
|
||||
def register_strikethrough_feature(features):
|
||||
"""
|
||||
Registering the `strikethrough` feature, which uses the `STRIKETHROUGH` Draft.js inline style type,
|
||||
and is stored as HTML with an `<s>` tag.
|
||||
"""
|
||||
feature_name = 'strikethrough'
|
||||
type_ = 'STRIKETHROUGH'
|
||||
tag = 's'
|
||||
|
||||
# 2. Configure how Draftail handles the feature in its toolbar.
|
||||
control = {
|
||||
'type': type_,
|
||||
'label': 'S',
|
||||
'description': 'Strikethrough',
|
||||
# This isn’t even required – Draftail has predefined styles for STRIKETHROUGH.
|
||||
# 'style': {'textDecoration': 'line-through'},
|
||||
}
|
||||
|
||||
# 3. Call register_editor_plugin to register the configuration for Draftail.
|
||||
features.register_editor_plugin(
|
||||
'draftail', feature_name, draftail_features.InlineStyleFeature(control)
|
||||
)
|
||||
|
||||
# 4.configure the content transform from the DB to the editor and back.
|
||||
db_conversion = {
|
||||
'from_database_format': {tag: InlineStyleElementHandler(type_)},
|
||||
'to_database_format': {'style_map': {type_: tag}},
|
||||
}
|
||||
|
||||
# 5. Call register_converter_rule to register the content transformation conversion.
|
||||
features.register_converter_rule('contentstate', feature_name, db_conversion)
|
||||
|
||||
These five steps will always be the same for all Draftail plugins. The important parts are to:
|
||||
|
||||
* Consistently use the feature’s Draft.js type or Wagtail feature names where appropriate.
|
||||
* Give enough information to Draftail so it knows how to make a button for the feature, and how to render it (more on this later).
|
||||
* Configure the conversion to use the right HTML element (as they are stored in the DB).
|
||||
|
||||
For detailed configuration options, head over to the `Draftail documentation <https://github.com/springload/draftail#formatting-options>`_ to see all of the details. Here are some parts worth highlighting about controls:
|
||||
|
||||
* The ``type`` is the only mandatory piece of information.
|
||||
* To display the control in the toolbar, combine ``icon``, ``label`` and ``description``.
|
||||
* The controls’ ``icon`` can be a string to use an icon font with CSS classes, say ``'icon': 'fas fa-user',``. It can also be an array of strings, to use SVG paths, or SVG symbol references eg. ``'icon': ['M100 100 H 900 V 900 H 100 Z'],``. The paths need to be set for a 1024x1024 viewbox.
|
||||
|
||||
Creating new inline styles
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the initial example, inline styles take a ``style`` property to define what CSS rules will be applied to text in the editor. Be sure to read the `Draftail documentation <https://github.com/springload/draftail#formatting-options>`_ on inline styles.
|
||||
|
||||
Finally, the DB to/from conversion uses an ``InlineStyleElementHandler`` to map from a given tag (``<s>`` in the example above) to a Draftail type, and the inverse mapping is done with `Draft.js exporter configuration <https://github.com/springload/draftjs_exporter>`_ of the ``style_map``.
|
||||
|
||||
Creating new blocks
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Blocks are nearly as simple as inline styles:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.admin.rich_text.converters.html_to_contentstate import BlockElementHandler
|
||||
|
||||
@hooks.register('register_rich_text_features')
|
||||
def register_blockquote_feature(features):
|
||||
"""
|
||||
Registering the `blockquote` feature, which uses the `blockquote` Draft.js block type,
|
||||
and is stored as HTML with a `<blockquote>` tag.
|
||||
"""
|
||||
feature_name = 'blockquote'
|
||||
type_ = 'blockquote'
|
||||
tag = 'blockquote'
|
||||
|
||||
control = {
|
||||
'type': type_,
|
||||
'label': '❝',
|
||||
'description': 'Blockquote',
|
||||
# We need to tell Draftail what element to use when displaying those blocks in the editor.
|
||||
'element': 'blockquote',
|
||||
# This isn't required as the blockquote tag could be styled directly.
|
||||
# 'className': 'editor__blockquote',
|
||||
}
|
||||
|
||||
features.register_editor_plugin(
|
||||
'draftail', feature_name, draftail_features.BlockFeature(control)
|
||||
)
|
||||
|
||||
features.register_converter_rule('contentstate', feature_name, {
|
||||
'from_database_format': {tag: BlockElementHandler(type_)},
|
||||
'to_database_format': {'block_map': {type_: tag}},
|
||||
})
|
||||
|
||||
Here are the main differences:
|
||||
|
||||
* We need to configure an ``element`` to tell Draftail how to render those blocks in the editor.
|
||||
* We could use a ``className`` (say if ``element`` was ``div``) to style the blockquotes in the editor.
|
||||
* We register the plugin with ``BlockFeature``.
|
||||
* We set up the conversion with ``BlockElementHandler`` and ``block_map``.
|
||||
|
||||
That’s it! The extra complexity is that you may need to write CSS in conjunction with the ``className`` to style the blocks in the editor.
|
||||
|
||||
Creating new entities
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. warning::
|
||||
This is an advanced feature. Please carefully consider whether you really need this.
|
||||
|
||||
Entities aren’t simply formatting buttons in the toolbar. They usually need to be much more versatile, communicating to APIs or requesting further user input. As such,
|
||||
|
||||
* You will most likely need to write a **hefty dose of JavaScript**, some of it with React.
|
||||
* The API is very **low-level**. You will most likely need some **Draft.js knowledge**.
|
||||
* Custom UIs in rich text can be brittle. Be ready to spend time **testing in multiple browsers**.
|
||||
|
||||
The good news is that having such a low-level API will enable third-party Wagtail plugins to innovate on rich text features, proposing new kinds of experiences.
|
||||
But in the meantime, consider implementing your UI through :doc:`StreamField <../../topics/streamfield>` instead, which has a battle-tested API meant for Django developers.
|
||||
|
||||
----
|
||||
|
||||
Here are the main requirements to create a new entity feature:
|
||||
|
||||
* Like for inline styles and blocks, register an editor plugin.
|
||||
* The editor plugin must define a ``source``: a React component responsible for creating new entity instances in the editor, using the Draft.js API.
|
||||
* The editor plugin also needs a ``decorator`` (for inline entities) or ``block`` (for block entities): a React component responsible for displaying entity instances within the editor.
|
||||
* Like for inline styles and blocks, set up the to/from DB conversion.
|
||||
* The conversion usually is more involved, since entities contain data that needs to be serialised to HTML.
|
||||
|
||||
To write the React components, Wagtail exposes its own React and Draft.js dependencies as global variables. Read more about this in :ref:`extending_clientside_components`.
|
||||
To go further, please look at the `Draftail documentation <https://github.com/springload/draftail#formatting-options>`_ as well as the `Draft.js exporter documentation <https://github.com/springload/draftjs_exporter>`_.
|
||||
|
||||
Here is a detailed example to showcase how those tools are used in the context of Wagtail.
|
||||
For the sake of our example, we can imagine a news team working at a financial newspaper.
|
||||
They want to write articles about the stock market, refer to specific stocks anywhere inside of their content (eg. "$TSLA" tokens in a sentence), and then have their article automatically enriched with the stock’s information (a link, a number, a sparkline).
|
||||
|
||||
The editor toolbar could contain a "stock chooser" that displays a list of available stocks, then inserts the user’s selection as a textual token. For our example, we will just pick a stock at random:
|
||||
|
||||
.. image:: ../../_static/images/draftail_entity_stock_source.gif
|
||||
|
||||
Those tokens are then saved in the rich text on publish. When the news article is displayed on the site, we then insert live market data coming from an API next to each token:
|
||||
|
||||
.. image:: ../../_static/images/draftail_entity_stock_rendering.png
|
||||
|
|
@ -0,0 +1,76 @@
|
|||
Extending the Hallo Editor
|
||||
==========================
|
||||
|
||||
.. warning::
|
||||
**As of Wagtail 2.0, the hallo.js editor is deprecated.** We have no intentions to remove it from Wagtail as of yet, but it will no longer receive bug fixes. Please be aware of the `known hallo.js issues <https://github.com/wagtail/wagtail/issues?q=is%3Aissue+is%3Aclosed+hallo+label%3A%22component%3ARich+text%22+label%3Atype%3ABug+label%3A%22status%3AWont+Fix%22>`_ should you want to keep using it.
|
||||
|
||||
To use hallo.js on Wagtail 2.x, add the following to your settings:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
WAGTAILADMIN_RICH_TEXT_EDITORS = {
|
||||
'default': {
|
||||
'WIDGET': 'wagtail.admin.rich_text.HalloRichTextArea'
|
||||
}
|
||||
}
|
||||
|
||||
The legacy hallo.js editor’s functionality can be extended through plugins. For information on developing custom ``hallo.js`` plugins, see the project's page: https://github.com/bergie/hallo
|
||||
|
||||
Once the plugin has been created, it should be registered through the feature registry's ``register_editor_plugin(editor, feature_name, plugin)`` method. For a ``hallo.js`` plugin, the ``editor`` parameter should always be ``'hallo'``.
|
||||
|
||||
A plugin ``halloblockquote``, implemented in ``myapp/js/hallo-blockquote.js``, that adds support for the ``<blockquote>`` tag, would be registered under the feature name ``block-quote`` as follows:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.admin.rich_text import HalloPlugin
|
||||
from wagtail.core import hooks
|
||||
|
||||
@hooks.register('register_rich_text_features')
|
||||
def register_embed_feature(features):
|
||||
features.register_editor_plugin(
|
||||
'hallo', 'block-quote',
|
||||
HalloPlugin(
|
||||
name='halloblockquote',
|
||||
js=['myapp/js/hallo-blockquote.js'],
|
||||
)
|
||||
)
|
||||
|
||||
The constructor for ``HalloPlugin`` accepts the following keyword arguments:
|
||||
|
||||
* ``name`` - the plugin name as defined in the Javascript code. ``hallo.js`` plugin names are prefixed with the ``"IKS."`` namespace, but the name passed here should be without the prefix.
|
||||
* ``options`` - a dictionary (or other JSON-serialisable object) of options to be passed to the Javascript plugin code on initialisation
|
||||
* ``js`` - a list of Javascript 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
|
||||
* ``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:
|
||||
|
||||
Whitelisting rich text elements
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After extending the editor to support a new HTML element, you'll need to add it to the whitelist of permitted elements - Wagtail's standard behaviour is to strip out unrecognised elements, to prevent editors from inserting styles and scripts (either deliberately, or inadvertently through copy-and-paste) that the developer didn't account for.
|
||||
|
||||
Elements can be added to the whitelist through the feature registry's ``register_converter_rule(converter, feature_name, ruleset)`` method. When the ``hallo.js`` editor is in use, the ``converter`` parameter should always be ``'editorhtml'``.
|
||||
|
||||
The following code will add the ``<blockquote>`` element to the whitelist whenever the ``block-quote`` feature is active:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.admin.rich_text.converters.editor_html import WhitelistRule
|
||||
from wagtail.core.whitelist import allow_without_attributes
|
||||
|
||||
@hooks.register('register_rich_text_features')
|
||||
def register_blockquote_feature(features):
|
||||
features.register_converter_rule('editorhtml', 'block-quote', [
|
||||
WhitelistRule('blockquote', allow_without_attributes),
|
||||
])
|
||||
|
||||
``WhitelistRule`` is passed the element name, and a callable which will perform some kind of manipulation of the element whenever it is encountered. This callable receives the element as a `BeautifulSoup <http://www.crummy.com/software/BeautifulSoup/bs4/doc/>`_ Tag object.
|
||||
|
||||
The ``wagtail.core.whitelist`` module provides a few helper functions to assist in defining these handlers: ``allow_without_attributes``, a handler which preserves the element but strips out all of its attributes, and ``attribute_rule`` which accepts a dict specifying how to handle each attribute, and returns a handler function. This dict will map attribute names to either True (indicating that the attribute should be kept), False (indicating that it should be dropped), or a callable (which takes the initial attribute value and returns either a final value for the attribute, or None to drop the attribute).
|
||||
|
|
@ -6,5 +6,7 @@ Customising Wagtail
|
|||
:maxdepth: 2
|
||||
|
||||
page_editing_interface
|
||||
extending_draftail
|
||||
extending_hallo
|
||||
admin_templates
|
||||
custom_user_models
|
||||
|
|
|
|||
|
|
@ -101,248 +101,10 @@ To have a feature active by default (i.e. on ``RichTextFields`` that do not defi
|
|||
def register_blockquote_feature(features):
|
||||
features.default_features.append('strikethrough')
|
||||
|
||||
The process for creating new features is described in the following sections.
|
||||
|
||||
|
||||
.. _extending_wysiwyg:
|
||||
|
||||
Extending the WYSIWYG Editor (``Draftail``)
|
||||
+++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Wagtail’s rich text editor is built with `Draftail <https://github.com/springload/draftail>`_, and its functionality can be extended through plugins.
|
||||
|
||||
Plugins come in three types:
|
||||
|
||||
* Inline styles – To format a portion of a line, eg. ``bold``, ``italic``, ``monospace``.
|
||||
* Blocks – To indicate the structure of the content, eg. ``blockquote``, ``ol``.
|
||||
* Entities – To enter additional data/metadata, eg. ``link`` (with a URL), ``image`` (with a file).
|
||||
|
||||
All of these plugins are created with a similar baseline, which we can demonstrate with one of the simplest examples – a custom feature for an inline style of ``strikethrough``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import wagtail.admin.rich_text.editors.draftail.features as draftail_features
|
||||
from wagtail.admin.rich_text.converters.html_to_contentstate import InlineStyleElementHandler
|
||||
from wagtail.core import hooks
|
||||
|
||||
# 1. Use the register_rich_text_features hook.
|
||||
@hooks.register('register_rich_text_features')
|
||||
def register_strikethrough_feature(features):
|
||||
"""
|
||||
Registering the `strikethrough` feature, which uses the `STRIKETHROUGH` Draft.js inline style type,
|
||||
and is stored as HTML with an `<s>` tag.
|
||||
"""
|
||||
feature_name = 'strikethrough'
|
||||
type_ = 'STRIKETHROUGH'
|
||||
tag = 's'
|
||||
|
||||
# 2. Configure how Draftail handles the feature in its toolbar.
|
||||
control = {
|
||||
'type': type_,
|
||||
'label': 'S',
|
||||
'description': 'Strikethrough',
|
||||
# This isn’t even required – Draftail has predefined styles for STRIKETHROUGH.
|
||||
# 'style': {'textDecoration': 'line-through'},
|
||||
}
|
||||
|
||||
# 3. Call register_editor_plugin to register the configuration for Draftail.
|
||||
features.register_editor_plugin(
|
||||
'draftail', feature_name, draftail_features.InlineStyleFeature(control)
|
||||
)
|
||||
|
||||
# 4.configure the content transform from the DB to the editor and back.
|
||||
db_conversion = {
|
||||
'from_database_format': {tag: InlineStyleElementHandler(type_)},
|
||||
'to_database_format': {'style_map': {type_: tag}},
|
||||
}
|
||||
|
||||
# 5. Call register_converter_rule to register the content transformation conversion.
|
||||
features.register_converter_rule('contentstate', feature_name, db_conversion)
|
||||
|
||||
These five steps will always be the same for all Draftail plugins. The important parts are to:
|
||||
|
||||
* Consistently use the feature’s Draft.js type or Wagtail feature names where appropriate.
|
||||
* Give enough information to Draftail so it knows how to make a button for the feature, and how to render it (more on this later).
|
||||
* Configure the conversion to use the right HTML element (as they are stored in the DB).
|
||||
|
||||
For detailed configuration options, head over to the `Draftail documentation <https://github.com/springload/draftail#formatting-options>`_ to see all of the details. Here are some parts worth highlighting about controls:
|
||||
|
||||
* The ``type`` is the only mandatory piece of information.
|
||||
* To display the control in the toolbar, combine ``icon``, ``label`` and ``description``.
|
||||
* The controls’ ``icon`` can be a string to use an icon font with CSS classes, say ``'icon': 'fas fa-user',``. It can also be an array of strings, to use SVG paths, or SVG symbol references eg. ``'icon': ['M100 100 H 900 V 900 H 100 Z'],``. The paths need to be set for a 1024x1024 viewbox.
|
||||
|
||||
Creating new inline styles
|
||||
""""""""""""""""""""""""""
|
||||
|
||||
In addition to the initial example, inline styles take a ``style`` property to define what CSS rules will be applied to text in the editor. Be sure to read the `Draftail documentation <https://github.com/springload/draftail#formatting-options>`_ on inline styles.
|
||||
|
||||
Finally, the DB to/from conversion uses an ``InlineStyleElementHandler`` to map from a given tag (``<s>`` in the example above) to a Draftail type, and the inverse mapping is done with `Draft.js exporter configuration <https://github.com/springload/draftjs_exporter>`_ of the ``style_map``.
|
||||
|
||||
Creating new blocks
|
||||
"""""""""""""""""""
|
||||
|
||||
Blocks are nearly as simple as inline styles:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.admin.rich_text.converters.html_to_contentstate import BlockElementHandler
|
||||
|
||||
@hooks.register('register_rich_text_features')
|
||||
def register_blockquote_feature(features):
|
||||
"""
|
||||
Registering the `blockquote` feature, which uses the `blockquote` Draft.js block type,
|
||||
and is stored as HTML with a `<blockquote>` tag.
|
||||
"""
|
||||
feature_name = 'blockquote'
|
||||
type_ = 'blockquote'
|
||||
tag = 'blockquote'
|
||||
|
||||
control = {
|
||||
'type': type_,
|
||||
'label': '❝',
|
||||
'description': 'Blockquote',
|
||||
# We need to tell Draftail what element to use when displaying those blocks in the editor.
|
||||
'element': 'blockquote',
|
||||
# This isn't required as the blockquote tag could be styled directly.
|
||||
# 'className': 'editor__blockquote',
|
||||
}
|
||||
|
||||
features.register_editor_plugin(
|
||||
'draftail', feature_name, draftail_features.BlockFeature(control)
|
||||
)
|
||||
|
||||
features.register_converter_rule('contentstate', feature_name, {
|
||||
'from_database_format': {tag: BlockElementHandler(type_)},
|
||||
'to_database_format': {'block_map': {type_: tag}},
|
||||
})
|
||||
|
||||
Here are the main differences:
|
||||
|
||||
* We need to configure an ``element`` to tell Draftail how to render those blocks in the editor.
|
||||
* We could use a ``className`` (say if ``element`` was ``div``) to style the blockquotes in the editor.
|
||||
* We register the plugin with ``BlockFeature``.
|
||||
* We set up the conversion with ``BlockElementHandler`` and ``block_map``.
|
||||
|
||||
That’s it! The extra complexity is that you may need to write some CSS if using a ``className`` so your blocks look good in the editor.
|
||||
|
||||
Creating new entities
|
||||
"""""""""""""""""""""
|
||||
|
||||
.. warning::
|
||||
This is an advanced feature. Please carefully consider whether you really need this.
|
||||
|
||||
Entities aren’t simply formatting buttons in the toolbar. They usually need to be much more versatile, communicating to APIs or requesting further user input. As such,
|
||||
|
||||
* You will most likely need to write a **hefty dose of JavaScript**, some of it with React.
|
||||
* The API is very **low-level**. You will most likely need some **Draft.js knowledge**.
|
||||
* Custom UIs in rich text can be brittle. Be ready to spend time **testing in multiple browsers**.
|
||||
|
||||
The good news is that having such a low-level API will enable third-party Wagtail plugins to innovate on rich text features, proposing new kinds of experiences.
|
||||
But in the meantime, consider implementing your UI through :doc:`StreamField <../../topics/streamfield>` instead, which has a battle-tested API meant for Django developers.
|
||||
|
||||
----
|
||||
|
||||
Here are the main requirements to create a new entity feature:
|
||||
|
||||
* Like for inline styles and blocks, register an editor plugin.
|
||||
* The editor plugin must define a ``source``: a React component responsible for creating new entity instances in the editor, using the Draft.js API.
|
||||
* The editor plugin also needs a ``decorator`` (for inline entities) or ``block`` (for block entities): a React component responsible for displaying entity instances within the editor.
|
||||
* Like for inline styles and blocks, set up the to/from DB conversion.
|
||||
* The conversion usually is more involved, since entities contain data that needs to be serialised to HTML.
|
||||
|
||||
To write the React components, Wagtail exposes its own React and Draft.js dependencies as global variables. Read more about this in :ref:`extending_clientside_components`. To go further, please look at the `Draftail documentation <https://github.com/springload/draftail#formatting-options>`_ as well as the `Draft.js exporter documentation <https://github.com/springload/draftjs_exporter>`_.
|
||||
|
||||
Here is a detailed example to showcase how those tools are used in the context of Wagtail.
|
||||
For the sake of our example, we can imagine a news team working at a financial newspaper.
|
||||
They want to write articles about the stock market, refer to specific stocks anywhere inside of their content (eg. $TSLA tokens in a sentence), and then have their article automatically enriched with the stock’s information (a link, a value, up or down, a sparkline).
|
||||
|
||||
The editor toolbar could contain a "stock chooser" that displays a list of available stocks, then inserts the user’s selection as a textual token. For our example, we will just pick a stock at random:
|
||||
|
||||
.. image:: ../../_static/images/draftail_entity_stock_source.gif
|
||||
|
||||
Those tokens are then saved in the rich text on publish. When the news article is displayed on the site, we then insert live market data coming from an API next to each token:
|
||||
|
||||
.. image:: ../../_static/images/draftail_entity_stock_rendering.png
|
||||
|
||||
|
||||
|
||||
Extending the WYSIWYG Editor (``hallo.js``)
|
||||
+++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
.. warning::
|
||||
**As of Wagtail 2.0, the hallo.js editor is deprecated.** We have no intentions to remove it from Wagtail as of yet, but it will no longer receive bug fixes. Please be aware of the `known hallo.js issues <https://github.com/wagtail/wagtail/issues?q=is%3Aissue+is%3Aclosed+hallo+label%3A%22component%3ARich+text%22+label%3Atype%3ABug+label%3A%22status%3AWont+Fix%22>`_ should you want to keep using it.
|
||||
|
||||
To use hallo.js on Wagtail 2.x, add the following to your settings:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
WAGTAILADMIN_RICH_TEXT_EDITORS = {
|
||||
'default': {
|
||||
'WIDGET': 'wagtail.admin.rich_text.HalloRichTextArea'
|
||||
}
|
||||
}
|
||||
|
||||
The legacy hallo.js editor’s functionality can be extended through plugins. For information on developing custom ``hallo.js`` plugins, see the project's page: https://github.com/bergie/hallo
|
||||
|
||||
Once the plugin has been created, it should be registered through the feature registry's ``register_editor_plugin(editor, feature_name, plugin)`` method. For a ``hallo.js`` plugin, the ``editor`` parameter should always be ``'hallo'``.
|
||||
|
||||
A plugin ``halloblockquote``, implemented in ``myapp/js/hallo-blockquote.js``, that adds support for the ``<blockquote>`` tag, would be registered under the feature name ``block-quote`` as follows:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.admin.rich_text import HalloPlugin
|
||||
from wagtail.core import hooks
|
||||
|
||||
@hooks.register('register_rich_text_features')
|
||||
def register_embed_feature(features):
|
||||
features.register_editor_plugin(
|
||||
'hallo', 'block-quote',
|
||||
HalloPlugin(
|
||||
name='halloblockquote',
|
||||
js=['myapp/js/hallo-blockquote.js'],
|
||||
)
|
||||
)
|
||||
|
||||
The constructor for ``HalloPlugin`` accepts the following keyword arguments:
|
||||
|
||||
* ``name`` - the plugin name as defined in the Javascript code. ``hallo.js`` plugin names are prefixed with the ``"IKS."`` namespace, but the name passed here should be without the prefix.
|
||||
* ``options`` - a dictionary (or other JSON-serialisable object) of options to be passed to the Javascript plugin code on initialisation
|
||||
* ``js`` - a list of Javascript 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
|
||||
* ``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:
|
||||
|
||||
Whitelisting rich text elements (``hallo.js``)
|
||||
++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
After extending the editor to support a new HTML element, you'll need to add it to the whitelist of permitted elements - Wagtail's standard behaviour is to strip out unrecognised elements, to prevent editors from inserting styles and scripts (either deliberately, or inadvertently through copy-and-paste) that the developer didn't account for.
|
||||
|
||||
Elements can be added to the whitelist through the feature registry's ``register_converter_rule(converter, feature_name, ruleset)`` method. When the ``hallo.js`` editor is in use, the ``converter`` parameter should always be ``'editorhtml'``.
|
||||
|
||||
The following code will add the ``<blockquote>`` element to the whitelist whenever the ``block-quote`` feature is active:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.admin.rich_text.converters.editor_html import WhitelistRule
|
||||
from wagtail.core.whitelist import allow_without_attributes
|
||||
|
||||
@hooks.register('register_rich_text_features')
|
||||
def register_blockquote_feature(features):
|
||||
features.register_converter_rule('editorhtml', 'block-quote', [
|
||||
WhitelistRule('blockquote', allow_without_attributes),
|
||||
])
|
||||
|
||||
``WhitelistRule`` is passed the element name, and a callable which will perform some kind of manipulation of the element whenever it is encountered. This callable receives the element as a `BeautifulSoup <http://www.crummy.com/software/BeautifulSoup/bs4/doc/>`_ Tag object.
|
||||
|
||||
The ``wagtail.core.whitelist`` module provides a few helper functions to assist in defining these handlers: ``allow_without_attributes``, a handler which preserves the element but strips out all of its attributes, and ``attribute_rule`` which accepts a dict specifying how to handle each attribute, and returns a handler function. This dict will map attribute names to either True (indicating that the attribute should be kept), False (indicating that it should be dropped), or a callable (which takes the initial attribute value and returns either a final value for the attribute, or None to drop the attribute).
|
||||
The process for creating new features is described in the following pages:
|
||||
|
||||
* :doc:`./extending_draftail`
|
||||
* :doc:`./extending_hallo`
|
||||
|
||||
.. _rich_text_image_formats:
|
||||
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ The configuration settings ``WAGTAILEMBEDS_EMBED_FINDER`` and ``WAGTAILEMBEDS_EM
|
|||
Registering custom hallo.js plugins directly is deprecated
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ability to enable / disable ``hallo.js`` plugins by calling ``registerHalloPlugin`` or modifying the ``halloPlugins`` list has been deprecated, and will be removed in Wagtail 1.14. The recommended way of customising the hallo.js editor is now through :ref:`rich text features <rich_text_features>`. For details of how to define a hallo.js plugin as a rich text feature, see :ref:`extending_wysiwyg`.
|
||||
The ability to enable / disable ``hallo.js`` plugins by calling ``registerHalloPlugin`` or modifying the ``halloPlugins`` list has been deprecated, and will be removed in Wagtail 1.14. The recommended way of customising the hallo.js editor is now through :ref:`rich text features <rich_text_features>`. For details of how to define a hallo.js plugin as a rich text feature, see :doc:`../advanced_topics/customisation/extending_hallo`.
|
||||
|
||||
|
||||
Custom ``get_admin_display_title`` methods should use ``draft_title``
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue