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>inheader.phpand</body>infooter.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.