Performing Text Replacements in a Webclass

See Also

Text replacements are useful in situations where you are generating some parts of your HTML page on the fly. For example, you might want to personalize a Web page with the user's name, as entered on a previous page in your application. You could insert a replacement indicator in the .htm file, then replace it at run time with the user's name.

In a more complex example, suppose you want to populate a table with the results of a database query. You can use replacement indicators in the HTML for the table to mark where information should go, then replace these indicators with the retrieved information after your query runs.

The process of performing text replacements involves scanning a webclass template file for special indicator tags and replacing them or their contents with custom content. The webclass processes these indicators automatically when it responds to the WriteTemplate method in an event procedure. WriteTemplate sends the contents of an HTML template file to the browser, after any replacements are finished.

The tags processed on the server have the following format:

Together, these elements provide the webclass with the information it needs to process the tag. You insert these indicators at each location in the file where you want the system to process replacements.

For More Information   See "Sending HTML to the Browser" for more information on the WriteTemplate method and its processing. See "ProcessTag event" in the Language Reference.

Modifying a Template File to Use Replacements

In order to perform text replacements, you must first define a tag prefix for the template, in the Webclass Designer, then use an editor to insert those tags prefixes into the file wherever you want a replacement to occur. You can indicate as many replacement areas in a file as you want.

For example, suppose you have a template in your webclass called FeedbackPage. On this page, you want to perform a replacement in two areas:  you want to insert the user's name and the date on which the user's order will be shipped. You have defined the tag prefix for this webitem to be WC@.

Note   The tag prefix must begin with an alphabetical character and should contain a unique character to provide for optimal processing.

Suppose that your FeedbackPage file looks like this before you add the replacement tags:

<HTML>
<BODY>
<P>Thank you for your order. We estimate that your order will be shipped on the following date: xxx.
<P>
</BODY>
</HTML>

In order to indicate replacement areas for the name and date, you would modify the file as shown below:

<HTML>
<BODY>
<P>Thank you for your order, <WC@customer>firstlast</WC@customer>. We estimate that your order will be shipped on the following date: <WC@shipdate>shipdate</WC@shipdate>.
<P>
</BODY>
</HTML>

The following figure identifies the pieces of the replacement area in the previous code:

Replacement Indicators

Writing Code to Process a Replacement Area

You write all of the code to replace text in your file within the ProcessTag event. If you have a template file that contains several replacement areas and you need to treat them differently in your procedures, you would use a conditional statement such as If or Select Case to specify the different actions to take for each tag prefix on the page.

The order of processing for a file with tag prefixes is:

  1. Visual Basic processes user code and calls the WriteTemplate method from an event handler in the application. Typically, the event handler is for the Respond event.

  2. The webclass processes and replaces all prefixed tags in the file, according to the code you wrote for the ProcessTag event.

  3. The webclass writes the template file to the Response object.

  4. The WriteTemplate method sends the template file to the browser.

Note   The ProcessTag event cannot be fired automatically from the user's actions in the browser. It is called by the WriteTemplate method from within another event procedure.

For example, in the example in the previous section, you modified an .htm file to include two replacement areas: one called "customer" and one called "shipdate". The following event procedure could be used to process those replacements:

Sub FeedbackPage_ProcessTag(ByVal TagName as String, TagContents as _
String, SendTags as Boolean)
   'Work with previously defined variables FirstName, LastName,
   'and ShipDate
   If TagName = "wc@customer" Then
      TagContents = FirstName & "" & LastName
   EndIf
   If TagName = "wc@shipdate" Then
      TagContents = ShipDate
   EndIf
   SendTags = False
End Sub

In this code, the webclass retrieves information from several member variables that were previously set to values the user entered. These values correspond to the user's first name, last name, and a calculated date for shipment. The values from these three variables are inserted onto the page, which is then displayed to the user.

When the ProcessTag event is fired, the TagContents argument retrieves the current value of the text between the tags in the .htm file. For example, in the following line of HTML code, "customer" is the current value of the TagContents argument.

<P>Thank you for your order, <WC@customer>customer</WC@customer>.

You set new values for the TagContents in your ProcessTag event procedure. You can use the existing contents to help retrieve the new values. For example you could use a database key as your TagContents, then reference that value in your ProcessTag event procedure to retrieve a record from the database.

To perform text replacements for a webitem in your application

  1. In the Webclass Designer, click the template for which you want to define text replacements, then set the value of the TagPrefix property in the Properties window to the prefix you want to use.

    Note   The tag prefix must begin with an alphabetical character.

  2. Open the .htm file for the template in the editor of your choice, then insert replacement indicators anywhere you want to replace text, using this format:

    <tagprefix tagname>tagcontents</tagprefix tagname>

    Argument Definition
    tagprefix The tag prefix you defined in the Properties window, for this template.
    tagname A unique identifier by which you will reference this replacement area in code. For example, for a tag prefix that will be used to insert the customer's order number, you might use the tagname "orderno."
    tagcontents A placeholder for the content you will insert. This argument can also be used to provide information about what the content should be, or to hold information that will be needed when processing the replacement, such as a database key.

  3. In the Webclass Designer, right-click the template and click View Code.

  4. Write code for the ProcessTag event for the webitem, using an If or Select Case statement to work through each replacement area in the file.

Rescanning for Replacement Areas

In normal replacement processing, the webclass automatically scans the .htm file once to find all tag prefixes in the file when the webclass processes the WriteTemplate event. After finding these replacement areas, the webclass processes the tags and replaces them as indicated in code. However, your code might indicate that the webclass should insert additional tag prefixes when it replaces one of the original tags. In this situation, the webclass must search the replacement area again for these new replacement indicators and process them as well.

You can tell the webclass to search again by setting the ReScanReplacements property for the webitem. The ReScanReplacements property causes the webclass to make an additional pass through the replacement tags during the ProcessTag event. You must write code for any additional replacement areas you generate in order for the ProcessTag event to work through them.

Note   The ReScanReplacements property tells the webclass to make another search during the ProcessTag event only. You cannot use this property to scan for replacement areas during other events.

To enable the webclass to recursively check the file for new tag prefixes