Chapter 3. Tutorial: creating a modular document
Prev |  | Next

## Chapter 3. Tutorial: creating a modular document

A modular document is a document which not only has its own content but which also includes XML nodes 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 once again choose XHTML Strict/Page as the document template.

Using Edit → Replace, replace the inner `p` by a `div`.

Using the Attributes tool, specify `copyright` as the `id` attribute of the newly insert `div` element.

Then select the text node which is the default content of the `div` by clicking on `#text` in the node path bar and replace it by an `address` element. Finally, 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).

   Note that unless selected element has an ID attribute or is the root element of the document, Copy as Reference will not work.

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 `div` contained in `Copyright.html`, therefore we need to select it. 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, the 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 the 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 the values of the different VAT rates used in European countries directly in your document 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 which is 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 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+C to copy it normally.

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 it is not possible to copy a reference as a reference. Only an ``original'' element can be copied as reference. That's why we used Copy (Ctrl+C) here and not Copy As Reference (Ctrl+Shift+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 `span`s 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[2], should work equally well.

Despite the fact that XXE exclusively uses a standard mechanism (XInclude), 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 at all. Example: the Saxon XSLT 1 processor.

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

The workarounds are:

Situation A: no support for XInclude

  Use a preprocessor to create a flat copy of the document before submitting it to the application which does not support XInclude. XMLmind XML Editor comes with such preprocessor. You'll find `xmltool` in the ``XXE_install_dir`/bin/` directory.

Situation B: limited support for XInclude

  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).

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

Prev |  | Next
Chapter 2. Tutorial: basics | Home | Chapter 4. Being productive with XXE