4.3. Conditional processing4.4. Transclusion (16/59)Part II. Reference

4.4. Transclusion

XMLmind Ebook Compiler has good support for transclusion, that is the ability to include contents found in an input HTML page into another input HTML page. This feature is implemented using a standard mechanism called XInclude.

Example, "page1.html" contains paragraph having id="notice":

1
2
<p id="notice" class="important">Interest rates are subject
to fluctuation without notice.</p>

Because this paragraph has an id, it's possible to include it in "page2.html":

1
2
3
4
5
6
<p>Paragraph found in page2.html.</p>

<xi:include href="page1.html" xpointer="notice" 
  xmlns:xi="http://www.w3.org/2001/XInclude" />[1]

<p>Other paragraph found in page2.html.</p>

The corresponding output HTML page will then contain:

1
2
3
4
5
6
<p>Paragraph found in page2.html.</p>

<p id="notice" class="important">Interest rates are subject
to fluctuation without notice.</p>

<p>Other paragraph found in page2.html.</p>

Note that transclusion works fine not only between two input HTML pages, but also:

However transclusion does not work between an input HTML page and an ebook specification.

Example 4-2. Transclusion works fine within the same input HTML page
1
2
3
4
5
6
7
<p id="notice" class="important">Interest rates are subject
to fluctuation without notice.</p>

... ELSEWHERE in page1.html ...

<xi:include href="" xpointer="notice" 
  xmlns:xi="http://www.w3.org/2001/XInclude" />

Notice href="" to refer to the same file.

Transclusion is most often used between the input HTML pages and a “utility HTML page” which is not an input HTML page but which contains useful “snippets”.

Example, excerpts from "snippets.html":

1
2
3
4
5
6
7
8
<ul>
  <li><span id="ebookc">XMLmind Ebook Compiler</span>.</li>

  <li><span id="xxe">XMLmind XML Editor</span>.</li>

  <li><a href="http://www.xmlmind.com/" id="xmlmind"
         target="_blank">XMLmind</a>.</li>
</ul>

Now, including snippets in an input HTML page:

1
2
3
4
5
6
7
8
9
<p><xi:include href="snippets.html" xpointer="ebookc"
xmlns:xi="http://www.w3.org/2001/XInclude" /> is free, open source software
developed by <xi:include href="snippets.html" xpointer="xmlmind"
xmlns:xi="http://www.w3.org/2001/XInclude" />.</p>

<p><xi:include href="snippets.html" xpointer="xxe"
xmlns:xi="http://www.w3.org/2001/XInclude" /> is a commercial product
developed by <xi:include href="snippets.html" xpointer="xmlmind"
xmlns:xi="http://www.w3.org/2001/XInclude" />.</p>

[1] Creating xi:include elements by hand is tedious and error prone. It's strongly recommended to use an XInclude-enabled editor like XMLmind XML Editor to do that. With XMLmind XML Editor, creating an xi:include element is as easy as copying a reference to an element (Ctrl+Shift-C) from one page and then pasting it (Ctrl-V) into another page.