http://www.xmlmind.com/xmleditor Contents Tutorial: basics Being productive with XXE Being productive with XXE

3 Tutorial: creating a modular document

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.

3.1 Creating the Copyright.html document

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

images/modular00

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

images/modular01

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.

images/modular02

3.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 Document 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. 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. XXE being a multi-document editor, the XHTML page created during this tutorial is still loaded in the editor but it is hidden behind Copyright.html. Use Window|Untitled.html : XHTML : XHTML to switch back to our XHTML page.
  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.)

    images/modular04

  6. Use command Paste After (shortcut Ctrl-W) to paste the reference to the div after selected p. A dialog box is displayed to mainly inform you that you are pasting a reference to an external element and not ordinary data.

    images/modular05

    Click on OK.

The XHTML page now looks like this.

images/modular06

Notice that the copyright information inserted at the bottom of the page is displayed with a light 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.

images/modular07

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

    images/modular08

  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.

images/modular09

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.
  4. Switch to the window displaying our XHTML page.
  5. Select last added p.
  6. Paste copied reference to the VAT table after selected p.

After the usual confirmation dialog box, this verbose dialog box is displayed.

images/modular10

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 "VATrates.html#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 paste 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: "VATrates.html#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.

images/modular11

If you save this XHTML page or if you click on the Check Validity icon found at the bottom left of XXE window, you'll find that XXE pretends that the XHTML page is invalid: ID "france_vat" already defined (in fact, the same element is included several times from "file:/opt/xxe/doc/user/tutorial/VATrates.html#france_vat") [cvc-id.2].

You can safely ignore this warning. It is reported when a reference to an external element has been pasted several times in the same modular document. In the case of our example, it is the reference to the external span element containing the VAT rate of France which has been inserted two times.