Frontpage Stored Queries

Extending Find and Replace for Microsoft Office FrontPage 2003

Lisa Wollin
Microsoft Corporation

January 2004

Applies to:
    Microsoft® Office FrontPage® 2003

Summary: Learn the basics of creating queries that find and replace text in Microsoft Office FrontPage 2003 documents, the XML Query schema that FrontPage uses to save and reuse queries, and the Microsoft Visual Basic for Applications (VBA) objects that you can use to create your own powerful solutions to extend FrontPage. (13 printed pages)

Contents

Introduction
Creating Queries
Understanding the Query Schema
Developing Custom Find and Replace Solutions
Conclusion

Introduction

With the new find and replace capabilities in Microsoft® Office FrontPage® 2003, you can easily develop powerful find and replace solutions. Initially, the find and replace capabilities in FrontPage are similar to the find and replace capabilities in other Microsoft Office 2003 applications. However, unlike other Office applications, FrontPage uses Extensible Markup Language (XML) to perform queries. You can create queries with FrontPage by using the Find and Replace dialog box, or you can create them manually by using the simple Query schema described in this article.

Once you have created a query, you can then save it to a file, which allows you to easily reuse it or share it with others. You can also use the query strings contained in the query files to develop custom find and replace solutions by using the new SearchInfo object that is included in the FrontPage 2003 Visual Basic® for Applications (VBA) object model.

Creating Queries

You can use the Find and Replace dialog box in FrontPage to create queries. The Find and Replace dialog box provides a useful way to create queries. In the lower-right corner of the dialog box, there are two Query icons. The folder icon allows you to open saved queries, and the disk icon allows you to save queries.

To demonstrate how this works, you can use the following steps to create and save a simple query by using the Find and Replace dialog box. These steps create a query that uses the default settings.

1. On the Edit menu, click Replace.
2. Type "frist" in the Find what text box.
3. Type "first" in the Replace with text box.
4. Click the Save query button.
5. Type "NewQuery" in the Filename text box.
6. Click Save.

When you save a query, FrontPage automatically saves it with an .fpq file extension. By default, new queries are saved to the FrontPage Queries folder for the current user located at C:\Documents and Settings\<user>\Application Data\Microsoft\FrontPage\Queries. However, you can save them to any folder you want.

After following the preceding steps, you will find a saved query called NewQuery.fpq in the default folder. If you open the file in Notepad, you will see a very simple statement in the XML to find the text "frist" and replace it with the text "first".

 

Copy

<?xml version="1.0" encoding="utf-8" ?>
<fpquery version="1.0">
    <queryparams />
    <find text="frist" />
    <replace text="first" />
</fpquery>

The additional options in the Find and Replace dialog box allow you to create more complex queries. You can even create conditional queries. For example, you might want to change all occurrences of the B element to a U element but only when they occur inside of a TABLE element. This query would resemble the following XML query string.

 

Copy

<?xml version="1.0" encoding="utf-8" ?>
<fpquery version="1.0">
    <queryparams />
    <find tag="b">
        <rule type="insideTag" tag="table" />
    </find>
    <replace type="changeTag" tag="u" />
</fpquery>

Working with Regular Expressions

In addition to creating queries that find specific text and elements, you can create queries that use regular expressions. Regular expressions allow you to create patterns of characters that describe one or more strings to find when searching text or code. These are especially useful when you don't know the exact text or code that you are looking for or when you are looking for all occurrences of text or code with one or more similarities. For more information on the different regular expressions that you can use within a FrontPage find and replace, see Regular Expressions.

Understanding the Query Schema

As shown above, all the queries that you create use a custom XML schema. This relatively simple XML schema contains only five elements but provides a considerable amount of flexibility and power for creating queries that give you greater control over find and replace capabilities within FrontPage. The syntax for these elements is shown below.

 

Copy

<?xml version="1.0" encoding="utf-8" ?>
<fpquery>
    <queryparams />
    <find>
        <rule />
    </find>
    <replace />
</fpquery>

The first line of the query syntax indicates the document type declaration. The version attribute indicates that the document conforms to version 1.0 of the XML specification. The encoding attribute indicates that the XML document is encoded using the UTF-8 character set. This line is necessary for FrontPage to be able to parse the XML query string.

Note    XML stands for Extensible Markup Language. Similar to HTML, XML is a markup language designed for the Internet. However, unlike HTML, which was designed to define formatting of Web pages, XML was designed to describe data. You can use XML to develop custom schemas. As with HTML, the World Wide Web Consortium defined the specifications for XML. For more information on XML and the XML specification, see Extensible Markup Language on the World Wide Web Consortium Web site.

Query Schema Elements

The FrontPage Query schema elements are defined in detail in the following sections.

fpquery

The fpquery element is the top-level container element for FrontPage queries. This element is required and contains one required attribute.

Syntax

 

Copy

<fpquery>
    <queryparams />
    <find />
    <replace />
</fpquery>

Table 1. Attributes of the fpquery element

Attribute	Data type	Description
version	string	Required. Specifies the schema version that is being used. For FrontPage 2003, the expected value is "1.0".

queryparams

The queryparams element defines special find functions that you want FrontPage to take into consideration when executing a query. This element is optional. If omitted, all attributes default to FALSE.

Syntax

 

Copy

<queryparams/>

Table 2. Attributes of the queryparams element

Attribute	Data type	Description
matchcase	boolean	Optional.   Matches the find and replace text to the exact case as specified in the find and replace strings.
wholeword	boolean	Optional.   Matches the whole word as specified in the find string and will not locate occurrences where the text is nested within other words.
ignorewhitespace	boolean	Optional.   Matches words that are next to each other but may appear on separate lines either in code or in the page as it is displayed in the browser. If the regexp attribute equals TRUE, FrontPage ignores the ignorewhitespace attribute because a regular expression can define whether to find strings with spaces.
regexp	boolean	Optional.   Performs a find by using a regular expression.
inhtml	boolean	Optional.   Searches for the find string in the HTML source code.
diacritics	boolean	Optional.   Matches a find string that contains diacritic characters in Hebrew and Arabic text.
kashida	boolean	Optional.   Matches a find string that contains Kashida characters.
alefhamza	boolean	Optional.   Matches a find string that contains Alefhamza characters.
hangul	boolean	Optional.   Matches a find string that contains Hangul characters.

find

The find element specifies either the text or the name of the element for which to search. This element is required and contains two optional attributes; however, all find elements must contain one of the optional attributes. Additionally, this element may have one or more rule elements that specify HTML rules to apply when searching.

Syntax

 

Copy

<find>
    <rule />
</find>

Table 3. Attributes of the find element

Attribute	Data type	Description
text	string	Optional.   Specifies a find string that contains the text for which to search.
tag	string	Optional.   Specifies a find string that contains the name of the element for which to search.

replace

The replace element specifies either the replacement text or the replacement action to perform on an element. This element is optional and contains six optional attributes.

Syntax

 

Copy

<replace />

Table 4. Attributes of the replace element

Attribute	Data type	Description
text	string	Optional.    Specifies the text with which to replace the found text.
action	string	Optional.    Specifies the action to take when replacing HTML elements. Can be one of the following string values: blank   Specifies that no replace action is required when performing a search operation. none    Specifies that no replace action is required when performing a search operation. For example, <replace action="none" /> replaceTagAndContents   Replaces the element specified in the find statement and its contents with a specified HTML string. For example, <replace action="replaceTagAndContents" html="<hr>" />. replaceContentsOnly   Replaces only the contents of the element specified in the find statement with a specified HTML string. For example, <replace action="replaceContentsOnly" html="<p></p>" />. addAfterStartTag    Inserts the specified HTML string after the starting tag for the element specified in the find statement. For example, <replace action="addAfterStartTag" html="<h1></h1>" />. addAfterEndTag    Inserts the specified HTML string after the ending tag for the element specified in the find statement. For example, <replace action="addAfterEndTag" html="<p>" />. removeTagAndContents    Removes the element specified in the find statement and its contents. For example, <replace action="removeTagAndContents" />. removeTag    Removes the element specified in the find statement. For example, <replace action="removeTag" />. changeTag   Replaces the element specified in the find statement with a new element. For example, <replace action="changeTag" tag="div" />. setAttribute   Sets the value for a specified attribute for the element specified in the find statement. For example, <replace action="setAttribute" attribute="width" value="100%" />. removeAttribute   Removes a specified attribute for the element specified in the find statement. For example, <replace action="removeAttribute" attribute="align" />.
html	string	Optional. Specifies the HTML string with which to replace found text.
tag	string	Optional. Specifies the element name with which to replace a found tag.
attribute	string	Optional. Specifies the attribute for which to replace a value.
value	string	Optional. Specifies the replacement value for an attribute.

rule

The rule element specifies HTML rules that define how FrontPage should perform a find and replace operation. This element is optional and contains one required and seven optional attributes. The rule element is a child element for the find element and may be a sibling of or a parent to another rule element.

Syntax

 

Copy

<rule ...>
     <rule ... />
</rule>

The attributes of a rule element change depending on the value of the type attribute.

Table 5. Attributes of the rule element

Attribute	Data type	Description
type	string	Required. Specifies how to apply the rule to the find string. attribute   Specifies that the rule applies to an attribute. containsText   Specifies that the rule contains text. containsTag   Specifies that the rule contains the name of an HTML element. insideTag   Specifies that the find text can be found inside of an element.
attribute	string	Optional. When the type attribute equals "attribute", specifies the name of the attribute. For example, <rule type="attribute" attribute="width" compare="=" value="5" />.
compare	string	Optional. When the type attribute equals "attribute", specifies a comparison operator that indicates a comparison value for the attribute. For example, <rule type="attribute" attribute="width" compare="=" value="5" />. =   Indicates the current value is equal to the specified value. !=   Indicates the current value is not equal to the specified value. >   Indicates the current value is greater than the specified value. >=   Indicates the current value is greater than or equal to the specified value. <   Indicates the current value is less than the specified value. <=   Indicates the current value is less than or equal to the specified value. contains   Indicates the current value contains the specified value. notcontaining   Indicates the current value does not contain the specified value.
value	string	Optional. When the type attribute equals "attribute", specifies a value for an attribute comparison. For example, <rule type="attribute" attribute="width" compare="=" value="5" />.
negate	boolean	Optional. Switches the meaning of the type attribute to its opposite when the type attribute equals "containsText", "containsTag", or "insideTag". For example, when the type attribute is set to "insideTag", setting the negate attribute to "true" changes the rule to mean "Not Inside Tag". If omitted, the negate attribute defaults to "false". For example, <rule type="containsText" text="annual" negate="true" />.
text	string	Optional. When the type attribute equals "containsText", specifies the text. For example, <rule type="containsText" text="quarterly" />.
tag	string	Optional. When the type attribute equals "containsTag", specifies the name of the element. Examples, <rule type="containsTag" tag="div" negate="false" /> and <rule type="insideTag" tag="div" />.

Developing Custom Find and Replace Solutions

Add-ins are a common way to extend the functionality of Office applications. To this end, FrontPage provides the VBA object model. By using this object model, you can create powerful custom solutions that extend the find and replace functionality in FrontPage beyond what is contained in the application. For more information about how to work with the VBA object model and how to create add-ins, see Getting Started for FrontPage developers on MSDN.

In the FrontPage 2003 object model, you will find a new SearchInfo object as well two methods and several new properties that you can use to develop your own custom solutions to extend the find and replace capabilities. The following table identifies the methods and objects that you would use to create a custom find and replace solution.

Table 6. Methods and objects for find and replace

Name	Description
SearchInfo object	Provides programmatic access to find and replace capabilities in FrontPage. Use the SearchInfo object to define search queries, text, rules, and options.
CreateSearchInfo method	A member of the Application object, you would use the CreateSearchInfo method to create an empty SearchInfo object.
Find method	A member of the FPHTMLDocument object, you would use the Find method to develop more complex find and replace solutions that specify XML query strings by using the QueryContents property.
Action property	A member of the SearchInfo object, the Action property sets or returns an fpSearchAction constant that defines the type of search that you want to perform. The value of the Action property can be one of the following fpSearchAction constants. fpSearchFindTag   Searches for the specified element. fpSearchFindText   Searches for matching text in the document. fpSearchReplaceAllText   Searches and replaces all matching text in the document. fpSearchReplaceText   Replaces the text and searches for the next occurrence.
Find property	A member of the SearchInfo object, the Find property sets or returns a String that represents the text or the name of the element for which to search.
Options property	A member of the SearchInfo object, the Options property returns an FpSearchOptions constant that represents the parameters of a search. The Options property can be one or more of the following FpSearchOptions constants. fpSearchIgnoreWhitespace   Matches words that are next to each other but may appear on separate lines either in code or in the page as it is displayed in the browser. fpSearchMatchAlef   Matches a find string that specifies Alefhamza characters. fpSearchMatchCase   Matches the find and replace text to the exact case as specified in the find and replace strings. fpSearchMatchDiacritics   Matches a find string that contains diacritic characters contained in Hebrew and Arabic text. fpSearchMatchKashida   Matches a find string that contains Kashida characters. fpSearchRegExp   Performs a find by using a regular expression. fpSearchReviseHangul   Matches a find string that contains Hangul ending characters for Korean text. fpSearchWholeWord   Matches the whole word as specified in the find string.
QueryContents property	A member of the SearchInfo object, the QueryContents property sets or returns a String that is an XML representation of the query. This String must adhere to the Query schema.
ReplaceWith property	A member of the SearchInfo object, the ReplaceWith property sets or returns a String that represents the text to replace the text specified in the Find property.

Programming Find and Replace Operations

Using the above objects, methods, and properties, you can write very simple code that performs a textual find and replace. For example the following code takes the find and replace operation introduced at the beginning of this article and uses code to find all occurrences of "frist" and replace them with "first".

 

Copy

Sub SimpleFindAndReplace()

    Dim objSearch As SearchInfo

    Set objSearch = Application.CreateSearchInfo

    objSearch.Action = fpSearchReplaceAllText
    objSearch.Find = "frist"
    objSearch.ReplaceWith = "first"

    ActiveDocument.Find objSearch

End Sub

Note that the above code uses the CreateSearchInfo method to create an empty SearchInfo object. Then by using this empty object, the code specifies the action (to replace all text), the text ("frist"), and the replacement text ("first"). It then uses the Find method for the FPHTMLDocument object to execute a search by using the SearchInfo object.

Alternatively, you could use the QueryContents property of the CreateSearchInfo method along with the XML query string that you created earlier to create a comparable find and replace solution. For example, the following example does exactly the same thing as the previous example.

 

Copy

Sub QueryStringFindAndReplaceAll()

    Dim objSearch As SearchInfo

    Set objSearch = Application.CreateSearchInfo

    objSearch.QueryContents = "<?xml version=""1.0"" " & _
        "encoding=""utf-8"" ?>" & _
        "<fpquery version=""1.0"">" & _
        "<queryparams />" & _
        "<find text=""frist"" />" & _
        "<replace text=""first"" />" & _
        "</fpquery>"
    objSearch.Action = fpSearchReplaceAllText

    ActiveDocument.Find objSearch

End Sub

Note that the second example required several more lines. In this case, you set the QueryContents property to the query string that you created earlier in this article. You could also write this same code as show in the following example.

 

Copy

Sub QueryStringFindAndReplace()

    Dim objSearch As SearchInfo
    Dim objDocument As IHTMLTxtRange
    Dim objFound As IHTMLTxtRange
    Dim blnFound As Boolean

    Set objDocument = ActiveDocument.body.createTextRange
    Set objFound = ActiveDocument.body.createTextRange
    Set objSearch = Application.CreateSearchInfo

    objSearch.QueryContents = "<?xml version=""1.0"" " & _
        "encoding=""utf-8"" ?>" & _
        "<fpquery version=""1.0"">" & _
        "<queryparams />" & _
        "<find text=""frist"" />" & _
        "<replace text=""first"" />" & _
        "</fpquery>"
     objSearch.Action = fpSearchReplaceText

     Do
        blnFound = ActiveDocument.Find(objSearch, objDocument, objFound)
     Loop While blnFound = True

End Sub

The preceding example also sets the QueryContents property to the same query string. However, in this case, the code also uses the IHTMLTxtRange object. When you set the Action property to fpSearchReplaceText, you can use the Find method's two optional parameters to step through each change occurrence-by-occurrence. These two parameters require IHTMLTxtRange objects, so the code declares two different IHTMLTxtRange objects, which are then used in the Find method. The syntax for the Find method is as follows:

 

Copy

Find(info, limits, startRange)

The info parameter of the Find method specifies the SearchInfo object that contains the search text, rules, and options. Note that the second example above uses the QueryContents property to define a find and replace query, while the first example uses the Action, Find, and ReplaceWith properties of the SearchInfo object. This allows the SearchInfo object to identify the test to find and to specify the text with which to replace it.

The limits parameter specifies the IHTMLTxtRange object that represents the portion of the page against which to perform a find and replace. To search the entire document, you can use the createTextRange method of the FPHTMLBody object, as shown in the example above. This sets the limits of the range to search to the entire body of a page. However, you could also perform a find and replace against a selection by using the createRange method of the IHTMLSelectionObject object. This sets the limits for the range to search to only the text that is selected in the FrontPage window. The code to do this would look like the following example.

 

Copy

Set objDocument = ActiveDocument.Selection.createRange

The startRange parameter provides a reference to the found text. When the return value for the Find method is True, you can use the startRange parameter to select the found text. This is especially important if you want to step through a find and replace operation, stopping at each found word. In this case, you would set the Action property of the SearchInfo object equal to fpSearchReplaceText because the fpSearchReplaceText constant enables you to perform a find and replace that stops at each occurrence of found text.

Therefore, in the preceding example, if you wanted to select each occurrence as it is found, you could use the Select method of the IHTMLTxtRange object to select the returned text within the Do loop, as shown in the following sample.

 

Copy

Do
    blnFound = ActiveDocument.Find(objSearch, objDocument, objFound)
    objFound.Select
Loop While blnFound = True

Note The SearchInfo object allows you to perform textual find and replace only. You cannot perform replace operations that modify HTML. To do this, you can use the DocumentHTML property to perform a global search and replace of all occurrences of a string. The DocumentHTML property returns a string that represents both the HTML and the text for a Web page.

Programming with Regular Expressions

Using a query, you can easily perform find and replace operations that use regular expressions. To demonstrate this, the following example uses the SearchInfo object to execute a find based on a query string that uses a regular expression. The regular expression it specified is " t:a*n ". This regular expression will locate all words that start with a "t" and end with an "n". For example, it will locate tan, ten, ton, tin, and teen as well as Tennessean. The asterisk indicates that any number of letters can occur between the "t" and the "n". For more information see, Regular Expressions.

 

Copy

Sub QueryContents()
    Dim objSearch As SearchInfo
    Dim objRange As IHTMLTxtRange
    Dim objLimits As IHTMLTxtRange
    Dim strQuery As String
    Dim blnFoundMatch As Boolean

    strQuery = "<fpquery version=""1.0"">" & _
        "<queryparams regexp=""true"" />" & _
        "<find text=""t:a*n"" />" & _
        "</fpquery>"

    Set objRange = ActiveDocument.body.createTextRange
    Set objLimits = ActiveDocument.body.createTextRange
    Set objSearch = Application.CreateSearchInfo

    objSearch.Action = fpSearchFindText
    objSearch.QueryContents = strQuery

    Do
        blnFoundMatch = ActiveDocument.Find(objSearch, objLimits, objRange)
    Loop While blnFoundMatch = True
End Sub

Conclusion

As you have seen in this article, the new find and replace functionality in FrontPage 2003 provides powerful search capabilities not only within the Find and Replace dialog box but also from using the VBA object model. You can also perform searches for patterns of words by using regular expressions. These capabilities give you greater control over searches and give you the ability to share search queries and develop complex custom solutions.