27. Richtext Extensions¶

27.1.1. Behind the scenes¶

The most tricky part of the implementation is the mapping of the dialog form fields to the editor’s document state and vice versa. Dialog forms therefore need a way to bidirectionally exchange their data with the Richtext editor. This is done by adding the extra attributes richtext-map-to and richtext-map-from or richtext-bidirectional to the form field widgets.

richtext-map-to

This extra attribute is used to map the value of one or more form field’s values to the editor’s document state. This operation is performed whenever the user clicks on the “Apply” button of the dialog form. This attribute can take three types of values:

• A key value: This is used to map the value of the given field onto to the editor’s document state with that key. This is the most basic way to map a field’s value and can only be used to map a single value.

• A functional expression: This is used to map multiple field values to the editor’s document state using a JavaScript lambda function. This snippet has access to all elements of the dialog form and must return a value to be mapped onto the editor’s document state. Accessing the values of the elements can only be achieved using elements.… inside this snippet. This is a more flexible way, because it can take the values of other fields into account, transform them or perform extra logic.

  Example: {src: JSON.parse(elements.image.dataset.fileupload).download_url} maps the download URL of an uploaded image of an input element named image to the attribute src of the editor’s document state implementing the mark extension <img src="…" />.

• The name of a function followed by empty brackets, for instance image_to_document(). This function must be an attribute of the object declared inside the extension script as explained in the previous section. It takes an HTMLFormControlsCollection as its only argument. This collection contains all the fields of the given dialog form. The function must return a plain JavaScript object which then is merged into the editor’s document state. This is the most flexible way, because it can be programmed in JavaScript. Optionally, this function can also return a Promise which must resolve to said JavaScript object. This way we can perform asynchronous operations inside this function.

myapp/tiptap-extensions/simple_image.js¶

{
    ...

    image_to_document(elements) {
        const fileupload = JSON.parse(elements.image.dataset.fileupload);
        return {
            src: fileupload.download_url,
            dataset: fileupload,
       };
    },

    ...
}

richtext-map-from

This extra attribute is used to map the editor’s document state back to the dialog form field’s value. It is applied whenever the user opens the dialog form for an existing mark or node element in the editor. This attribute can take three types of values:

• A key value: This is used to map the editor’s document state using a key and map it to the given field’ value of the dialog form.

• A functional expression: This is used to map the editor’s document state using a JavaScript lambda function. This snippet has access to all attributes of the editor’s document state and must return one or more properties or attributes of the dialog form’s field. If the field is an HTMLInputElement or HTMLSelectElement, then this lamda function usually returns an object containing {value: …}. The editor’s document state can be accessed using attributes.… inside this snippet.

  Example: {dataset: {fileupload: JSON.stringify(attributes.dataset)}} maps the value of the attribute dataset of the editor’s document state to the dataset attribute of the associated input field in the form dialog.

• The name of a function followed by brackets, for instance change_link_type(). This function must be an attribute of the object declared inside the extension script as explained in the previous section. As its first argument it takes the field of the dialog form, usually an HTMLInputElement or HTMLSelectElement. As its second argument it receives the editor’s document state for the given mark or node as a plain JavaScript object. This function then shall modify the given input element’s value or checked property, or any of its attributes.

  Example: Say, that in our CustomHyperlinkDialogForm we prefer a RadioSelect widget to select the link type. Now the problem is, that we have one radio input element for each choice. Inside our extension script we can therefore implement this mapping function:

  myapp/tiptap-extensions/custom_hyperlink.js¶

  {
      ...
  
      change_link_type(inputElement, attributes) {
          if (attributes.page && inputElement.value === "internal") {
             inputElement.checked = true;
          } else if (attributes.href && inputElement.value === "external") {
             inputElement.checked = true;
          } else {
             inputElement.checked = false;
          }
      },
  
      ...
  }
  

  When opening the dialog, this function is called for each input element of its form. Since we don’t have a single field we can map our editor’s document state value to, we must lookup the named radio input element (actually we use value for this) and set its checked property accordingly. This way we can ensure that the correct radio input element is selected when opening the dialog form.

  The return value of this function is ignored unless it’s a Promise, which suspends execution of the caller until it resolved. This way we can perform asynchronous operations inside this function.

  The widget for our choice field link_type then must be rewritten to:

  class CustomHyperlinkDialogForm(dialogs.RichtextDialogForm):
      ...
      link_type = fields.ChoiceField(
          ...
          widget=RadioSelect(attrs={'richtext-map-from': 'change_link_type()'}),
      )
  

richtext-bidirectional

A common use-case is to map the value of a dialog form field to the editor’s document state and vice versa. This can be done by using the attributes richtext-map-to="fieldname" and richtext-map-from="fieldname", where fieldname is the name of the given dialog field. A shortcut for avoiding this verbose syntax is to use the attribute richtext-bidirectional=True. This then maps the value of the dialog form field to the editor’s state using the field’s name as the key. It also maps the value of the editor’s document state back to the dialog form field using the same key. Using this attribute is only allowed if neither richtext-map-to nor richtext-map-from are set on the dialog’s field.

richtext-selection

This extra attribute is used to map the editor’s selected text to the dialog form field’s value. It is applied whenever the user selects some text and wants to convert it into a mark or node element. A ggod example is the hyperlink editor, where the user selects some text and clicks on the link button. This attribute is used to set the initial value of the dialog form field to the selected text.

27.1.2. Rendering the content¶

The internal representation of the editor is a state object containing nodes and marks. To render the content of the editor, we can use the render_richtext template tag as explained in Rendering Richtext.

For each custom extension, we must define their own rendering template. It must be named as the extension itself adding the suffix .html. The template must be placed in the project’s folder templates/richtext for nodes, or in templates/richtext/marks for marks. If the extension may contain children, the template must be able to render them recursively. Check the samples in folder formset/templates/richtext for various nodes and marks.

For our custom hyperlink extension, the template could look like this:

{% load page_url from hyperlink %}
<a href="{% if attrs.page_id %}{% page_url attrs.page_id %}{% else %}{{ attrs.href }}{% endif %}">{{ text }}</a>

This template then is used by the richtext renderer and loaded whenever an element of type custom_hyperlink is encountered.