Customizing the Rich Text Editor

The Rich Text Editor is customizable in two ways:

1. The styling that is applied to content in the editor window
2. The styles that appear in the Style pop-up menu

Preview Area Styling

To make the Rich Text Editor (RTE) truly "what you see is what you get" for your site, some customization is required. The CSS that is applied to the editor contents (called the preview area) is controlled by a separate stylesheet. To make the editor contents match your pages, you'll want to copy most of the rules from your main stylesheet into the preview stylesheet.

There are a few tricky parts to this:

1. If you have background colors or images defined in your main stylesheet, you may want to remove those when setting the preview styles for ease of editing.
2. Your styles may depend on context (if you use descendent selectors in your CSS). When you are editing the contents of a specific region, the editor preview area does not know about any context outside of that region.
3. The size of the editor window may be different from the region of the page that is being edited, so you may not want to apply fixed widths.

Your site comes preconfigured with a generic editor preview style sheet, which will set text color according to the Global Settings. The background is set to white.

To customize the styles to match your site, modify (or replace) the stylesheet webvanta-preview.css. (You can also change which stylesheet is used by changing the Global Setting system.rte.admin.EditorAreaCSS.)

The entire editor preview area is wrapped in a div, whose ID you can set by changing the global setting system.rte.admin.BodyId. By default, this is set to wrapper. This style in the webvanta-preview stylesheet defines the padding that gives some space around the text.

If the styles you want to use in the preview area depend on a parent or ancestor of the individual styles (as in #article h2), then you may want to set system.rte.admin.BodyId to the corresponding ID (article in this example) to activate those styles.

To summarize, the following process will generally give you an editor preview stylesheet that works well:

1. Create a combined stylesheet that has the CSS rules from all of your stylesheets (if you have multiple stylesheets). There's no need to include any print styles, of course.
2. Remove background colors and images from the combined stylesheet.
3. Remove any fixed widths or positions from the combined stylesheet.
4. Add a style definition for #wrapper, with the padding set to 10px.
5. Edit the webvanta-preview.css stylesheet (via Structure > CSS Files) and replace all of its contents with your combined stylesheet.
6. If you have styles that depend on a parent element via descendent rules, set the gllobal setting (via Settings >Global Settings) system.rte.admin.BodyId to the ID or classname for the parent. (You must choose one parent for all cases.)
7. Clear your browser's cache.

You should now have an RTE that displays text very similarly to your site's pages.

Providing Preset Styles

To preserve the integrity of your design, you don't want your client choosing fonts, colors, or sizes; you want them choosing from styles that you have defined for them.

You can configure the RTE to provide exactly the styles you want in the Styles drop-down menu. This configuration is done via an XML file, whose path is in the Global Setting system.rte.admin.StylesXmlPath (set to webvanta-editor-styles.xml by default).

Your site initially has a few example styles. To replace, modify, or add styles, edit the XML file by choosing Structure > Feeds & XML Files from the control panel menu.

This XML file is quite simple, but you do need to get the syntax correct, and to understand how this information is used. Here is an example file:

<?xml version="1.0" encoding="utf-8" ?>
<Styles>
  <Style name="Large Headline" element="h1" >
    <Attribute name="class" value="large_headline" />
  </Style>
  <Style name="Large Body Copy" element="p" >
    <Attribute name="class" value="large_body" />
  </Style>
  <Style name="Highlighted Text" element="span" >
    <Attribute name="class" value="highlighted_text" />
  </Style>
  <Style name="Image on Left" element="img" >
    <Attribute name="class" value="image_left" />
  </Style>
</Styles>

The file consists of a single Styles element, which includes any number of Style elements. Each Style element must specify a name, which is what will appear in the Styles menu of the RTE, and an element, which is the HTML element to which the style will be applied.

Within each Style element, you can have any number of attributes. We recommend having only one attribute, which is the CSS classname to be applied. You can add other attributes, and they will be applied as inline styles, but that's probably not what you want; you want just a CSS class applied, so that your stylesheet will determine the styling.

In the examples above, if the user selects the style "Large Headline" from the Styles menu in the RTE, the selected text will be wrapped in an H1 element with the class "large_headline" applied:

<h1 class="large_headline">Text that the user selected</h1>

This style will be applied to the entire text element, even if only part of the text is selected. If that text was previously wrapped in an h2 or a p tag or whatever, the tag will be changed to a h1 tag, because that is what was specified in this Style definition.

If you want to specify styles that apply only to selected words, rather than to the entire text element, specify the element in the Style definition as "span", as shown in the third style of the example above. If you specify the element as "span", then only the selected text is affected. For example, if the original text was:

<p>This is a line of text.</p>

And the user highlighted the word "line" and chose Highlighted Text from the Styles menu, then the markup would be changed to:

<p>This is a <span class="highlighted_text">line</span> of text.</p>

The items that appear in the Styles drop-down list in the RTE are context-sensitive, based on the element selected. If text is selected, than all styles that specify text elements, such as h1, h2, p, etc., will be shown. If an image is selected, then only styles that specify an img element will be shown.