Customizing Visual Editor

Learn how to customize C1 Visual Editor by adding, removing or modifying buttons on its toolbar and items in its style and class selectors.

C1 Visual Editor is customizable and you can adapt some of its appearance to your needs.

You can add, remove or customize buttons on the editor's toolbar as well as items in the style or class selector.

The Visual Editor is styled with style sheets (CSS) and uses a number of images for its GUI buttons. The appearance and behavior of the editor itself is set via its configuration file.

Please examine the folder on your website: ~\Frontend\Config\VisualEditor. It contains two folders: Images and Styles for its images and style sheets respectively and the configuration file - common.xml

What are "formats"?

Visual Editor uses "formats" to apply styles to the objects in the content. There are 3 types of objects you can apply a style to:

  • An inline selection
    Example: part of a text
    The format for this object wraps up the inline selection with the tag and optionally style class specified. The inline format can be only represented as a button. The button gets enabled only if the user makes an explicit selection, for example, one or more characters in a text.
  • A block selection
    Example: a paragraph (<p>)
    The format for this object wraps up the block selection with a tag and optionally a style class specified. The block selection can be represented as both a button and an item in the style selector. Normally, the button and the item are always enabled as long as the cursor is within the block element (no need to select the entire element.)
  • An element selection (selector)
    Example: <img/>
    The format for this object adds the specified class to the element (<img class="no-border" />). The element selection can be represented as both a button and an item in the class selector.

What are "groups" and "radio groups"?

Each format must be defined within either a group or a radio group. The latter is used to group mutually exclusive formats and is similar to radio buttons in their behavior.

The formats that belong to the same group or radio group will appear separated from other buttons with a separator (|).

The formats defined for block selections will appear in the style selector. The formats for element selections will appear in the class selector.

How to get started with customization?

Normally, you should add a style to an existing or new cascade style sheet file (e.g. Styles/common.css), add an image to Images folder for a button image (if buttons are used) and add a "format" to the common.xml.

If you use styles from style sheets not listed in <styles/> in common.xml, add them manually:

<visualeditor> 
  <styles> 
    <style file="styles/custom.css" /> 
  </styles> 
</visualeditor>

(Alternatively, import them into a style sheet already listed in common.xml with the @import directive.)

Note: Adding a styles sheet with used styles to common.xml will only make applied formats visible in Visual Editor. To make them visible in Preview or on published pages in a web browser, you should also link to the style sheet in corresponding C1 page templates.

The formats should be placed within either <group> or <radiogroup> elements, the latter - within the <format/> element.

<visualeditor> 
  <formats> 
    <group> 
      <format /> 
    </group> 
    <radiogroup> 
      <format /> 
    </radiogroup> 
  </formats> 
</visualeditor>

You use the inline, block or selector attributes of a <format/> element to specify specific markup elements such as <p>, <h1>, <img>. For example, if you want to use a <h1> to format a block of text, you should specify it as 'block="h1"' in the <format/> element.

If the format also uses a style class with the markup element, you should specify the class in the classes attribute. For example,if you want to wrap some inline text with a <span class="strikethrough">, you should specify it as 'inline="span" classes="strikethrough"'.

What you need to get started:

  • A style in CSS (redefined for element or defined as a class for the element). This is what your format is. This should include the name of the styled element (e.g. <h1>) and if applicable, the class (e.g.".nice")
  • An ID for your format
  • A label and optionally a tooltip text (notes) for the button/item
  • An image if necessary (quite expected for a button)

Note: You should at least specify either the label or the image for the button or the item to appear in Visual Editor.

Visual Editor comes with a number of predefined styles for most common elements such as <h1> or <p>. However, you can override them and use your own.

Note: You should reload the console or clear the cache and reopen the page to see the changes instantly.

For specific scenarios please go on to read about: