Chapter 2. Tutorial: basics

Table of Contents

1. Starting XXE
2. Creating a new document
3. Inserting elements
4. Selecting elements
4.1. The implicit element selection
4.2. The text selection
4.3. The node selection
4.3.1. Most general method
4.3.2. Directly selecting a node
4.3.3. Selecting a node range
5. Navigating through elements
5.1. Using Tab to go from a #text to the other, just like in a form
5.2. XXE makes a difference between the end of a #text node and the beginning of the #text node next to it
6. Copy, cut, paste, delete
6.1. Copy, cut, paste, delete applied to the text selection
6.2. Copy, cut, paste, delete applied to the node selection
7. Splitting and joining elements
7.1. Simple Split and Join
7.2. Split and Join generalized
8. Replacing elements
9. Converting elements
9.1. Convert applied to the text selection
9.2. Convert applied to the node selection
10. Editing element attributes
10.1. Required attributes in newly created elements
11. Checking document validity

What you'll not learn by reading this tutorial

This tutorial will not teach you how to use most nifty features of XXE:

  • how to use the Ins key or the Enter key to quickly insert text nodes and elements,

  • how to change an image displayed in the document view by dragging and dropping a graphics file onto it,

  • how to quickly insert or move columns by using the table editor,

  • etc.

Most of these smart tricks are listed in chapter Being productive with XXE. Other features are specific to the type of the document being edited (XHTML, DocBook, DITA, etc) and therefore, are documented in the online help which comes with the XXE configuration associated to the document type.

No, this tutorial will just teach you the most basic way to do things. On the other hand, what you'll learn here will work for any type of document, and not only for XHTML.

This tutorial assumes that the reader has a minimal knowledge of XML (that is, the reader knows what is an element, an attribute, etc) and a minimal knowledge of HTML or XHTML (that is, the reader knows that p is the tag for a paragraph, that ul is a list, etc).

It is recommended that, using XXE, the reader repeats each action described in this tutorial. (On Mac, use the Command key instead of the Control key, except for Ctrl-Tab and Ctrl-Space.)

1. Starting XXE

  • If you have installed an auto-installable Windows distribution (xxe-perso-3_6_1-setup.exe), XXE can be started by double-clicking on the icon of xxe.exe or by using the "XMLmind XML Editor" shortcut added to the Start menu.

    If you have installed a zipped distribution, XXE can be started by typing xxe (or xxe.bat) from the command prompt, optionally followed by the name of one or several XML documents.

    Example:

    C> xxe C:\xxe-perso-3_6_1\doc\user\userguide.xml
  • On Unix, XXE can be started by typing xxe from an xterm, optionally followed by the name of one or several XML documents.

    Example:

    $ xxe &

2. Creating a new document

Use File|New and choose a document template from the following dialog box.

Figure 2.1. The File|New dialog box

The File|New dialog box

Alternatively, use File|Open as Template and choose an existing XML document. A copy of this existing XML document will be emptied to serve as the skeleton of your new document. For example, use this command to select userguide.xml (User's Guide in DocBook format) file contained in the doc/user/ subdirectory of your XXE distribution.

In this tutorial, we have chosen to create a XHTML page (strict DTD).

The newly created document (Untitled.html) looks like this:

The ``blobs'' are placeholders for text. Click on the first placeholder and type the title of your XHTML page. Click on the second placeholder and type a few words.

Click again anywhere on the title and then anywhere in the first paragraph. You'll notice that, at the top of the window, just below the tool bar icons, the node path bar changes its label.

The node path bar shows where is the caret (also called insertion cursor).

The node path bar does so by displaying the name of the node (anonymous text node #text) containing the caret preceded by the name of each of its ancestors elements in the containment hierarchy (element p contained in element body contained in element html).

3. Inserting elements

In this section, we'll get familiar with the following commands:

  1. Insert before element

  2. Insert inside element, at caret location

  3. Insert after element

These commands are accessible using the Edit menu bar menu, using the Edit tool ``tab'' or using keyboard shortcuts, but in this tutorial we'll limit ourselves to using the Edit popup menu. Therefore the notation Edit|Insert means "click anywhere in the document view using the right mouse button and select menu item Insert in the Edit popup menu".

Figure 2.2. The Edit popup menu

The Edit popup menu

Click anywhere inside the paragraph and execute Edit|Insert Before. The keyboard focus is given to the Edit tool. This pane now lists all the elements you can insert before a p and therefore, is ready to use.

Figure 2.3. The Edit tool listing all elements you can insert before a p

The Edit tool listing all elements you can insert before a p

Select h1 from the list (a single click on the list item is sufficient). The newly inserted element has a red border around it. Do not care about that, just type the text of the heading and the red border will go away.

Click inside the p before a word and execute Edit|Insert, the same element chooser dialog pops up listing all the inline elements you can insert inside a p. Select strong from the list and type a few words in bold font.

Your document should look like this:

This time, use Edit|Insert After and add a ul (unordered list) after the p. Type the text of the first list item (li).

If you are in the strong element -- check it with the node path bar -- click in the p outside the bold words because inserting an ul inside a p after a strong is not allowed in XHTML.

Click to get rid of the red border, then using what you have learned, add two more lis: one before the first li you have created, the second after it.

4. Selecting elements

Editing commands are applied to the selection.

XXE supports three types of selection:

  • The text selection, found in all text editors and word processors.

  • The node selection, which can contain one or several nodes.

  • The implicit element selection.

Some commands can be applied to any type of selection, for example: Edit|Convert. Other are more restrictive, for example: Edit|Insert Before can be applied to the implicit element selection or to an explicit single node selection.

4.1. The implicit element selection

The element containing the caret is implicitly selected. Therefore you can apply commands to it without making any special effort.

This is one of XXE nicest feature, even if it needs to be learned because it has no equivalent in the word processor world.

In the first section of this tutorial, you have already used the implicit element selection to insert an h1 before the p and an ul after it.

4.2. The text selection

Selecting text in XXE is not different from selecting text in any text editor. Click in the middle of the h1 and drag the mouse across the document until the middle of the second li is reached.

4.3. The node selection

4.3.1. Most general method

Now we want to add a pre (preformatted text) after the ul.

We have learned that clicking inside the a li implicitly selects it therefore we know how to add a new li after this one but how to select its parent, the ul, to add a pre after it?

For that we need to use explicit element selection. Click inside any li and then click on word ul inside the node path bar.

This explicitly selects the corresponding node in the document view.

Note that explicitly selected nodes are drawn with a red border around them.

Alternatively, click inside any li and type Ctrl-Up 3 times: first time to select the #text node, second time to select the li, third time to select the ul.

Now that ul is selected, use Edit|Insert After to add a pre after it.

Type 2 lines of text in this pre. Do not be worried by the ``carriage return icon'' always displayed by XXE if the last character of a #text node is a newline character.

4.3.2. Directly selecting a node

Clicking near some text moves the caret inside the text and no node is explicitly selected.

Instead of simply clicking, try to Ctrl-click on the first p. A #text node is explicitly selected and the node path bar tells you which one.

Selecting a #text node is rarely what you want to do. You'll often need to Ctrl-click again without moving the mouse. This will select to parent of the selected #text, that is, the p. Ctrl-clicking again without moving the mouse would select the parent of the p which is a body and so on. When doing a series of Ctrl-clicks, always look at the node path bar to know precisely where you are. Also, do not Ctrl-click several times too fast otherwise the editor will think you are double-clicking or triple-clicking and therefore, selecting elements that way would not work.

Click on the first p to cancel the selection because we are going to study another method to select it. Now try to Ctrl-click, not inside the text itself, but in the blank space at the right of the text of first p. Notice that one Ctrl-click is sufficient to directly select the whole p.

Similarly, you can directly select a node when a non-editable ``decor'' has been generated for it. For example, simply click on the bullet of a li to select it. This type of non-editable decor is very common, for example: the image displayed for a figure, the number of a section, the border of a table, a node icon or element name in the tree view, etc.

4.3.3. Selecting a node range

What if you want to put first p and ul inside a blockquote? The answer is select both of them first and then use Edit|Convert (described below in this tutorial).

With XXE it is possible to select a node range, that is, adjacent children of the same parent element.

Select first p using any of the methods described above.

Then Ctrl+Shift-click anywhere on the ul.

Note that extending the node selection is easy because you do not have to be precise. The reason is that there is no ambiguity about what to select: a #text or a li is not a sibling of first p, only the ul is a sibling of first p.

Alternatively, you could have typed Esc then Right to extend node selection to the ul.

Now use Edit|Convert and choose blockquote.

5. Navigating through elements

5.1. Using Tab to go from a #text to the other, just like in a form

The Tab key may be used to move the caret from the current #text to the beginning of the next one. Shift-Tab moves the caret from the current #text to the beginning of the previous one.

Click on the title and use Tab and Shift-Tab to move the caret from one #text to the other.

What if you really want to insert a Tab character into a pre (or any element which allows Tab characters to be inserted in the text flow just as any ordinary character)? The answer is: type Ctrl-Tab instead of Tab.

5.2. XXE makes a difference between the end of a #text node and the beginning of the #text node next to it

The simplest way to move the caret is of course to use the Left or Right arrow keys.

Click on the first p to the left of the strong and press on the Right key to move the caret in the direction of the strong.

Just before reaching the strong element, you'll notice that pressing on the Right key has caused no perceptible caret movement. Then after this ``dead'' Right key, the caret seems to move as expected.

Go back to the left using the Left arrow and at the p/strong boundary, you'll notice a ``dead'' Left key then the caret seems to move as expected.

Note that on the p/strong boundary, the caret makes no visible movement but the node path bar displays different paths (html·body·p·#text and html·body·p·strong·#text).

Use menu command View|Add to add a low-level, hierarchical, view called the tree view, at left of the styled view.

Figure 2.4. Both tree and styled Views side by side

Both tree and styled Views side by side

Repeat what you have done with the Right and Left arrow keys and you'll notice that with the tree view, there is a visible caret movement from the end of the p·#text to the beginning of the strong·#text and vice-versa.

Close the tree view by clicking anywhere inside it and by using View|Close.

This ``dead'' key behavior also occurs when using the Del and Backspace keys.

Click on the first p to the left of the strong and type on the Del key several times. Notice what happens on the p/strong boundary. Then use Edit|Undo as many times as needed to undo this typing.

Click inside the strong and type on the Backspace key several times. Notice what happens on the p/strong boundary. Then use Edit|Undo as many times as needed to undo this typing.

6. Copy, cut, paste, delete

6.1. Copy, cut, paste, delete applied to the text selection

The text selection is used not only to specify a range of characters but also a range of nodes and child elements contained in a common ancestor element.

When applied to the text selection, the Edit|Copy menu command copies all the characters and nodes in the specified range to the system clipboard. It is then possible to paste these characters and nodes in any other application including XXE itself.

Select the characters displayed in bold font from the first p, copy them to the clipboard using Edit|Copy, click on the title and paste the copied characters using the Edit|Paste.

After copying the text selection, you'll notice that, near the Clipboard Content button, the status bar displays #text: a piece of text is stored in the clipboard.

Note that if you have not been precise when selecting text, the status bar may display strong (you have copied the whole strong element to the clipboard) or it may display [2] (you have copied 2 nodes to the clipboard: the strong element and a piece of text next to it).

Edit|Cut and Edit|Delete basically work the same: they delete all the characters and nodes in the range specified by text selection. The only difference is that Edit|Cut copies the characters and nodes in the specified range to the clipboard.

Of course, elements and nodes are deleted only if the DTD or schema constraining the document allows to do so. In this is not the case, selected characters are removed from such elements and nodes and that's it.

6.2. Copy, cut, paste, delete applied to the node selection

The Copy, Cut, Paste, Delete commands can be applied to a node range or to the implicitly selected element.

Two more Paste commands are available: Paste before and Paste after. These commands can only be applied to a single explicitly selected node or to the implicitly selected element.

Select the first li (implicit selection is fine for that). Use the Edit|Cut to move it to the clipboard. Select the last li. Use the Edit|Paste After to paste the li stored in the clipboard after the last li.

After copying the first li, you'll notice that the status bar displays li: a list item element is stored in the clipboard.

Note that when the clipboard contains a node range, the status bar displays the number of nodes of the range. For example, copy all list items to the clipboard and you'll see:

7. Splitting and joining elements

7.1. Simple Split and Join

Click in the middle of the strong contained in the first p. Type Enter. The p is split in two parts, each part being a p, as expected in any word processor.

Now type Backspace at the beginning of the second part. The two parts are joined to form our original single paragraph.

Typing Del at the end of the first part would have given the same result.

This is also a handy method for inserting elements. Type Enter at the end of the p.

Type some text in the newly created paragraph. Type Enter at the beginning of newly created p. This creates another p before it.

Use Edit|Undo three times to undo the creation of last two paragraphs.

7.2. Split and Join generalized

The Split and Join commands bound to Enter, Backspace or Del keystrokes are very handy but they can only be applied to paragraphs.

What if we want to split the list in two parts in order to insert a paragraph before the second part?

Move the caret at the beginning of the last list item and explicitly select the whole list using the node path bar.

Now execute Edit|Split. This command splits the explicitly selected element at caret position, which gives us two adjacent lists.

The generalized form of Join is the inverse command of Split. Command Join joins explicitly selected element to its preceding sibling, an element of same type.

Note that the generalized form of Split and Join are the only commands that cannot be applied to the implicitly selected element.

Explicitly select the second ul and execute Edit|Join. The two adjacent lists are now joined to form our original single list.

Undo last Join because we really want to split the list in two parts.

  • Add a p before the second ul, type some text in it.

  • Copy text "List item #1" (as usual, by dragging the mouse and by pressing Ctrl-C) and paste it (by pressing Ctrl-V) in the empty last li of first ul.

  • Add another li before the only li of second ul, for example by clicking in the li, using Edit|Copy and then using Edit|Paste Before.

  • Change all the text of the two list items of the second ul, for example by selecting "List item #1" as usual and by typing a few words.

Our XHTML document now looks like this.

8. Replacing elements

The Edit|Replace command is equivalent to deleting the node selection or implicitly selected element and inserting a new element or #text which replaces the deleted nodes.

This command is useful because it is often not allowed to delete the selection: doing so would create an invalid document.

Select the pre. Insert a table after it.

table(head_column), ..., table(head_row_column) are preconfigured table templates. Most of the time, you'll choose one of these but for this exercise, we'll choose table which is the simplest table possible in XHTML.

The table is created with a single tr (row) containing a single th (a ``heading'' cell where text is displayed using a bold font). This is often what you want for the skeleton of table but not always.

This very simple table has no borders, even if the footprint of a cell is displayed using a very light gray. This would make the screenshots of this tutorial hard to read. Therefore we'll immediately add a border to this table.

Select the table (using the node path bar) if it is not already the case. The Attributes tool should be already displayed, otherwise click on the corresponding tab.

First row of the attribute table is for attribute border. Click inside the attribute value cell at the right of the attribute name cell containing border, type 1 and press Enter.

Now the table has a nice black border. (We'll learn how to use the Attributes tool later in this tutorial.)

Exercise:

  1. Select the th contained in the tr (implicit selection is fine for that). Using Edit|Replace, replace it with a td (a plain cell).

  2. Select this td. Use Edit|Insert After to add another td after it.

  3. Using the node bar path, select the tr containing the two cells . Use Edit|Copy to copy it to clipboard.

  4. Use Edit|Paste After to paste a copy of the tr after currently selected tr.

  5. Type some text in each cell.

9. Converting elements

9.1. Convert applied to the text selection

Select a non-bold word in the first p.

Use the Edit|Convert to convert it to em (emphasis).

Remember that text selection is used not only to specify a range of characters but also a range of nodes and child elements contained in a common ancestor element. This feature is very useful when doing a conversion. For example: select text from word "paragraph" to word "XMLmind".

Use the Edit|Convert to convert it to button.

Use Edit|Undo to undo the last conversion.

9.2. Convert applied to the node selection

Converting a #text node rather than an equivalent text selection is often more convenient.

Select the #text node contained in the first cell of the table. Note that explicit node selection is needed to do that: implicit element selection selects the td not the #text inside it.

Used Edit|Convert to convert it to em.

Unlike Edit|Replace which creates an empty new element, Edit|Convert transfers the content of the selection to the new element which is the result of the conversion.

More precisely, in the case of the node selection:

  • When several nodes or a single non-element node are selected, all these nodes are given a new parent element which is the result of the conversion.

    We have already seen two examples of this behavior. First one is when we ``wrapped'' a p and a ul into a blockquote. Second one is just above.

  • When a single element is selected, all its children (but not its attributes) are transferred to the result of the conversion.

    What follows is an example of this second behavior. Here we want to ``morph'' single selected element which is an ul to an ol.

Select the first ul.

Used Edit|Convert to convert it to an ol (ordered list).

This operation is valid because the ul parent, a body, accepts uls as well as ols at this place and because the element content of this ul is ``compatible'' with an ol.

10. Editing element attributes

Use Tools|Edit Attribute (keyboard shortcut Ctrl-E) to edit the attributes of the selected element. This action displays and gives the keyboard focus to the Attributes tool. Alternatively, if this pane is already displayed, you can click inside it and use it right away.

Figure 2.5. The Attributes tool with the rowspan attribute of a td being edited

The Attributes tool with the rowspan attribute of a td being edited

There are two methods for adding or changing the attributes of the (explicitly or implicitly) selected element:

  1. Using the attribute form (the upper side of the Attributes tool).This should be the method of choice for persons who prefer to use the keyboard.

  2. Using the attribute table (the lower side of the Attributes tool). This should be the method of choice for persons who prefer to use the mouse.

The ``minus'' button of the attribute form can be used to remove an attribute. Removing an attribute directly from the attribute table is possible too: simply right-click on the attribute row and use the displayed popup menu.

The content of the attribute table can be described as follows:

  • All attributes set for the selected element are displayed by the table.

  • All possible attributes for the selected element, even those not set, are also displayed by the table.

    Attributes which have not been set are displayed in gray. Attributes which have been set are displayed in black.

  • Attributes are listed sorted in alphabetical order.

  • The names of required attributes are displayed using a bold font.

  • The names of fixed attributes are displayed using an italic font.

Exercise:

  • Select second td in the table. Set its align attribute to center.

  • Set its rowspan attribute to 2.

  • Set its valign attribute to middle.

  • Add an extra td after it to make the table look more balanced.

10.1. Required attributes in newly created elements

It is important to remember that, by default, XXE automatically gives a placeholder value ("???") to required attributes of newly created elements. This means that you have to replace this placeholder value by the actual one as soon as the element has been created.

Add a p after the table using Edit|Insert After and insert an img in it using Edit|Insert.

The img has two required attributes src and alt. XXE has set those attributes to string ???. Use the Attributes tool to give these attributes an actual value.

For this img, we used XXE_install_dir/doc/user/tutorial/xxe.gif and XMLmind logo for alt (directory XXE_install_dir/doc/user/tutorial/, generally C:\Program Files\XMLmind_XML_Editor\doc\user\tutorial\, contains all the files used in this tutorial) .

The useless #text node has been removed by explicitly selecting it and using Edit|Delete.

11. Checking document validity

You cannot check the validity of a document without an associated DTD, W3C XML Schema or RELAX NG schema. When editing a document not constrained by a grammar, XXE guarantees that what you'll create will be well-formed without making any special effort.

This section, like most of this tutorial, describes the behavior of XXE when editing documents constrained by a grammar.

Checking document validity is automatically performed each time you save your document.

Unless you use Edit|Force Deletion, XXE will never allow editing commands that would make the document structurally invalid (a document where some elements have invalid child elements or attribute names).

Therefore explicitly checking document validity is rarely needed. You may have to use the Tools|Check Validity command when:

  1. You have loaded an invalid document and you are fixing it. After each editing command, you want to know if it is fixed now.

  2. XXE creates elements where the value of required attributes, if any, is invalid: unless configured differently, the required attributes are given ??? as a placeholder value.

After explicitly or implicitly checking document validity, its validity status is displayed at the left of the status bar.

Figure 2.6. After forcing the deletion of all the items of a list, "Untitled.html" is structurally invalid.

After forcing the deletion of all the items of a list, "Untitled.html" is structurally invalid.

The Validity tool ``tab'' displays validity error messages if any.

Figure 2.7. Validity error message displayed after forcing the deletion of all the items of a list.

Validity error message displayed after forcing the deletion of all the items of a list.

The color of the message reflects the severity of the error. Clicking on the number of an error message selects the element where the validity error was found.