Skip to main content

Rich-text elements

Brightspot’s rich-text editor accommodates 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.

Rich-text element.png

Editing lifecycle of rich-text elements​

Subclasses of RichTextElement can implement the callbacks required for editing rich-text elements.

  • Inside the rich-text editor, clicking Edit fires two callbacks:

    • RichTextElement#fromBody to populate the editing widget’s Link Text field and the Main tab of the Link field.
    • RichTextElement#fromAttributes to populate the editing widget’s Attributes field in the Advanced tab.

  • Inside the editing widget, clicking Save & Close fires two callbacks to create a traditional HTML link of the form <a href="value" otherattribute="othervalue">link text</a>:

    • RichTextElement#toBody to retrieve the link text from the editing widget’s Link Text field.
    • RichTextElement#toAttributes to retrieve the link’s attributes from the editing widget’s Attributes field in the Advanced tab.

    Rich-text element lifecycle

The following snippet describes the interaction between the rich-text element and the editing widget.

showLineNumbers {8,10,21,26,31,48}
1
import com.psddev.cms.db.RichTextElement;

2
import com.psddev.dari.util.CompactMap;

3
import com.psddev.dari.util.StringUtils;

4


5
public class AnotherLinkRichTextElement extends RichTextElement {

6


7
    @Required

8
    private Link link;

9


10
    private String linkText;

11


12
    public String getLinkText() {

13
        return linkText;

14
    }

15


16
    public void setLinkText(String linkText) {

17
        this.linkText = linkText;

18
    }

19


20
    @Override

21
    public void fromBody(String body) {

22
        setLinkText(StringUtils.unescapeHtml(body));

23
    }

24


25
    @Override

26
    public String toBody() {

27
        return getLinkText();

28
    }

29


30
    @Override

31
    public void fromAttributes(Map<String, String> attributes) {

32
        List<Attribute> createdAttributes = attributes.keySet()

33
                .stream()

34
                .map(key -> {

35
                    Attribute attribute = new Attribute();

36
                    attribute.setName(key);

37
                    attribute.setValue(attributes.get(key));

38


39
                    return attribute;

40


41
                })

42
                .collect(Collectors.toList());

43


44
        link.setAttributes(createdAttributes);

45
    }

46


47
    @Override

48
    public Map<String, String> toAttributes() {

49
        Map<String, String> htmlAttributes = new CompactMap<>();

50
        link.getAttributes()

51
                .forEach(attribute -> htmlAttributes.put(attribute.getName(), attribute.getValue()));

52
        return htmlAttributes;

53
    }

54
}
  • 8. Declares a Link field that contains the attributes in an HTML <a> element.
  • 10. Declares a field, getter, and setter for the link text (the text inside an HTML <a> element.
  • 21. Populates the field Link Text in the editing widget, unescaping any escaped HTML entities that may have been received from the rich-text element.
  • 26. Retrieves the value in the field Link Text, and uses it as the link text when constructing an HTML <a> element.
  • 31. Reads the attribute map passed from the rich-text element and populates the Attributes list in the editing widget's Advanced tab.
  • 48. Reads the Attributes list in the editing widget's Advanced tab, and uses it to construct the attributes in an HTML <a> element.

Deploying a rich-text element​

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 pull quotes, you can apply them to any custom rich-text element.

Step 1: Extend a rich-text element

All custom rich-text elements extend from RichTextElement.

showLineNumbers {5,6,25}
1
import com.psddev.cms.db.RichTextElement;

2
import com.psddev.dari.db.Recordable;

3
import com.psddev.dari.util.StringUtils;

4


5
@Recordable.DisplayName("Pull Quote") 1

6
    @RichTextElement.Tag( 2

7
    value = "quote",

8
    preview = true,

9
    block = false,

10
    root = true,

11
    menu = "Enhancement")

12
public class PullQuoteRichTextElement extends RichTextElement {

13


14
    @Required

15
    private String quote;

16


17
    public String getQuote() {

18
        return quote;

19
    }

20


21
    public void setQuote(String quote) {

22
        this.quote = quote;

23
    }

24


25
    @Override 3

26
    public Map<String, String> toAttributes() {

27
        return null;

28
    }

29


30
    @Override

31
    public void fromAttributes(Map<String, String> attributes) {

32
    }

33


34
    @Override

35
    public void fromBody(String body) {

36
        setQuote(StringUtils.unescapeHtml(body));

37
    }

38


39
    @Override

40
    public String toBody() {

41
        return getQuote();

42
    }

43


44
}

  • 5. Specifies the rich-text element displays as a pull quote in the rich-text toolbar.

  • 6. Specifies the presentation aspects of the rich-text element:

  • The theme's data files use the value element for creating the view. In this snippet, the data files must provision the rich-text element using the identifier quote.

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

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

  • 25. Overrides the methods toAttributes, fromAttributes, fromBody, and toBody. These methods provide the interface between the rich-text element and the associated editing widget. For details, see Editing lifecycle of rich-text elements.

Step 2: Attach rich-text element to toolbar

showLineNumbers {8}
1
import com.psddev.cms.rte.RichTextToolbar;

2
import com.psddev.cms.rte.RichTextToolbarItem;

3
import com.psddev.cms.rte.RichTextToolbarStyle;

4


5
public class CustomRichTextToolbar implements RichTextToolbar {

6


7
    @Override

8
    public List<RichTextToolbarItem> getItems() { 1

9
        return Arrays.asList(

10
            RichTextToolbarStyle.BOLD,

11
            RichTextToolbarStyle.ITALIC,

12
            RichTextToolbarStyle.UNDERLINE

13
            RichTextToolbarStyle.ELEMENTS);

14
    }

15


16
}
  • 8. Attaches all custom rich-text elements to the toolbar.

Step 3: Create theme files

Under your project’s styleguide/ directory, create 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 theme’s files must provide the template, data file, and styling for the field body. As a best practice, ensure each file’s path and base name correspond to the rich-text element’s class. The following example provides an illustration for theme files corresponding to the class PullQuoteRichTextElement developed in Step 1.

showLineNumbers
1
./

2


3
└── <root>

4


5
            ├── src |

6


7
                       └── main |

8


9
                                  └── java |

10


11
                                            └── brightspot |

12


13
                                                       └── content |

14


15
                                                                  └── article |

16


17
                                                                             └── PullQuoteRichTextElement.java

18


19
             └── styleguide

20


21
                        └── content

22


23
                                   └── article

24


25
                                              ├── PullQuoteRichTextElement.hbs

26


27
                                              ├── PullQuoteRichTextElement.json

28


29
                                              └── PullQuoteRichTextElement.less

For information about creating theming files, see Theme guide.

See also:

Storage of rich-text elements​

Brightspot stores rich-text elements in XML format, similar to the following:

showLineNumbers
1
{

2
  "caption": "Here is a link <a href=\"http://www.brightspot.com/\" target=\"_blank\" cursor=\"wait\" type=\"text/html\" >Brightspot</a>."

3
}

The element and attribute names you can use in a custom rich-text element are arbitrary, so you can design rich-text elements to fit your publishing needs. You then implement runtime parsers in view models that extract the elements and attributes from the database and populate the view.