Rich Text Editor (RTE) Setup

RTEs are more effective/productive for authors when they are configured properly for the specific type of content the author is managing. A properly and effectively configured RTE has the right styles, menu options and so on. Every RTE in the system can have a different look and feel, different editing/menu options, available styles, components and other configurations. You can also SHARE setups between similar RTEs in your project. This document will help you understand how to configure RTEs in Crafter Studio.

Common Configurations for Effective RTEs

  1. The rich text editor’s width should be set to the same width as the region it is intended to edit
  2. Site style sheet is imported
  3. Site styles are being applied appropriately to the markup in the RTE. Not that sometimes styles in CSS are so aggressively specified that the RTE cannot pick them up.
  4. Formats and styles are configured to match the part of the site being edited
  5. Toolbar is configured with only what is required for the specific use case (reducing options makes it easier for editors)
  6. If plugins like insert component, insert smart table and so on are enabled it should be fully configured.

What Out-of-the-Box Functionality Does Crafter Studio’s RTE Support?

Our RTE is based on TinyMCE (https://www.tinymce.com/) and can leverage all configurations and plugins designed for the TinyMCE editor. You can find the documentation for these configurations and settings here: https://www.tinymce.com/docs/configure

Crafter Studio Specific Extensions

The list of Crafter Studio specific extensions is available in Crafter Studio’s git repo.

To see an example, the out of the box blueprints Empty and Website_Editorial uses the Insert Image specific extensions which enables the user to insert an image from 1 or more data sources, which replaces the TinyMCE out of the box image plugin.

In the blueprints, in order to use the Insert Image extension, add managedImage inside the tag <toolbarItems1>. Inside the tags <rteModules>, insert <module>insert-image</module>. (See the sample RTE Setup configuration file in the section below.)

Once the RTE Setup is attached to an RTE in a form, you can now specify multiple data sources for the image. In the image below, we have two data sources enabled for the RTE image insert.

RTE Setup - Insert Image Extension Example :align: center

Creating an RTE Setup

The RTE’s configuration file looks like this:

{REPOSITORY_ROOT}/sites/SITENAME/config/studio/form-control-config/rte/rte-setup.xml
 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
<config>
    <setup>
        <id>generic</id>
        <rteStylesheets>
            <link>
                <loadFromPreview>true</loadFromPreview>
                <url>/static-assets/css/style.css</url>
            </link>

            <link>
                <appliesToChannel>iphonev,iphoneh</appliesToChannel>
                <loadFromPreview>true</loadFromPreview>
                <url>/static-assets/mobile/css/libs/jquery.mobile-1.0.min.css</url>
            </link>
        </rteStylesheets>

        <toolbarItems1>formatselect,|,bold,italic,underline,strikethrough,|,sub,sup,charmap,|,outdent,indent,blockquote,|,justifyleft,justifycenter,justifyright,justifyfull,|,bullist,numlist,|,managedImage,link,unlink,anchor,|,code,|,undo,redo</toolbarItems1>
        <toolbarItems2></toolbarItems2>
        <toolbarItems3></toolbarItems3>
        <toolbarItems4></toolbarItems4>

        <rteLinkStyles>
            <style>
                <name>Standard</name>
                <value>standard</value>
            </style>
            <style>
                <name>Hidden</name>
                <value>hidden</value>
            </style>
            <style>
                <name>Button</name>
                <value>mediumButton</value>
            </style>
        </rteLinkStyles>

        <!-- widgets -->
        <rteWidgets>
        </rteWidgets>

        <rteModules>
            <module>insert-image</module>
            <module>channel</module>
        </rteModules>
    </setup>
</config>

You can access the RTE Configuration file by going to the Sidebar then clicking on Site Config. In the Site Config, click on Configuration, then from the dropdown list, select RTE Configuration

RTE Setup - Open RTE Configuration File in Studio :align: center

Inside the <config> tag, there can be multiple <setup> tags. Each represents a possible RTE configuration that can be specified to be used by a RTE control. Each possible RTE configuration contains:

  • An <id> tag with the name that must be specified for an RTE control to use this configuration.

  • <rteStylesheets> tag that contains multiple <link> tags. Each link tag represents a link to a CSS stylesheet that will be used so that the RTE matches the look and feel of the site.

    <link>
            <appliesToChannel>iphonev,iphoneh</appliesToChannel>
                    <loadFromPreview>true</loadFromPreview>
                    <url>/static-assets/mobile/css/libs/jquery.mobile-1.0.min.css</url>
    </link>
    
    • <appliesToChannel> is optional. If it’s missing, it will apply to every channel.
  • <toolbarItems1> and similar contain the toolbar buttons in the RTE. You can specify any plugin as named in Tiny MCE Plugins List. They will be featured in the same order as specified here, and separators can be specified with |.

  • <rteModules> is used to specify which external plugins to include, the list of which is available in Crafter Studio’s git repo.

For example, to use the edit-html editor, you’ll have to add <module>edit-html</module> to <rteModules> and place edithtml somewhere in a toolbar <toolbarItems1> similar to this link,unlink,anchor,|,edithtml,|,undo,redo</toolbarItems1>

Attaching an RTE in a Form to an RTE Setup

To attach an RTE setup to an RTE in a form, open the content type that you want to add an RTE to, then go to the Properties Explorer and click on RTE Configuration and type in an RTE setup name.

RTE Setup - Add an RTE in the Form :align: center

In the image below, the RTE setup name used is generic. Please see the section above on how to create an RTE Setup, where the example shows an RTE Setup named generic.

RTE Setup - Attach an RTE in a Form to an RTE Setup :align: center

Todo

Update images