Inserting external HTML code

The server-side includes described in the previous section require you to configure an HTTP server to execute the includes when the file is accessed. What if you want to insert static HTML code from an external source into the HTML files that DocBook builds? For example, many website pages are based on templates that use boilerplate HTML code or Javascript libraries that already exist in external files. How do you insert such content verbatim into DocBook-generated HTML files?

The basic method is to use the XSLT document() function to open the code file, and then use xsl:copy-of to copy its content to your output. However, the document() function can only open well-formed XML files, not just any text file. But you can turn a text file into a well-formed XML document by wrapping its content in some element's start and end tags. Then the code text will be taken as the content of the wrapper element. As you will see in the examples below, you do not have to include the wrapper element in your output, so you can use any element name. The examples use htmlcode.

If your external code file includes HTML markup, be sure that any HTML elements are well-formed. The easiest way to do that is to convert it to XHTML. You can use the HTML Tidy tool to do that.

In the page header

If you want to insert the external code into the header on your HTML pages, you can use the user.header.content template as described in the section “HTML headers and footers”. The following is an example:

<xsl:template name="user.header.content">
   <xsl:variable name="codefile" select="document('mycode.html',/)"/>
   <xsl:copy-of select="$codefile/htmlcode/node()"/>
</xsl:template>

The first line of the template opens the code file and puts its well-formed content into a variable named codefile. This example assumes the code is contained in a file named mycode.html located in the current directory. You may want to make that a parameter reference so you can change the pathname more easily. You could also use a URI and have your XML catalog map that URI to the actual code file on your system. See Chapter 5, XML catalogs for more information about using catalogs.

The example also assumes the code file uses a wrapper element named htmlcode to make it well-formed XML. The second line of the template copies the content of the wrapper element to your output, without including the wrapper element itself. It selects using node(), which matches everything, including elements, text, comments, and processing instructions. If you do not want to hard code the wrapper element name in your template, then use this selection instead:

<xsl:copy-of select="$codefile/*/node()"/>

This will copy the content of whatever the root element is in the code file.

In the HEAD element

If you want to insert boilerplate HTML code into your HTML head element, then you can use the user.head.content template instead. See the section “HTML HEAD elements” for further information on that template. The following is an example that is similar to the one in the previous section:

<xsl:template name="user.head.content">
   <xsl:variable name="codefile" select="document('mycode.html',/)"/>
   <xsl:copy-of select="$codefile/htmlcode/node()"/>
</xsl:template>

In the page content

If you want to insert boilerplate HTML code mixed in with the content of your pages, then you can use the same technique as the previous sections to customize any of the element templates that generate output.

If you want the authors of your documents to be able to insert their own HTML code in arbitrary places, then they can use a dbhtml-include processing instruction to indicate the location and filename. At the point where you want the HTML code inserted, add a processing instruction like the following to your DocBook XML document:

...
</para>
<?dbhtml-include href="mycode.html"?>
<para>
...

The DocBook HTML stylesheet will open the file referenced by the href pseudo-attribute and attempt to copy it into the output.

  • To be read by an XSL stylesheet, any external HTML code file must be well-formed XML. Well-formed means:

    • It must have a single root element.

    • All non-empty elements must have an end tag as well as a start tag.

    • Empty elements must include a closing slash, such as <br/>.

    • Attribute values must be in quotes.

    Loose HTML coding will not be recognized as XML by the parser.

  • If the HTML code has a single root element, then the stylesheet will just copy it all into the output.

  • If the HTML code is not a single root element, then you must make it a single root element by wrapping all the content in an html wrapper element. That is, put an <html> tag at the start of the file and an </html> tag at the end of the file. The DocBook stylesheet will recognize that wrapper tag and copy everthing inside the element, not including the <html> wrapper. This only happens with that element name.