Wagtail: Extending the Draftail Editor Part 1 - Inline Styles

Introduction

The previous post looked at basic configuration of the Draftail rich text editor and introduced the concept of adding custom features.

In this article, I'll cover creating custom inline font styles not included by default in the Draftail rich text editor. I'll include:

• how to add tag-based styling (such as <u>)
• how to add styled <span> tags
• demonstrate using both unicode glyphs and svg paths for your toolbar icon

The examples below will create underline, larger, smaller and highlighted styles.

Part 2 covers adding block styles (i.e. styles that are applied to an entire paragraph of text, such as numbered lists) by creating alignment buttons while examining if this is the best route to take for this requirement.

Part 3 looks at one method to add inline dynamic text to your rich text block. In this example, I create a button to add FontAwesome icons to your text.

Registering Custom Inline Styles with the Draftail Editor

As mentioned in the previous article, you can add features to the built-in draftail editor through the use of Wagtail hooks.

The Inline Style Register Function

Taking the example from the documentation page, I created an inline style register function rather than repeating the same block of code with minor differences. To stop the size of the hooks file blowing out, I created a file called draftail_extensions.py for my register functions and SVG icon definitions.

• features: supplied by the register_rich_text_features hook and requires passing through
• feature_name: the name used internally by Wagtail for this feature - this is the name you use in your feature list when including it in your editor.
• description: this is the text displayed when the mouse is hovered over the toolbar button.
• type_: to be honest, I've never found any documentation for this, but it is required, so following the example on the Wagtail page, I generally just give this a meaningful uppercase word.
• tag: optional - this is the HTML element tag to be used (i.e. tag='u' will render <u>...</u>), <span> by default.
• format: optional - valid style and/or class element attribute definition (e.g. format='style="color: red; font-size: larger;"').
• editor_style: used to alter the way the formatted text is displayed in the editor, defined as a dictionary of css properties (e.g. editor_style={'color': 'red', 'font-size': 'larger'}). Not required for standard tag definitions such as <u>, but needed to instruct the editor how to display your formatted text. It will also be needed for non-standard tags which I'll go through in part 3 when creating inline dynamic text.
• label, icon: choose one of these. label will take unicode glyphs which we'll use for the underline style, while icon can take an SVG path (set for a 1024x1024px viewbox). Ignore the documentation's claim that you can use Font Awesome icons, this is no longer true. If you supply neither, the function will pass the description to the label property.
• Finally, after the declarations, are the two methods to register the plug-in and the conversion rule:

The function call above registers the plugin as an inline style feature and instructs Draftail how to render the control (i.e. the button on the toolbar).

This last chunk creates a nested dictionary with instructions on how that feature should be rendered in the editor (from_database_format) and how it should be rendered on the front end web page (to_database_format) and uses this to register the converter rule.

1. Create an underline inline style with a unicode button

In this first example, I'll use a unicode glyph as label. To add the underline style, we need a plugin that wraps the highlighted text with <u></u> tags.

In your wagtail_hooks.py, import the above function and add the following:

Once your web server reloads, the new feature will be added. Remember, to use it in your editor, 'underline' must be included in the feature list in use. Once you've done that, you'll see the button with the U̲ character. Highlight some text and click the button to get the underline style. Use the dev tools to inspect the underlined word to see how draftail renders inline styles.

2. Create inline styles for larger and smaller font with SVG buttons

Next, we can create font styles for larger and smaller text by wrapping highlighted text with a <span> tag styled with font-size:smaller; and font-size:larger;.

fa-solid fa-circle-info fa-xl These are simple 'on/off' features that size the font relative to the current font size. They do not incrementally increase and decrease the font size as the same buttons in Word do for instance.

It is possible to use a list of svg paths to define the Draftail icon. Wagtail 5 introduced custom svg icons which is the preferable way to go here.

If you're unfamiliar with this, I recommend following the instructions in the Wagtail docs. I'll just give the svg definitions here.

The two icons are: