2. The "Find and Replace Element" dialog box

Selecting menu item SearchFind and Replace ElementFind and Replace Element displays the following modal dialog box:

Figure 9.2. The "Find and Replace Element" dialog box
The "Find and Replace Element" dialog box

Note that selecting SearchFind and Replace ElementFind Element displays the "Find Element" modal dialog box, a simplified variant of the "Find and Replace Element" dialog box.

Figure 9.3. The "Find Element" dialog box
The "Find Element" dialog box

"Find element" fields are:

Whose name is

Search for an element having any of specified names. This field may contain one or more qualified XML names (e.g. p, html:li) or wildcards (e.g. *, svg:*). The namespace prefixes, if any, used in specified names must have been declared in the document being edited. An empty field may be used to specify “any name”, which is equivalent to wildcard "*".

Having attribute

Search for an element having any of specified attributes. This field may contain one or more qualified XML names (e.g. href, xml:lang) or wildcards (e.g. *, xlink:*). The namespace prefixes, if any, used in specified names must have been declared in the document being edited. An empty field may be used to specify “any name”, which is equivalent to wildcard "*".

The combobox and the text field below the checkbox specify the attribute value searched for:

Equals

A matching attribute value is equal to the text specified in the field.

Contains

A matching attribute value contains the text specified in the field.

Contains item

A matching attribute value contains a list of items separated by whitespace, one of these items being the text specified in the field.

Matches RE

A matching attribute value contains a substring matching the regular expression pattern specified in the text field.

Containing text

Search for an element containing directly or indirectly[17] specified text.

The combobox and the text field below the checkbox specify the text searched for:

Equals

A matching text is equal to the text specified in the field.

Contains

A matching text contains the text specified in the field.

Matches RE

A matching text contains a substring matching the regular expression pattern specified in the text field.

Direction
Up

Next search/replace operation starts at explicitly or implicitly selected node and ends at the beginning of the document (backwards search/replace).

Down

Next search/replace operation starts at explicitly or implicitly selected node and ends at the end of the document.

"Replace in found element" fields are:

Name

Change the name of found element to specified name (equivalent to using EditConvert). This field contains a qualified XML name (e.g. p, html:li). The namespace prefix, if any, used in specified name must have been declared in the document being edited.

Found attribute

Replace the value of found attribute. Found attribute is the attribute that is searched for using the "Having attribute" field.

For a given element, several attributes may match the search criteria. In this case, the replace operation described below applies to all matching attributes.

The combobox and the text field below the checkbox specify the attribute change:

Replace all occurrences

Replace all occurrences of the substring searched for by the text specified in the field.

If there is no substring searched for ("-" is selected in the "Having attribute" combobox), set the value of found attribute to the text specified in the field.

Set to

Set the value of found attribute to the text specified in the field.

Delete

Remove found attribute.

Other attribute

Add, replace or delete an attribute other than the found attribute (see "Found attribute" above). This field contains a qualified XML name (e.g. href, xml:lang). The namespace prefix, if any, used in specified name must have been declared in the document being edited.

The combobox and the text field below the checkbox specify the attribute change:

Set to

Set the value of this other attribute to the text specified in the field.

Delete

Remove this other attribute (if it exists).

Text

Add, replace or delete some text contained in found element.

The combobox and the text field below the checkbox specify the text change:

Replace all occurrences

Replace all occurrences of the substring searched for by the text specified in the field.

If there is no substring searched for ("-" is selected in the "Containing text" combobox), set the text contained in the element to the text specified in the field.

Set to

Set the text contained in the element to the text specified in the field.

Delete

Delete all the text contained in the element.

[Note]Using the "Find and Replace Element" dialog box is safe

You cannot make your document invalid by using any of the above replace operations. For example, you cannot convert an XHTML p to an ul. Other example, you cannot add attribute xml:id="1 2 3" to a DocBook section.

When one of the replace operations specified using the "Find and Replace Element" dialog box would make the document invalid, an error dialog box is displayed and the element in which replacements were to be made is skipped.

Buttons are:

Find

Find next element meeting specified search criteria and select it.

Replace

If currently selected element does not meet specified search criteria, search for next element meeting search criteria and select it (that is, behave as if button Find was clicked).

If currently selected element meets specified search criteria, make specified replacements (if any) in it, then search and select next element meeting search criteria.

Replace All

Starting at explicitly or implicitly selected node, make specified replacements in all elements meeting search criteria.

Reset

Clears all "Find element" fields and all "Replace in found element" fields.

History

Displays a list containing entries for last specified "Find Element" and "Find and Replace Element" operations.

Figure 9.4. The popup list displayed by the "History" button.
The popup list displayed by the "History" button.

An entry corresponding to a "Find and Replace Element" operation is two lines long. Selecting such entry initializes both the "Find element" fields and the "Replace in found element" fields. It's possible to use this kind of history entry within the simplified "Find Element" dialog box but in the case, the replace operations (which were specified in the "Replace in found element" fields) are ignored.

An entry corresponding to a "Find Element" operation is one line long. Selecting such entry initializes just the "Find element" fields. It's possible to use this kind of history entry within the "Find and Replace Element" dialog box but in the case, all the "Replace in found element" fields are cleared.

Example 9.1. DocBook example: change the ID of an element and update all links to this element
  1. Check Having attribute.

    1. Select Contains item in the combobox.

    2. Type the old ID (e.g MyID) in the text field.

  2. Check Found attribute.

    1. Select Replace all occurrences in the combobox.

    2. Type the new ID (e.g. MyNewID) in the text field.

  3. Click Replace All.

This use case is depicted in Figure 9.2, “The "Find and Replace Element" dialog box”.

Example 9.2. XHTML example: add attribute target="_blank" to all external links
  1. Check Having attribute.

    1. Select Matches RE in the combobox.

    2. Type "^http(s)?://" in the text field.

  2. Check Other attribute.

    1. Type "target" in first text field.

    2. Select Set to in the combobox.

    3. Type "_blank" in second text field.

  3. Click Replace All.



[17] Part or all of the searched text may be contained in descendants of this element.