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
<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
- Don't put
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 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,
nav, ol, section, td, th, ul
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 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
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
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 let you change an element's background color and image. To create a background
data-type="background" to any block region or inline region element.
The element can also have a
style attribute with the
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>
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 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
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.
data- attributes can be used to control how thumbnails and other gallery
||The desired width of thumbnails.||
||The desired height of thumbnails.||
||How to resize thumbnails.
||Captions are stored in each image's
||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
If your gallery region is a
gallery images will be wrapped in
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>
For usability purposes, line breaks
<br> are still permitted in
By default, Surreal CMS outputs relative links in content regions. If you need absolute links instead,
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.
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|
Standard content regions.
Plain text content regions.
Lockable elements (previously known as uneditables).