http://www.xmlmind.com/xmleditor Contents Install Command reference APPENDIX D: Enhancements and bug fixes

4 Tutorial

4.1 Starting XXE

Tips:

4.2 Creating a new document

A new document is simply a copy of an existing document template chosen using the File->New dialog box:

filenew0

The File->New dialog box, the first time XXE is started, may contain no document templates

Click on the icon at the top right of the dialog box and select the page.html template contained in the template sub-directory of your XXE distribution. (In the following figure, the distribution directory is /home/hussein/src/xmledit/distrib):

filenew1

Note that the file: prefix has been automatically prepended to the file name selected using the standard file chooser dialog box. It is also possible (and even recommended) to specify templates hosted by a Web server. In which case, you'll need to enter the full URL of the template including the http:// prefix.

User preferences are persistent (stored in ~/.xxe on Unix and in C:\winnt\Profiles\<user>\xxe.ini on Windows), so adding templates to the File->New dialog box is done once for all.

Tips:

4.3 Inserting elements

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

doc0

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.

doc1

Click again anywhere on the title and then anywhere in the first paragraph. You'll notice that, at the top of the window, some tool bar icons change their state from disabled (grayed) to enabled (colored)

toolbar

and at the bottom of the window, the selected element path tool changes its label.

subpathp

The path tool shows precisely which element is currently selected, i.e. the document object you can act upon using the Edit menu commands (or their tool bar icon equivalent).

The path tool does so by showing the type name (p, title, etc) of the selected element and the type name of each of its ``ancestors'' in the containment hierarchy (body, head, html, etc).

In this section, we'll get familiar with only three Edit menu commands:

inserticons

  1. Insert before selected element
  2. Insert inside selected element, at text cursor location
  3. Insert after selected element

Click anywhere inside the paragraph and click on the Insert before icon. A dialog box shows up, listing all the element types you can insert before a p (the element type name, also called the tag, of a paragraph is called p in XHTML).

tagchooseh1

The tag chooser dialog box

Select tag h1 and type the text of the heading.

Click inside the p before a word and click on the Insert inside icon, the same tag chooser dialog pops up listing all the inline elements you can insert inside a p. Select tag strong and type a few words in bold font.

Your document should look like this:

doc2

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

doc3

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

Using what you have learned, add two more lis: one before the first li you have created, the second after it.

doc4

Tips:

4.4 Selecting elements

4.4.1 Element and #PCDATA selection

select1icons

The Select Parent and Select Child tool bar icons

Clicking on some text moves the text cursor (AKA caret) to the mouse click location and implicitly selects the element containing the piece of text.

It is also possible to explicitly select elements.

Click on the first p outside the strong and then click on the Select Parent tool bar icon (or type Ctrl-Up arrow).

doc5

Explicitly selected objects are surrounded by a red line.

The path tool indicates that #PCDATA is selected. #PCDATA is not an element type name, it is used to specify an anonymous piece of text contained in some elements like p.

Click on the strong element and type Ctrl-Up as long as the selected object changes and observe what is displayed by the path tool: first the #PCDATA contained in the strong is selected, then the strong itself, then the p, then the body containing the p and finally html itself.

Click on the Select Child tool bar icon (or type Ctrl-Down arrow) as long as the selected object changes and observe what is displayed by the path tool.

Selecting objects by directly clicking on them is possible too. There are two ways to do so:

  1. Click in the path tool on the element type name you want to select.

    Example: try to click in the path tool on the word body.

  2. Ctrl-click-1 on some text always selects the corresponding #PCDATA, which is rarely what you want to do. Ctrl-click-1 on the margin or on anything not editable (such as the bullet of a li) surrounding an element generally selects this element.

    Example 1: Ctrl-click-1 on the text of the title. Then Ctrl-click-1 on the left or right margin surrounding the text of the title. Notice the difference.

    Example 2: Ctrl-click-1 on the text of a li. Then Ctrl-click-1 on the bullet of the li. Notice the difference.

    Note that If you do not click near text (for instance, if you click on an image or on generated content), you don't need to hold the Ctrl key pressed while clicking. In such case, there is no ambiguity and a plain mouse click is sufficient.

4.4.2 Text selection

The customary text selection found in all word processors is also available in XXE.

Click in the middle of the title and drag the mouse across the document until the middle of the second li is reached.

doc6

Note that the path tool displays html.head.title.#PCDATA, the place where the text selection begins.

Clicking on some text or using the Escape key cancels the explicit selection whatever its nature.

In summary, you can use 3 different types of selection:

  1. The implicit text container element selection.
  2. The explicit #PCDATA or element selection.
  3. The text selection.

All these types of selection differ by the type of editing commands you can apply to them. Only one type of selection is possible at a time.

Tips:

4.5 Navigating through elements

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

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

Inside an element which allows tab characters to be inserted in the text flow just as any ordinary character (example: an XHTML pre), you must use Ctrl-Tab and Shift-Ctrl-Tab instead.

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 type on the Right key to move the caret in the direction of the strong.

Just before reaching the strong element, you'll notice that typing 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.

This is not a bug. On the p/strong boundary, the caret makes no visible movement but the path tool displays different implicitly selected elements (p and strong).

Use menu command Style->NoStyleSheet to view the document using a low-level hierarchical view.

doc7

In this figure, for more compactness, the head, h1, and ul elements have been collapsed by clicking on the arrow located at the left of each element type name

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.#PCDATA to the beginning of the strong.#PCDATA and vice-versa.

Switch back to the styled view using the Style->xhtml command (xhtml is the name of the CSS style sheet used by the document template).

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. Notice what happens on the p/strong boundary. Then use Edit->Undo (Ctrl-Z) to undo this typing.

Click inside the strong and type on the Backspace key. Notice what happens on the p/strong boundary. Then use Edit->Undo to undo this typing.

Tips:

4.6 Copy, cut, paste, delete

cutpasteicons

The Cut, Copy, Paste before, Paste, Paste after, Delete tool bar icons

4.6.1 Text selection

When applied to the text selection, the Edit->Copy menu command copies all the selected characters to the system clipboard. It is then possible to paste these characters in any other application including XXE itself.

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

doc8

After copying the text selection, you'll notice that the clipboard tool at the bottom of the XXE windows displays #PCDATA: a piece of text is stored in the clipboard.

clippcdata

Edit->Cut and Edit->Delete basically work the same way: they delete all the selected characters from the document. The only difference is that Edit->Cut copies the deleted characters to the clipboard.

Note that these commands also eagerly delete empty text container elements contained in a parent text container element.

Click in the middle of the title and drag the mouse across the document until the middle of the second li is reached. Then click of the Delete tool bar icon.

doc9

The strong element in the first p has been deleted because it was an empty text container element contained in a text container element.

The h1, p, li, while being empty text container elements, have not been deleted because they are contained in a non text container element (body, ul).

Use Edit->Undo (Ctrl-Z) to undo this command.

4.6.2 Element and #PCDATA selection

The Copy, Cut, Paste, Delete commands can operate on the selected element (whether implicitly or explicitly selected) or #PCDATA too.

For this type of selection, two more commands are available: Paste before and Paste after.

Select the first li. Use the Cut tool bar icon to move it to the clipboard. Select the last li. Use the Paste after tool bar icon to paste the li stored in the clipboard after the last li.

doc10

After copying the first li, you'll notice that the clipboard tool at the bottom of the XXE windows displays li: a list item element is stored in the clipboard.

clipli

Tips:

4.7 Splitting and joining elements

splitjoinicons

The Split and Join tool bar icons

The Edit->Split command may be used to split the selected text container element in two, the split point being specified by the caret position. This command will not operate on any other selected object.

Click in the middle of the strong contained in the first p. Use the Split tool bar icon to split the strong in two. Nothing visible happens.

There is no bug here. Switch to the tree view using Style->NoStyleSheet to see what really happened.

doc11

Two adjacent strong elements have been created and the boundary between these two elements is not visible using the style view.

Use Edit->Undo (Ctrl-Z) to undo the split and switch back to the styled view using Style->xhtml.

Click in the middle of the strong contained in the first p. Use Ctrl-Up to explicitly select the p.

doc12

Type Ctrl-Enter (the keyboard shortcut for Edit->Split) to split the p containing the strong in two.

doc13

The Edit->Join (keyboard shortcut Ctrl-Backspace) is the inverse command of Edit->Split. It concatenates the selected element with the preceeding one, if this preceeding element is of the same type (i.e. you cannot join a p with a pre).

When two elements are joined, if the first child element of the selected element and the last child of its preceeding element can be joined, they are joined too. And this happens at all nesting levels to really make Edit->Join the inverse command of Edit->Split.

Select the p created by the split command described above, for example by clicking on it and then using the selected element path tool.

doc13a

Type Ctrl-backspace to join this p to the previous one, then undo the command by typing Ctrl-Z.

Tips:

4.8 Replacing elements

replaceicon

The Replace tool bar icon

The Edit->Replace command is equivalent to deleting the selected element or #PCDATA and inserting a new element or #PCDATA which replaces the deleted element.

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

Select the ul. Insert a table after it.

doc14

The table is created with a single tr (row) containing a single td (cell). This is often what you want as a table template but not always.

Select the tr. Use the Replace tool bar icon to replace it with a tbody.

tagchoosetbody

As an exercise, select the td contained in the tr contained in the tbody and replace with a th (another type of cell). Then add one more row. Each row must contain a th followed by a td.

doc15

Tips:

4.9 Converting elements

converticon

The Convert tool bar icon

4.9.1 Text selection

When applied to the text selection, the Edit->Convert command

  1. deletes all the selected characters (like Edit->Cut or Edit->Delete, it also eagerly deletes empty text container elements contained in a parent text container element);
  2. puts all the deleted characters in the chosen element or #PCDATA (the target of the conversion);
  3. inserts this newly created text container at the location where the text selection starts.

As a simple example, select a non-bold word in the first p.

doc16

Use the Convert tool bar icon to convert it to em (emphasis).

doc17

As a harder to understand example, select some text from the middle of the strong in the second p to the end of this p.

doc18

Use the Convert tool bar icon to convert the text selection to strong. But there is a trick here: because the text selection starts in the strong, you must specify #PCDATA when prompted by the tag chooser dialog.

doc19

Note that the tag chooser dialog proposes strong as a valid choice, because in XHTML, it is possible to have a strong contained in a strong.

4.9.2 Element and #PCDATA selection

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

Select the #PCDATA contained in the second cell of the table.

doc20

Type Ctrl-T (the keyboard shortcut of Edit->Convert, T is for Translate) to convert it to em.

doc21

Unlike Edit->Replace which creates empty elements, the Edit->Convert command transfers the content of the source element (but not its attributes) to the target converted element.

Select the ul.

doc22

Type Ctrl-T to convert it to an ol (ordered list).

doc23

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.

4.10 Editing element attributes

Use Tools->EditAttributes (keyboard shortcut Ctrl-E) to edit the attributes of the selected element.

atteditrowspan

The Attribute Editor dialog box with the rowspan attribute of a td being edited

This dialog box can be quickly described as follows:

Type Ctrl-E to pop up the attribute editor. Select a td in the table. Set its align attribute to center, its rowspan attribute to 2, its valign attribute to middle. Add an extra td to make the table look more balanced.

doc24

It is important to remember that XXE automatically gives a dumb value to required attributes of newly created elements (otherwise the document would be invalid). This means that you have to replace this dumb value by the actual one as soon as the element has been created.

Add a p after the table and insert an img in it.

doc25

The img has two required attributes src and alt. XXE has set those attributes to string '?'.

Use the attribute editor to give these attributes an actual value.

doc26

(In this figure, we used file:/usr/local/httpd/icons/apache_pb.gif for src and Powered by Apache for alt.)

Notes about images:

4.11 Checking document validity

You cannot check the validity of a document without an associated DTD. (When editing a document without a DTD, 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 with an associated DTD.

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

Unless the DTD is ill-formed, XXE will never allow editing commands that would make the document structurally invalid (a document where some elements have invalid sub-elements or attribute names).

Therefore explicitly checking document validity is rarely needed. You may have to use the Tools->CheckValidity 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 the attribute is invalid.

    This almost always occurs with an element which has an attribute of type IDREF (a reference to another element identified by a unique ID).

    It is possible to create this type of element before creating any element identified by a unique ID.

    In such case, XXE cannot automatically give to the IDREF attribute a valid value, and for this reason, your document is temporarily invalid.

After explicitly or implicitly checking document validity, its validity status is displayed at the bottom left of the window using the same icon but with three different colors.

statusinvalid

Icon color Meaning
No icon at all Document is valid
Yellow Cross-reference problems
(ex. an IDREF attribute contains a reference
to a non-existent ID)
Orange Invalid attribute names or values
(other than cross-reference problems)
Red Invalid element content

When the validity status changes from any color to red, XXE changes its editing mode from normal (strict) to repair (lenient). It will always signal this transition by popping up a dialog box.

repairmode

In repair mode, in order to fix an invalid document, you are allowed to insert and delete elements more liberally than in the normal, strict mode.

Invoking the Tools->CheckValidity command will pop up a non-modal dialog box listing all validity errors, if such errors are detected.

checkvalid

Clicking on an error number will select the corresponding invalid element and will scroll the XXE window to make it visible.

Tips: