Documentation » Website Integration

Choosing a DOCTYPE

For maximum compliance with W3C Standards, it is recommended that your webpages use the XHTML Transitional DOCTYPE. You can use another DOCTYPE at your own discretion, but you may experience validation errors on occasion.

For your convenience, the code to specify an XHTML Transitional DOCTYPE is:


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

Setting Your Character Encoding

To accommodate special characters that the editor may output (including characters from non-western alphabets), your webpages need to use the versatile UTF-8 format. To enable UTF-8, the following code should be added to the head section of all webpages:


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

If published pages contain unintended symbols in various locations, double check that the pages are using UTF-8.

Troubleshooting Encoding Issues

First, make sure that you remove any other meta tags from your pages that specify other character encodings such as ISO-8859-1. These might be overriding the UTF-8 meta tag.

In rare cases, your webserver may be configured to serve pages as ISO-8859-1 (or another type of encoding) even if you are using the UTF-8 meta tag in your documents. If your server supports .htaccess files, you can usually fix the issue by adding AddDefaultCharset UTF-8.

Place the above line in your existing .htaccess file. This file can usually be found in the same directory as your homepage. If you don’t see it there, it may be necessary to create it yourself.

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

The last attribute, fileEncoding, is particularly important, as that tells the server how to serve your pages.

Still Not Displaying Properly?

If you’ve tried all of the above and still experience issues with strange characters, please submit a help request from within the CMS.

Enabling Webpage Properties

The Page Properties Editor allows users to modify the title, description, and keywords of each webpage. To enable this feature, make sure that the following elements all appear inside the head section of your webpages:


						<title>Your Webpage Title</title>

						<meta name="description" content="..." />

						<meta name="keywords" content="..." />

If a webpage is missing any of these, the missing elements will be disabled in the Properties Editor.

Defining Content Regions

The CMS will automatically choose the most appropriate editing tool based on the type of content regions you enable on each page. To define a content region, simply add class="editable" to virtually any HTML element.

Sample Usage:


						<div class="editable">

						    <p>Here is some content</p>

						</div>

If your element already has a class, you can still make it an editable content region:

<div class="someclass editable">

Refrain from nesting editable elements inside of other editable elements, as this may result in undesirable output. For example:


						<div class="editable">

						    <blockquote class="editable">

						        <p>Here is some content</p>

						    </blockquote>

						</div>

General Usage

Most designers find it easy to make div elements editable when creating large content regions (or td elements for table-based layouts). This generally works very well, but you can also apply the editable class to a number of other HTML elements. Some of the more popular ones include:

blockquote
div
h1 — h6
img
ol, ul
p
pre
script*
span
style*
table, td, th

The CMS now supports nearly 50 different HTML elements, including acronym, address, fieldset, label, table, and many more.

* It is against XHTML DTDs to use class attributes on script and style elements. Although Surreal will allow you to edit those that contain the editable class, you should be aware that your webpages will not be “valid” according to W3C standards.

You can make input elements editable — even hidden types. Their value attribute will be updated when published.

Disabling the Rich-text Editor

You can use the editable-text class to disable the rich-text editor for any content region. To do so, simply replace any editable class with editable-text.

Labeling Content Regions

You can apply labels to editable regions by adding a title or id attribute to the respective element(s):


						<div title="Column One" class="editable">

						

						<div id="column_one" class="editable">

These labels will appear in the webpage editor toolbar. They are used to easily identify the content regions that appear on each page.

If present, Surreal will use the title attribute over the id attribute. If the id is used, Surreal will convert underscores and dashes to spaces and camel-case each word for better clarity. For example,


						<div id="column_one" class="editable">

will display in the editor as “Column One”. If both title and id are missing, the region will be labeled as <[element type]>.

Repeatable Regions

You can create one or more repeatable regions inside of any content region. This is very handy for pages that have structured markup and/or formatting which users may not be able to re-create easily on their own. Useful examples include articles, photo galleries, complex lists, styled table rows, etc.

This feature is currently in beta testing. Please report any issues and feedback to us so we can improve and optimize it.

Defining Repeatable Regions

To create a repeatable region, add the repeatable class to any element that exists inside of a content region. For example:


					<div class="editable">


					    <div class="repeatable">

					        <h1>Article Title</h1>

					        <p class="article-date">Posted on August 20, 2010</p>

					        <div class="article-body">...</div>

					    </div>
					


					</div>

The above example creates an editable content region with one repeatable region inside of it. When a user selects this region in the CMS, they will be able to add, remove, and reorder repeatable regions using the Repeatable Regions toolbar:

Repeatable Regions Toolbar

Each new region a user creates is an exact clone of the selected region, including all HTML elements, styles, classes, etc.

Grouping Repeatable Regions

There is no need to group or identify your repeatable regions. The CMS will automatically detect when a series of repeatable regions begins and ends. (Technically, this occurs when another element which is not repeatable occurs before or after the series.)

Styling Repeatable Regions

The rich-text editor has predefined styles for repeatable regions. You can override these styles by creating custom styles using the following CSS selectors:


						/* Normal state */

						.mceContentBody .repeatable { ... }

						

						/* Hover state */

						.mceContentBody .repeatable-hover { ... }

						

						/* Selected state */

						.mceContentBody .repeatable-focus { ... }

The .mceContentBody portion of the selector will prevent the repeatable styles from showing up in the Styles dropdown.

You may need to use !important to override certain CSS properties before they show up in the rich-text editor.

You can be really creative when styling repeating regions for your website and the CMS. It is always a good practice, however, to identify repeatable regions in such a way that your editors will recognize them while editing. The selected state is especially important, as this is how the CMS identifies which region is currently selected.

Things to Remember

Repeatable regions are only a guide for structuring and styling markup
Editors can change the structure and styles of regions if they wish
Editors can delete repeatable regions if they wish
There are no limits to the number of regions you can have on a page
You can nest repeatable regions inside other repeatable regions

Linking to Files

Surreal generates URLs from the website root. For example, when you use the File Manager to select a file, the resulting URL will be preceded by a forward slash (/) and the complete path starting from the website root.

When designing, you should always precede links to internal resources (files on your own website) with a forward slash or absolutely:


						Correct:

						<a href="/images/thumbs/image.jpg">

						<a href="http://example.com/images/thumbs/image.jpg">

						

						Incorrect:

						<a href="../thumbs/image.jpg">

						<a href="thumbs/image.jpg">

Working with Dynamic Webpages

Surreal generally works well with webpages that contain both plain HTML and server-side scripting such as PHP, ASP, etc. For best results, refrain from using class="editable" anywhere within your server-side code.

Remember, if you include a file (such as a navigation menu) on every page, you will have to enable that file separately in Surreal to be able to edit it.

Surreal CMS