Chapter 3. Tutorial: creating a modular document

Table of Contents

1. Creating the Copyright.html document
2. Inserting a reference to Copyright.html into the XHTML page
3. Extensive use of the "Copy as Reference" command
4. Creating modular documents which are highly interchangeable with other applications

A modular document is a document which not only has its own content but which also includes elements contained in other documents.

Let's say you want to add the same copyright information at the bottom of all the XHTML pages you create. The first step is to author the copyright information in a separate document we'll call Copyright.html. The second step is to include this copyright information at the bottom of the XHTML page created during this tutorial.

1. Creating the Copyright.html document

Use File|New and this time choose XHTML|Div (part of a modular document) as the document template.

This template is a div (a generic container) containing a p. Using Edit|Replace, replace the p by an address element and then type the copyright information. (The copyright sign © has been inserted using the Characters tool.)

Using Edit|Insert Before, insert a hr (horizontal rule) before the address to visually separate the copyright information from the body of the XHTML page.

Using File|Save As (or File|Save which behaves like File|Save As for a new document), save this document as Copyright.html in a place where it can be shared by all the XHTML pages you'll create.

2. Inserting a reference to Copyright.html into the XHTML page

The procedure to do this is very simple. It is similar to copying an element in a document and pasting it in another document:

  1. Open in XXE the document containing the element you want to reference. If the document containing the element you want to reference is already opened in XXE, simply display its window.

  2. Explicitly select the element you want to reference.

  3. Use menu bar menu Edit (not popup menu Edit), select sub-menu Reference and choose entry Copy as Reference (shortcut Ctrl-Shift-C). Unlike the usual Copy command which copies XML data to the clipboard, this special command copies to the clipboard a reference to an element (that is, a pointer to the element).

  4. Now switch to the window containing the modular document.

  5. Select the element where you want to insert the reference.

  6. Use one of the standard Paste Before, Paste or Paste After commands to insert the reference into the modular document. As always, the Paste Before, Paste or Paste After commands are enabled only if the DTD or schema constraining the modular document allows it.

Now let's apply this procedure to our example:

  1. The window containing Copyright.html, the document we want to reference, is already displayed. There is nothing to do in step #1.

  2. We want to reference the whole Copyright.html, therefore we need to select its root element. For example, click on word div in the node path bar to do this.

  3. Use Ctrl-Shift-C to copy to the clipboard a reference to the div. Notice that at the bottom of XXE window, near the "View Clipboard Content" icon, word div is displayed using a dimmed color. This means that the clipboard contains a reference rather than ordinary data.

  4. Switch to the window containing our XHTML page, for example by clicking on the tab having "Untitled.html" as its title.

  5. Select last p at the bottom of the page, for example by simply clicking at the right of the XMLmind logo. (There are many quick ways to select nodes using the keyboard or the mouse: they are all explained in next chapter of this user's guide: being productive with XXE.)

  6. Use command Paste After (shortcut Ctrl-W) to paste the reference to the div after selected p.

The XHTML page now looks like this.

Notice that the copyright information inserted at the bottom of the page is displayed with a light blue-gray background. This is used to indicate that this part of the document has been included from an other document and that,consequently, it cannot be edited in this window.

Click anywhere inside the copyright information and try to type some text: no characters are inserted. (You can still delete, cut or replace the whole copyright information: it is the div which is not editable, not its parent body.)

Also notice that the node path bar displays non-editable nodes using a dimmed color.

At the left of the node path bar, the button with a right arrow switches to the window of the included document. Try it and you'll be able to edit Copyright.html.

Once having Copyright.html in front of you, use the button at the left of the node path bar showing a left arrow to go back to the XHTML page created during this tutorial.

3. Extensive use of the "Copy as Reference" command

Let's suppose you need to write an article about taxes but you don't want to type directly in your document the values of the different VAT rates used in European countries, because you know that these VAT rates are about to change. Let's say that you already have an XML document detailing these VAT rates.

(In this tutorial, creating the VAT rates document from scratch would be tedious that's why you'll find VATrates.html in XXE_install_dir/doc/user/tutorial/. You'll also find in this directory: Untitled.html, the XHTML page we are trying to create, Copyright.html and xxe.gif. That is, all the files used in this tutorial.)

Add a new p at the end of our XHTML page and type in it ``The VAT rate of France is higher than the VAT rate of Germany.''.

Now we need to use VATrates.html to insert the numerical values of the VAT rates in our new paragraph.

  1. Open VATrates.html in XXE.

  2. Click inside the cell which contains the VAT rate of France to implicitly select it, then use Ctrl-Shift-C to copy it as a reference.

  3. Switch to the window displaying our XHTML page: Untitled.html.

  4. Move the caret after ``The VAT rate of France'' .

  5. Paste the copied reference using Ctrl-V.

Do the same for the VAT rate of Germany.

The XHTML page now looks like this.

This has worked smoothly because:

  1. Each table cell of VATrates.html contains a single span element rather than plain text. A span element can be inserted almost anywhere in an XHTML document.

  2. Each span of second column is identified using an id attribute: austria_vat, belgium_vat, etc.

Now let's try to insert the whole VAT table in our XHTML page:

  1. Switch to the window of VATrates.html.

  2. Select the whole table, for example by clicking on word table in the node path bar.

  3. Use Ctrl-Shift-C to copy the table as a reference.

This verbose dialog box is immediately displayed:

Click on No. What does this mean?

Command Copy as Reference allows to copy as a reference any element, including those not having an ID.

Unless the copied reference is a reference to the root element of a document, this means that the copied reference is based on the position of the element as a child of its parent element, on the position of the parent element as a child of the grand-parent element and so on.

This is what we call a hierarchical XPointer. In the above example, it is "element(/1/2/2)".

Pasting a reference based on a hierarchical XPointer is not safe because if you modify the referenced document, your referencing document may point to an element other than the one for which a reference has been originally pasted.

This is why XXE will warn you each time you'll try to copy a reference based on a hierarchical XPointer.

Note that you'll never get the above dialog box when you'll paste a reference to the root element of a document (example: "Copyright.html") or when you'll paste a reference which exclusively uses an ID to locate the element (example: "element(france_vat)") because these references are considered to be safe.

Now type this sentence at the end of last added p: ``Note that the VAT rate of France is lower than the VAT rate of Italy.'' and insert the value of the VAT rate of Italy as explained above.

Inserting the VAT rate of France in second sentence is easier because we have already pasted it in our XHTML page. In such case, there is no need to switch to the window displaying VATrates.html:

  1. Select the span previously pasted in our XHTML page which contains the VAT rate of France. For example, implicitly select it by clicking inside it.

  2. Ctrl-Shift-C to copy it as a reference.

  3. Click in second sentence after ``Note that the VAT rate of France''.

  4. Paste the copied reference using Ctrl-V.

The XHTML page finally looks like this.

Note that instead of using Copy As Reference (Ctrl-Shift-C) to copy the existing reference to the France VAT found in our XHTML page, we could have used the ordinary Copy command (Ctrl-C). In fact, the standard Cut, Copy and Paste, Paste After, Paste Before commands all know about included elements and will take care of preserving the fact that they are references to elements contained in other documents.

For example, use Cut (Ctrl-X) and Paste Before (Ctrl-U) to move the p containing all the VAT spans before the p containing the XMLmind logo. You'll get this:

4. Creating modular documents which are highly interchangeable with other applications

Creating modular documents in XXE should work very smoothly, without much limitations. Converting such modular documents to other formats, within XXE, using its "Convert document" menu[3], should work equally well.

Despite the fact that XXE exclusively uses standard mechanisms (XIncludes and, to a limited extent, references to external entities), naively creating modular documents may lead to interchange problems with third-party applications.

These problems come from two situations:

  1. The application does not support XInclude. Example: the Saxon XSLT processor.

  2. The application supports XInclude, but with limitations. Example: the xsltproc XSLT processor.

The workarounds are:

Situation A: no support for XInclude

Limit yourself to master documents directly referencing external entities. That is, the referenced external entities should not themselves include elements found in other external entities.

DocBook example: exclusively use the Book and "Chapter entity (no <!DOCTYPE>)" document templates[4].

XHTML example: exclusively use the Page and "Div entity (no <!DOCTYPE>)" document templates.

Situation B: limited support for XInclude
  1. Do not mix XIncludes and references to external entities. To ensure this is the case, simply never use document templates having the word "entity" in their names.

    DocBook example: do not use the "Chapter entity (no <!DOCTYPE>)" document template.

    XHTML example: do not use the "Div entity (no <!DOCTYPE>)" document template.

  2. Avoid anything which, even remotely, looks like a recursive inclusion.

    For example, even if this complies with the standard and is very well supported by XXE, avoid to reference in a modular document, an element contained in the modular document itself (e.g. you want the same tip to appear at different places).

In both cases, make sure that option "Entity when possible, XInclude otherwise" (Options|Preferences, Edit section, "Paste reference" frame) is checked[5].



[3] The "Convert document" menu is present only in XMLmind XML Editor Professional Edition.

[4] Documents templates are displayed by the File|New dialog box.

[5] Normally this should be the case, as this is the default value for the "Type of document reference" option.