XML Includes is a special XML aggregation filter which makes it possible to reference XML and metadata from multiple files, enabling XSL transformations to automatically generate links and navigation sections that tie a web site together.
Defining XML Includes
Any number of XML Includes can be defined per form of output of an xml-doc or xml-doctype in a HyperContent project definition. Each set of includes is configured in an include tag:
< include >
source =
A path pattern indicating the location of the files to be included. This may include the path of a file in the repository, a URL, or a pattern with wildcards; if the wildcard pattern does not begin with a '/', it is resolved at build time from the directory of the source file being built. See the chapter on path patterns for more information.
data = (yes | no)
Indicates whether the actual XML content of an included file should be copied into the output XML. This is useful when you want to reuse portions of the content, for example displaying the first 300 characters of text. Defaults to "yes", but should be set to "no" if the data is not needed, to improve build performance. If the file is not an xml content type, data will not be included.
metadata = (yes | no)
Indicates whether the metadata of the included file should be copied into the output XML as RDF/XML. This is useful, for example, when you want to create a link to an included file and use its title in the text of the link. Defaults to "no".
The result of XML Includes
At build time the include filters are processed first, before any XSL transformation or other filters that may be specified. The result is one XML document which contains both the source file and its metadata expressed as RDF/XML, and all of the files in the repository which match one of the configured include source patterns. There are three special elements declared in the HyperContent namespace which create the structure around the source and included data and metadata:
xmlns:cms="http://www.ais.columbia.edu/sws/xmlns/cucms#"
< cms:wrapper >
This is the root element of the XML document generated by the XML Includes filter. It has one cms:source child element representing the XML document which was passed into the filter, and 0 or more cms:include elements representing each included file. The cms:source element has two child tags, an rdf:RDF tag containing the source file metadata in RDF/XML, and the root element of the source file with all the source XML data beneath it. A cms:include element may or may not have the rdf:RDF and root element as children, depending how the include was configured. Both cms:source and cms:include have the following attributes:
directory =
The directory in which the represented file lives in the repository.
path =
The path of the represented file in the repository.
filename =
The name of the represented file in the repository (the portion of the path after the directory).
pattern =
The pattern is taken from the path attribute of the xml-doc, xml-doctype or resource-directory tag used to configure the represented file's type in the project definition. You can easily query specific page types in XPath using this attribute.
basename =
The name of this file without an extension. This can be useful for constructing links to alternate forms of output for the represented file by appending the appropriate extension.
type =
The MIME type of the represented file.
XPath examples for working with included data
To illustrate the value of XML Includes, here are a few example XPath queries that could be used in XSL transformations to leverage included data.
/cms:wrapper/cms:include[@pattern='/faculty/*']/child::*[not(contains(@name,'RDF'))]
Retrieves the root element of all includes which were defined as faculty pages
/cms:wrapper/cms:include[starts-with(@directory,/cms:wrapper/cms:source/@directory)]
Retrieves all included files in or beneath the same directory as the source file
/cms:wrapper/cms:source/rdf:RDF/fs:File/dc:title
The title of the source document
