Surreal CMS • A Simple, Cloud-based CMS

Documentation

Integration

Supported DOCTYPEs

For maximum compliance with W3C standards, it is recommended to use either the XHTML Transitional DOCTYPE or the HTML5 DOCTYPE. In truth, you can use any DOCTYPE you want, but you may experience non-critical validation errors on occasion.

For your convenience, the DOCTYPE declaration for XHTML Transitional is: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

The DOCTYPE declaration for HTML5 is: 

<!DOCTYPE html>

Character Encoding

Surreal publishes content in UTF-8 format. UTF-8 is capable of representing every character in the Unicode character set, including those from many different alphabets. If you publish a page and notice strange characters appearing here and there, chances are your pages are not being served as UTF-8.

Setting UTF-8 with Meta Tags

To tell browsers to use UTF-8 on your pages, place the following into the head section of your pages: 

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

For your convenience, Surreal will automatically try to update your character encoding during publishing if it detects that it hasn’t been set to UTF-8.

Setting UTF-8 with .htaccess

In rare cases, your server may be configured to serve pages as ISO-8859-1 (or another type of encoding) even if you have the correct meta tag. If your server supports .htaccess files, you can add the following line to override this setting: 

AddDefaultCharset UTF-8

This line should go inside your .htaccess file. If you don’t see this file in your home directory, you can simply create it using a text editor.

ASP.NET Users

Even if your page has the UTF-8 meta tag, your pages may still be served incorrectly if your globalization settings are incorrect or missing. Make sure that you have the following attributes in your web.config file: 

<globalization
    requestEncoding="utf-8"
    responseEncoding="utf-8"
    fileEncoding="utf-8" />

ColdFusion Users

If you’re still seeing encoding issues even with the correct meta tag, try adding this to the top of the affected pages: 

<cfprocessingdirective pageencoding="utf-8">

Page Properties

Surreal lets you edit the title, description, and keywords of each page to enhance SEO. To enable this feature, make sure the following elements appear inside the head section of your pages: 

<title>Your Page Title</title>
<meta name="description" content="..." />
<meta name="keywords" content="..." />

If one of these elements is missing from your page, you will not be able to edit it in Surreal. If you don’t want clients editing this information, you can disable their access to this feature by adjusting their privileges.

Content Regions

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 required in V4 and serves as a page label in the CMS. 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">

Refrain from nesting editable regions or using duplicate id attributes on the same page, as this will trigger a warning in the CMS and you won’t be able to edit the affected regions.

If you have editable elements without an id, Surreal will automatically add them in sequential order starting with untitled-region-1 or included-region-1.

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, 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.

Making Images Editable

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" />

This only applies to images that are directly editable. Images inside other editable regions will be editable through the rich-text editor.

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">

JavaScript in Editable Regions

The CMS will remove script elements that it finds in editable regions for technical and security reasons. Because of this, it’s important to make sure that you don’t have any scripts inside of your content regions. Scripts can safely be placed in the head section of your pages, immediately before the closing body tag, or anywhere outside of your editable regions.

In addition, scripts in the body of your page will be disabled in the Live Editor. Scripts in the head section will not be disabled.

Compatibility with Other Services

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

Repeatable Regions

Repeatable regions are chunks of content that can be repeated, reordered, and deleted. They are particularly useful for things like articles, event listings, photo galleries, or anything else that has a dynamic number of items requiring the same HTML structure. There is no limit to the number of repeatable regions you can have.

Syntax

To define a repeatable region, simply add the repeatable class to any element inside of an editable region. The code in the following example will allow you to add, remove, and reorder additional regions of content that share the exact same structure as the original, including all its classes: 

<div id="my-content" class="editable">
    <div class="repeatable">
        <h1>Article Title</h1>
        <p class="article-date">Posted on August 20, 2010</p>
        <p>Lorem ipsum dolor sit amet...</p>
    </div>
</div>

Repeatable regions should not contain id attributes, as they cannot be repeated without compromising their uniqueness. Always use class attributes instead.

Grouping

Repeatable regions are grouped by their siblings. That is, if a region comes immediately before or after another region, they will be considered part of the same group. By design, regions can only be moved up or down within the same group.

The Repeatable Regions Toolbar

Repeatable regions can be manipulated using the toolbar in the editor:

The Repeatable Regions Toolbar

The buttons, in their respective order, are Add Region, Delete Region, Move Region Up, and Move Region Down. They will only be enabled when the cursor is inside of a repeatable element. To save time, you can use the following keyboard shortcuts while working with repeatable regions: alt+up, alt+down, alt++, alt+-.

Relative & Absolute URLs

There are two basic types of links: relative and absolute. A relative link points to a file that is relative to the current page, while an absolute link points to a file using a full URL, including the protocol and domain: 

<!-- Relative URL -->
<a href="../index.html">Home</a>

<!-- Absolute URL -->
<a href="http://www.example-website.net/index.html">Home</a>

As you edit, the CMS generates relative URLs for links. In some cases, this may not be desirable. To tell the CMS to format your links as absolute URLs, you can add data-urls="absolute" to your editable region: 

<div id="nav" class="editable" data-urls="absolute">
	<ul>
		<li><a href="http://example-website.net/">Home</a></li>
		<li><a href="http://example-website.net/about">About</a></li>
		<li><a href="http://example-website.net/contact">Contact</a></li>
	</ul>
</div>

In most cases, you won’t need to worry about this. However, if you have pages in various folder levels of your site that share the same include file, you’ll most likely want to use absolute URLs in the include file to ensure that the links always point to the right place.

Note that, while viewing the source in the editor, the links will appear as relative URLs. This is normal, and they will be converted before the page is published.

Working with JavaScript Plugins

If you’re using JavaScript plugins that dynamically change your HTML after the page loads, you’ll probably want to disable them in the CMS. There are a few ways to do this.

Using HTML Comments

The CMS will ignore everything inside of these special HTML comments: 

<!--cms-disable-->
<script>alert('This will alert on the site but not in the CMS');</script>
<!--/cms-disable-->

Using JavaScript

For more control over what you want to disable, you can check the value of window.isCMS using JavaScript: 

if( window.isCMS ) {
    alert('Page is being rendered in the CMS');
} else {
    alert('Page is NOT being rendered in the CMS');
}

Using Meta Tags

You can also check for the presence of the is-cms meta tag. This meta tag will be added by the Live Editor when the page is being rendered in the CMS: 

<meta name="is-cms" content="true" />

To check for this tag using jQuery, you could do this: 

if( $('META[name=is-cms]').attr('content') === 'true' ) {
    // Page is being rendered in the CMS
} else {
    // Page is NOT being rendered in the CMS
}

Include Files

Surreal lets you include shared content in your pages using PHP, ColdFusion, or Server Side Includes (SSI). This is extremely useful for things like headers, footers, navigation menus, and sidebars, where a change made on one page needs to propagate to many pages. When you publish a page that has an include file, Surreal will automatically look for the appropriate file on your server and update its content.

When using include files, make sure that your editable regions are inside of the include files. Do not try to place your include code inside of an editable region, as it is server-side code and will be stripped for security reasons.

PHP

The following types of PHP includes are supported: 

<?php
include('includes/sidebar.php');
require('includes/sidebar.php');
include_once('includes/sidebar.php');
require_once('includes/sidebar.php');
?>

If you need to reference your website root, you can use this syntax: 

<?php
include($_SERVER['DOCUMENT_ROOT'] . '/includes/sidebar.php');
?>

Surreal cannot parse other PHP variables, so something like include($file) will not work. You must specify the path and filename in a string inside of the include statement.

By design, Surreal will not follow nested include files.

ColdFusion

If your server is running ColdFusion, you can include files using the following syntax: 

<cfinclude template="/includes/sidebar.cfm">

Server Side Includes

If SSI is enabled on your server, you can include files using the following syntax. If not, you might be able to enable it. This tutorial should help you get started. 

<!--#include virtual="/includes/sidebar.html" -->