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, the content inside a background region is not editable. You can, however, nest additional content regions inside background 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).