Content Regions

Content regions are defined by adding an id and the cms-editable class to an HTML element. Surreal CMS will provide an appropriate editor based on the type of element you've enabled.

<div id="content" class="cms-editable">
  <!-- Everything inside is editable -->
</div>

Almost any HTML element can be turned into a content region, and you can have as many as you want on a page. However, there are some thing you should bear in mind:

All content regions must have a unique id attribute.
Don't put <script> or other JavaScript code in content regions.
Don't put server-side code in content regions (e.g. PHP, ASP, etc.).
Don't make elements editable if they contain important layout or structural markup.
Make sure to disable scripts that modify things in content regions.
By design, the <body> element cannot be made editable.

Block Regions

Block regions are the most common type of region. They receive a full toolbar and allow the most flexibility for writing content.

<div id="my-div" class="cms-editable">
  <!-- Block region -->
</div>

Enabling any of these elements will result in a block region: address, article, aside, blockquote, dd, div, dt, fieldset, figure, footer, header, hgroup, li, main, nav, ol, section, td, th, ul

Inline Regions

Inline regions are more restrictive than block regions since they can't contain certain element such as headers, paragraphs, and lists. As such, they receive a more limited toolbar.

<span id="my-span" class="cms-editable">
  <!-- Inline region -->
</span>

Enabling any of these elements will result in an inline region: abbr, acronym, b, big, caption, cite, code, del, dfn, em, figcaption, h1, h2, h3, h4, h5, h6, i, insert, kbd, mark, p, q, s, samp, small, span, strong, sub, sup, tt, var

Image Regions

Image regions are images that occur as independent content regions.

<img
  id="my-image"
  class="cms-editable"
  src="image.png"
  alt="..."
>

The only element that will result in an image region is <img>.

Link Regions

Link regions are links that occur as independent content regions.

<a
  id="my-link"
  class="cms-editable"
  href="page.html"
>
  Click me
</a>

The only element that will result in a link region is <a>.

Warning

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

Background Regions

Background regions let you change an element's background color and image. To create a background region, add data-type="background" to any block region or inline region element.

The element can also have a style attribute with the background-color and/or background-image properties. If omitted, these properties will be applied when the background is modified in the editor.

<div
  id="my-bg"
  class="cms-editable"
  data-type="background"
  style="background-color: #08d;"
>
  <!-- Background region -->
</div>

Tip

By design, a background region's content is not editable. You can, however, nest additional content regions inside background regions. However, at this time, you cannot nest background regions inside of other content regions.

Gallery Regions

Gallery regions work just like regular galleries, except they are stand-alone content regions that can't be removed from the page. They are also configured with slightly different data- attributes.

To create a gallery region, add data-type="gallery" to any block region element.

<div
  id="my-gallery"
  class="cms-editable"
  data-type="gallery"
>
  <!-- Gallery images here -->
</div>

Gallery images must use the syntax below. Avoid adding additional elements, classes, and attributes, as they will be removed when the gallery is parsed.

<a href="uploads/image.jpg">
  <img
    src="uploads/thumbnails/image-256x256.jpg"
    alt="Description"
    data-caption="Caption"
  >
</a>

Thumbnails are automatically generated when images are added to the gallery. They will be stored in the [uploads]/thumbnails/ folder on your server.

The following data- attributes can be used to control how thumbnails and other gallery features work.

Attribute	Description	Default
`data-thumbnail-width`	The desired width of thumbnails.	`256`
`data-thumbnail-height`	The desired height of thumbnails.	`256`
`data-thumbnail-resize`	How to resize thumbnails. `fit` – proportionally resize thumbnails to be no larger than the specified dimensions. `trim` – proportionally resize thumbnails to the exact dimensions and trim the remaining overflow.	`fit`
`data-captions`	Captions are stored in each image's `data-caption` attribute. They're intended to be used with lightbox-style galleries. If you don't need them, set this to `false`.	`true`
`data-links`	A link to the full size image will be wrapped around each thumbnail. If you don't want your thumbnails wrapped in links, set this to `false`.	`true`

Tip

If your gallery region is a <ul> or <ol>, gallery images will be wrapped in <li> elements.

Text Regions

In some cases, you might only want plain-text in a content region. This can achieved by adding data-type="text" to any block region or inline region.

<div
  id="my-text"
  class="cms-editable"
  data-type="text"
>
  <!-- Plain-text region -->
</div>

Note

For usability purposes, line breaks <br> are still permitted in plain-text regions.

Using Absolute URLs

By default, Surreal CMS outputs relative links in content regions. If you need absolute links instead, add data-urls="absolute" to your content regions.

<div
  id="content"
  class="cms-editable"
  data-urls="absolute"
>
  <!-- URLs in this region will be absolute -->
</div>

This can be useful when you have includes that occur in various subdirectories where relative URLs won't work.

Legacy Classes

The following legacy classes are supported for compatibility purposes, but are considered deprecated. For all new websites, you should use the corresponding cms-* class instead.

Legacy Class	New Syntax
`editable` `cushycms` `cushycms-wysiwyg` `clienteditor` `clienteditor-wysiwyg`	`class="cms-editable"` Standard content regions.
`editable-text` `cushycms-text` `clienteditor-text`	`class="cms-editable" data-format="text"` Plain text content regions.
`editable-gallery`	`class="cms-editable" data-type="gallery"` Gallery regions.
`uneditable`	`class="cms-lock"` Lockable elements (previously known as uneditables).