Development

Working with Server Side Includes

It is possible to publish snippets of HTML which can be pulled in via Server Side Includes (SSI) at runtime on your live web server. This method of including content can be useful for components like navigation menus, footers, and/or any other areas of your site that are commonly used across your site.

One drawback of a push CMS (like Cascade CMS) is that if the contents of a navigation menu change, for example, a full site publish is needed in order to ensure that all of the pages on your site get their navigation menu updated accordingly. By utilizing SSI for these areas of your site(s), you can publish a single asset and have all pages on your site load the most up-to-date navigation menu almost instantaneously. 

The steps below will walk you through a very basic setup that allows you to create/publish a snippet of HTML and then pull that into your pages on the live website through a SSI directive.

Set up a Page type for "include" files

  • Create a new Template with the following code:
<!--#cascade-skip-->
<pass-through>
 <system-region name="DEFAULT"/>
</pass-through>
  • Create a new Configuration with the following settings:
    • Check the Default Output box
    • Set the Type of Data field to HTML
    • Set the File Extension field to .shtml
    • In the Template field, select the Template that you created in the very first step
    • Ensure that the Publishable check box is checked
  • Create a new Content Type with the following settings:
    • In the Configuration field, select the Configuration you created in the step above
    • In the Metadata Set field, select a Metadata Set (the Default will typically be fine in this case)
    • In the  field, select No Data Definition (WYSIWYG Only)

At this point, we can create a Page asset using this Content Type and supply the HTML snippet we're looking to publish to the web server, and then reference the include file we've created using an SSI directive. To do this, follow the steps outlined in the next section below.

Create a new "include" Page

  • From the Add Content menu, click to create a new XML Block
  • In the content field of the Block, enter the following code and Submit:
<!--#protect-top
<ul>
 <li>Sample item 1</li>
 <li>Sample item 2</li>
 <li>Sample item 3</li>
</ul>
#protect-top-->
  • Click the Add Content menu once again and click to create a new Default -> Page
  • When prompted to select a Content Type for the Page, select the Content Type that you created in the previous section
  • Give the Page a name of include-file and then click the Configure tab
  • Scroll down to the Regions section and in the DEFAULT region, click the Block chooser and select the XML Block that you created above
  • Submit the Page
  • Publish the Page to your web server and verify that you can reach it by using the More -> Live option (you should see a mostly empty page with just our unordered list from earlier)

At this point, we have a Page asset that just contains our short HTML snippet (an unordered list containing 3 list items) and we can now pull it into other pages using an SSI directive.

Add the SSI to your page(s)

  • From the Add Content menu, click to create a new XML Block
  • In the content field of the Block, enter the following code and Submit:
[system-view:internal]
Enter content here that will be displayed inside the CMS only
[/system-view:internal]

[system-view:external]
<!--#include virtual="[system-asset]/full/path/to/include-file[/system-asset]" -->
[/system-view:external]
Notes:

- In the code snippet above, we're utilizing system-view tags in order to tell the CMS what should be displayed when previewing inside the CMS versus what should be displayed once published. This is necessary as SSIs will only work when viewing pages on the live website.

- In the "include" directive, we're surrounding the full path to our "include" file with system-asset tags to tell the system that we're linking to an asset that is managed in the system and that it should rewrite the link accordingly on publish.
  • Create or edit an existing Page
    • While creating/editing, click the Configure tab
    • Scroll down to the Regions section, then pick a region where you'd like to attach the HTML snippet we created earlier in this document
    • Click the Block chooser in that region and select the XML Block we just created above (the one with the SSI directive in it)
  • Publish the Page and then view it on the live site by clicking More -> Live

Assuming all goes as planned, your published page should display the unordered list that we are including via our SSI.

Additional information:

The steps above are intended to show how SSIs can be used in conjunction with CMS assets. There are many different ways in which this could be implemented and this document only touches on the general strategy for how it can be done.

For example, you'd typically want to attach your SSI directive Block to either a Template region or Configuration region (so that all Pages using that Template/Configuration inherit the SSI directive). It's also very common to have more dynamic content being generated for the HTML snippet using Format logic as opposed to just static HTML in a Block.
Notes:

- The ability to use SSI is dependent on the target web server configuration. You'll want to verify that your web server administrator(s) have this option enabled before you attempt to utilize this strategy.

- The HTML includes end up publishing as standard HTML files on the web server. You may wish to exclude the folder/directory where those includes are stored from search engines/crawlers by adding the directory to your robots.txt file on the web server.
Back to Top ↑