The Beauty of Include

The Beauty of 'include'

Learn how to use include effectively in your ECEn XML web pages.

Web pages often need to share common content. For example, web pages might share a common menu, set of features or news box. Using only copy and paste, it can be painful to ensure that each web page has the same exact menu or other shared features.

This is where 'include' comes in. Using the ECEn XML, you can create a small XML file containing only your shared content, for example, a left menu. You can simply 'include' this file on each of the XML web pages need this content. So, when you need to change the shared content, the change is reflected automatically in all of the ECEn XML web pages which included the file.

To include chunks of XML from other files in the ECEn Web XML, we're going to use <include> tags.

These instructions assume that you already have an ECEn XML web page to edit and know at least a bit about XML. Most content, such as text, links, lists, pictures etc., belongs in the <content> portion of your page; check the instructions below to see if you need to make sure that you have a page with a <content> portion. If you need a quick tutorial or just a simple starter web page download, check out the 'Howdy, World' Tutorial where you can get a brief overview of what files you need to set up a basic ECEn XML web page.

If you need an example, have a look at the Includes Example page. You can view the XML source in your browser by clicking the 'this XML' at the bottom of the page (but note that this will show the XML file after all the including has already been done. To see the individual XML pieces, try the 'see other formats' link). Or, the XML source is located in the Common Tasks Downloads to the right. (Right click, Save Link Target As...)

Basic Includes

Here is some ECEn XML "code" to show you how includes work:

[image]

There are two XML files here:

The blue XML file is the XML web page including a few files.

The green XML file is one of the files included in the blue XML web page.

To use 'includes' in your ECEn XML web pages:

Just as in the example, you'll need two separate XML files: one to include files and one to be included.
The file you are planning to include does not need its own .phtml file. In most cases, the included file does not have all the pieces required to stand on its own as an ECEn XML page. The file does have to contain valid XML, however.

Create the XML file to be included. You can create any content you want within this file. Here are a few guidelines:

When placing a menu, news box, or a single section within the included file, make sure that the <menu>, <news>, or <section> is the outermost tag in the included XML file.

If the content that you want to include doesn't have a natural outermost tag around it, like the sample above, then you will need to surround all of your content with <to-be-included> tags. These tags are stripped out at include time---they won't show up in your end document. They are necessary, however, because all valid XML documents have one outermost tag.
For more details about outermost tags and valid XML documents, have a look at the General XML Fundamentals page.

Now, in the XML file into which you want to include your newly created file (from the previous step), create <include> tags and within them, specify the location of the XML file which you want to include.
You can specify a relative or absolute path, or a full web address, to your included XML file. If the XML Template Engine can't find the file or if there is an error in the included file, your web page will render without the included file.

For more information about how the <include> tag works, check out the ECEn XML Template Reference or email the ECEn Web Team.