Rich-Text Elements

Brightspot’s Rich-Text Editors accommodate custom rich-text elements, such as embedded videos, image galleries, or pull quotes. For example, the following illustration is an example of a rich-text element rendered as a pull quote. The element contains typeface, alignment, and a left border.

../../../_images/rich-text-element.svg

The following steps outline how to design rich-text elements and attach them to the rich-text editor’s toolbar. Although the steps are specific to the pull quote example, you can apply them to any custom rich-text element.

Step 1: Implement a Rich-Text Element’s Model

Save the Model in your project’s src/main/java/ directory.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
package content.article;

import com.psddev.cms.db.RichTextElement;
import com.psddev.dari.db.Recordable;
import com.psddev.dari.util.StringUtils;
import java.util.Map;

@Recordable.DisplayName("Pull Quote")
@RichTextElement.Tag(
    value = "quote",
    preview = true,
    block = false,
    root = true,
    menu = "Enhancement")
public class PullQuoteRichTextElement extends RichTextElement {

    @Required
    private String quote;

    public String getQuote() {
        return quote;
    }

    public void setQuote(String quote) {
        this.quote = quote;
    }

    @Override
    public Map<String, String> toAttributes() {
        return null;
    }

    @Override
    public void fromAttributes(Map<String, String> attributes) {
    }

    @Override
    public String toBody() {
        return getQuote();
    }

    @Override
    public void fromBody(String body) {
        setQuote(StringUtils.unescapeHtml(body));
    }

}

In the previous listing—

  • Line 8 specifies that the rich-text element appears as Pull Quote in the rich-text toolbar.

  • Lines 9–14 specify presentation aspects of the rich-text element:

    • The Styleguide files use the value element for creating the View. In this snippet, the Styleguide files must provision the rich-text element using the identifier quote.

    • In the toolbar, the rich-text element appears under the menu item Enhancement.

      ../../../_images/pull-quote-menu-button.svg

      Quote Element Under Enhancement Toolbar Menu

    For information about the @RichTextElement.Tag annotation, see @RichTextElement.Tag.

  • The overridden methods extend from the RichTextElement class. In particular, the fromBody method in line 43, which calls StringUtils.unescapeHtml, ensures that Brightspot stores unescaped HTML. For example, without this method, Brightspot stores <b>bold text</b> as &lt;b&gt;bold text&lt;/b&gt;.

Step 2: Attach Rich-Text Element to Toolbar

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
package content.article;

import java.util.Arrays;
import java.util.List;

import com.psddev.cms.rte.RichTextToolbar;
import com.psddev.cms.rte.RichTextToolbarItem;
import com.psddev.cms.rte.RichTextToolbarStyle;

public class CustomRichTextToolbar implements RichTextToolbar {

    @Override
    public List<RichTextToolbarItem> getItems() {
        return Arrays.asList(
            RichTextToolbarStyle.BOLD,
            RichTextToolbarStyle.ITALIC,
            RichTextToolbarStyle.UNDERLINE,
            RichTextToolbarStyle.LINK,
            RichTextToolbarStyle.ELEMENTS);
    }

}

In the previous snippet, line 20 attaches all customized rich-text elements to the toolbar. See the illustration Quote Element Under Enhancement Toolbar Menu.

Step 3: Create Styleguide Files

Under your project’s styleguide/ directory, create Styleguide files for each field appearing in the rich-text element. For example, if a field body is typed as a rich-text field, then the Styleguide files must provide layout (Handlebars), data (JSON), and styling (Less) for the field body. As a best practice, ensure each file’s path and base name correspond to the rich-text Model. The following example provides an illustration for Styleguide files corresponding to the Model PullQuoteRichTextElement developed in Step 1.

../../../_images/rich-text-styleguide-files.svg

For information about creating Styleguide files, see Getting Started.