To tell Surreal which parts of your page are OK to edit, you’ll need to add a unique id and the editable class to each section. Surreal will provide the appropriate editing tool depending on the type of element you’ve enabled. There is no limit to the number of editable regions a page can have.

Syntax

Here is an example of Surreal’s editable syntax:

<div id="my-content" class="editable">
    <p>Your content goes here</p>
</div>

The id attribute is also required for internal purposes. If your element already has a class applied to it, you can still make it editable by separating each one with a space:

<div id="my-content" class="anotherClass editable">

Supported elements

Most designers find it easy to use div elements for large content regions (or td elements for table-based layouts). You can also make other types of elements editable including h1–h6, img, p, span, and many more. You can even use HTML5 elements such as header, footer, article, section, nav, etc.

Unsupported elements

The following elements do not directly support the editable class. They can, however, exist inside of a supported element such as a div.

• a
• table
• tr

Images

Images can be made editable using the following syntax:

<img src="image.jpg" alt="Description" id="image-id" class="editable">

If you specify a width and height attribute, the CMS will maintain the width, height, and aspect ratio when the image is replaced:

<img src="image.jpg" alt="Description"
    width="320" height="240" id="image-id" class="editable">

Plain-text editing

You can force plain-text editing on a content region by using the editable-text class. This will disable the editor and provide a simple textarea for editing:

<div id="my-content" class="editable-text">

Editable guides

The Live Editor draws dashed outlines around editable regions on hover and focus. The guides are dark by default, but you can configure them to appear lighter by adding a data- attribute to regions with dark backgrounds:

<div id="my-content" class="editable" data-cms-outline="light">

Regions with floated elements

When defining editable regions, avoid floating interior containers. This makes it impossible for the CMS to accurately detect the height of the editable element:

<div class="editable" id="my-region">
    <div style="float: left;">
        ...your content here...
    </div>
</div>

If you do need to use this kind of structure, you can apply a CSS rule so the CMS can still calculate the correct height of the region:

.clearfix:after {
    content: ' ';
    display: block;
    height: 0;
    clear: both;
}

Then simply add the clearfix class to your region:

<div class="editable clearfix" id="my-region">
    ...
</div>

Block-level Elements in Links

Putting block-level elements inside a link <a> is valid in HTML5, but it's not supported in content regions due to technical limitations.

<div class="editable" id="my-region">
    <!-- Not supported! -->
    <a href="#">
        <h3>Lorem Ipsum</h3>
        <p>Lorem ipsum dolor...</p>
    </a>
</div>

This will result in the <h3> and <p> tags being removed.

Compatibility with other services

Surreal also supports the following editable classes to make migrating from another service as painless as possible:

• cushycms
• cushycms-text
• clienteditor
• clienteditor-text
• cms-editable