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 let you share content across all pages on your web server. 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 all of your pages, updating every
element with the same
cms-include class. We'll also update any
matching includes we find in your templates.
Static includes can contain content regions, but they don't have to. You can include just about any HTML you want in them!
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 rely on server-side scripting to include other files into your pages. When you publish a page with dynamic includes, we'll look for content regions in those files and update them 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
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.
The following types of dynamic includes are supported.
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. You can, however, use this special PHP variable to reference your document root.
<?php include $_SERVER['DOCUMENT_ROOT'] . '/includes/sidebar.php'; ?>
Surreal CMS will follow Server Side Includes with the following syntax.
<!--#include virtual="/includes/sidebar.html" -->