Documentation

Includes

You can share content across pages using includes. This is perfect for things like headers, footers, and sidebars that need to stay the same from page to page. Instead of updating each page one by one, we'll update them all for you automatically.

We support two types of includes, static and dynamic.


Static includes

Static includes let you share content across all of the pages you've enabled in Surreal CMS. Here, we do the heavy lifting by downloading and uploading all of your pages when you publish changes. This is especially useful for static platforms such as Amazon S3 where server-side scripting can't be used.

Static includes are defined by adding id and the cms-include class to any element on the page.

<footer id="footer" class="cms-include">
  <!-- content here -->
</footer>

When you publish a page with a static include, we'll loop through every page you've enabled in Surreal CMS, updating every element with the same id and cms-include class. Only the element's contents are copied, not its attributes. Files on your server that aren't enabled are left alone. We'll also update any matching includes we find in your templates.

The page you publish always wins. Its copy of each include replaces the copy on every other page, and every enabled page is uploaded again.

Tip

Static includes can contain content regions, but they don't have to. You can include just about any HTML you want in them!

Warning

Make sure each include is up to date on the page you publish. If a page has an old copy of an include, publishing it will overwrite the newer copy on every other page.

Warning

Using this feature with FTP or FTPS will make publishing very slow if you have a lot of pages. This is because they don't support concurrent transfers, so every page needs to be downloaded, processed, and uploaded synchronously. If you need to use FTP or FTPS, dynamic includes will be much faster.


Dynamic includes

Dynamic includes rely on server-side scripting to include other files into your pages. When you publish a page, we'll look for each content region in the page first. If a region isn't there, we'll look for it in the files the page includes and update it accordingly.

There are some caveats to this approach, however.

  • You should never put server-side code inside a content region, especially includes. Put your content regions inside the include file instead.
  • Always open and close HTML tags in the same file (e.g. don't put <body> in header.php and </body> in footer.php). The HTML parser will try to fix mismatched tags, often creating unexpected results.
  • As of version 7, Surreal CMS no longer supports ColdFusion or Lucee includes.
  • By design, Surreal CMS will not follow nested includes.
  • If a region can't be found in the page or the files it includes, it won't be saved.

The following types of dynamic includes are supported.

PHP

Surreal CMS will follow PHP includes with the following syntax.

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

We don't parse your PHP code, so don't use variables when referencing include files. Use a quoted path that's relative to the page instead, even when the page is in a subfolder.

<?php
include '../includes/sidebar.php';
?>

Server Side Includes

Surreal CMS will follow Server Side Includes with the following syntax.

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

Only the first Server Side Include on each page is followed.

Include paths

Include paths are resolved relative to the page's folder. Absolute paths, including ones that start with $_SERVER['DOCUMENT_ROOT'] or virtual="/...", are resolved from your server's root folder. They only work if that folder is also your website's root, so use relative paths whenever you can.