Working with JavaScript, XML, XSL, and VoiceXML

While many web-based applications use client-side JavaScript to handle tasks such as validation of form input, most devices are unable to run JavaScript. To enable applications to make JavaScript-dependent content available to users, the CTE provides transparent JavaScript emulation, acting as a proxy server for the devices. The emulation is done without any intervention by the Design Studio or CTE user.

The CTE support for JavaScript provides access to JavaScript-dependent form manipulation, event processing, browser redirection, and cookie handling. This support means that a user can accomplish tasks such as the following:

Fill in and submit a form.
Receive validation regarding information entered into a form.
Reset form content.
Select a button or link to achieve the above tasks or to load a document.

The following sections describe the CTE JavaScript support:

CTE Processing of JavaScript

By default, JavaScript support is enabled for the CTE. If the sites you are transforming do not include JavaScript, you can use the CTE Administrative Interface to disable JavaScript support, as described in the "Specifying Content and Management Settings" section of the CTE Configuration Note. When JavaScript support is enabled for the CTE, each page that the CTE transforms requires additional memory even if the page does not contain JavaScript. By disabling JavaScript support when you do not need it, you improve the performance of the CTE.

Note If JavaScript support is not enabled, Design Studio renders the contents of a noscript element unless you clip it. If JavaScript support is enabled and you want to render the contents of a noscript element, ask your CTE administrator to specify the page URL in the JavaScript Exclusion List on the Advanced page of the CTE Administrative Interface.

When JavaScript support is enabled for the CTE, the CTE JavaScript engine handles a request for an HTML page as described in the following list.

1. The JavaScript engine searches for JavaScript located in these places:

script elements
Files referenced by <script src="filename"> tags
onclick, onsubmit, and other event handler attributes
<a href="javascript:method();"> tags

2. The JavaScript engine runs the JavaScript.

The JavaScript might perform actions such as modify form elements, cause the browser to retrieve another page, and submit a form to the application server.

3. The JavaScript engine caches the page.

By keeping the page in a cache, the CTE enables a user to return to the same form if a submit fails.

4. The JavaScript engine modifies the page as follows:

Wraps the entire document in a form element.
Changes regular and reset buttons to "Submit" buttons.
Changes text and images in links containing JavaScript to "Submit" buttons. For example, it converts text links such as
<a href="javascript:method();">Click here</a> to
<input type="submit">.

It converts image links such as
<a href="javascript:method();"><img src="clickme.gif"/></a> to
<input type="image">.

As a result, the link displays as a button in the transformed page and the CTE executes the associated JavaScript when a user clicks the button.
Changes the name attribute of form elements.
Changes the value attributes of check boxes and radio buttons.
Adds a "Change" button to drop-down menus with onchange events.

5. The JavaScript engine sends the page to the device.

When the user clicks a button, the JavaScript engine sets the form to the proper values, determines which events were triggered, and runs the event handler script. Depending on the result of that processing, the JavaScript engine then sends content to the device or sends a new request to the application server.

JavaScript Features Supported by the CTE

When emulating JavaScript, the CTE acts like a Netscape 4.7 client. Thus, the CTE does not support JavaScript that is specific to Internet Explorer, such as document.all or VBScript.

Table 6-1 lists the JavaScript features that the CTE supports. For unsupported features, see Table 6-2.

Table 6-1 Supported JavaScript Features

Feature Type	CTE Processing
Form manipulation	Transforms JavaScript related to form manipulation so that users can enter values into input fields and submit input. The CTE supports input from the following: Buttons: regular, image, submit, and reset Text boxes: regular, text areas, password, and hidden Drop-down menus and Select objects Checkboxes and radio buttons Form objects do not have to be enclosed in a form element. Handles the processing required before submitting the input fields. Adds a "Change" button beside a drop-down menu. A user must select the "Change" button after making a menu selection. Requires that a user submit or verify a form by selecting a button.
Dynamic HTML	Allows dynamic writing of content to a browser window (document.write). Supports menus (Select objects) that are dynamically populated with options.
Browser redirection	Allows script-based retrieving of new pages. Redirects from HTTP to HTTPS are not secure in Design Studio.
Cookie handling	Allows script-based reading and writing of cookies.
Event processing	Handles the processing required to determine the next event in response to a user action such as the following: Selecting a button or link Submitting or resetting a form Selecting from a drop-down menu Loading a document Transforms HTML elements that trigger a JavaScript event into a "Submit" button. Elements that might be transformed include the following: reset buttons, regular buttons, links with onclick events, and links with href attributes that contain JavaScript code. The CTE also adds "Change" buttons.
Other	Maintains Back button history. Supports included external script files.

Guidelines for Design Studio Users

The CTE handles all of the transformations that are required to support JavaScript-based forms. Whether or not you enable JavaScript support, the CTE transforms an HTML element that triggers a JavaScript event into a button labeled "Change" or "Submit." As a result, you will see more buttons in the Design Studio browser view of transformed pages. For example, Figure 6-1 shows an original application that uses JavaScript.

Figure 6-1 Original Application

The CTE transforms the application as shown in Figure 6-2. In the browser view, notice the additional "Change" buttons; in the XHTML source view, notice the XHTML code that has replaced JavaScript.

Figure 6-2 Transformed Application

Design Studio users do not need to apply any rules in order for JavaScript to operate correctly on devices. However, you can apply transformation rules to a page that contains JavaScript in order to perform the following:

Clip unneeded elements in a form. For example, you might clip a button.

Note Clipping, ignoring, or not including a checkbox, radio button, or Select object makes those objects appear unselected to an application server. If you need to make them appear selected to the application server, but do not want them to be visible on the transformed page, do not clip them. Instead, modify the object so that its type attribute is set to "hidden".

Add a Submit button to a form.

If a form does not have a Submit button, insert the following tag:

 
<input type="submit" name="fformnumberzs">

where formnumber is the same number that appears for other elements in that same form in the XHTML. For example, if the XHTML shows form number "1" for other elements, insert the following tag:

 
<input type="submit" name="f1zs">

Modify the label of a button from "Change" or "Submit."
Move a button or other elements in a form.
Reduce the number of choices in a Select object or drop-down menu.

Consider, for example, if a list of 50 items is practical to send to a microbrowser screen. If possible, eliminate some of the choices.

Change a text box to a drop-down menu to improve usability.
If a page contains JavaScript that opens a pop-up window, you can replace the unsupported pop-up window with a link. For more information, see the "Replacing a Pop-Up Window with a Link" section.

Note When working in Design Studio on a page that contains JavaScript, note that the operation of JavaScript is state dependent and Design Studio might not return the correct state when you navigate to the Browse tab. In this case, Design Studio prompts you to click the

(reload) button to retrieve the page from the CTE cache.

If you need to apply transformation rules to JavaScript-based forms, follow these guidelines to ensure that the CTE can correctly transform and process the JavaScript:

Do not change the name attribute of the elements in a form. The CTE assigns and uses name attributes to track elements.
Do not change the value attribute of check boxes and radio buttons. The CTE assigns and uses value attributes to track the state of check boxes and radio buttons.

Replacing a Pop-Up Window with a Link

To replace a pop-up window with a link, perform these steps:

Step 1 View the source HTML in Netscape or Internet Explorer.

Step 2 Search for "window.open" and copy the referenced URL.

Note If window.open calls a function, search for the function and copy the URL referenced in its associated a element.

Step 3 Use Design Studio to insert a link, using the URL you copied.

JavaScript Features Not Supported by the CTE

Table 6-2 lists the JavaScript features that the CTE currently does not support.

Table 6-2 Unsupported JavaScript Features

Feature Type	Unsupported Actions
Dynamic HTML	Dynamically manipulate cascading style sheets (document.tag, classes, IDs). Dynamically manipulate layers (document.layer). Show or hide page elements. Use of events that change images during a mouse rollover; checkbox and radio button click events. Use of onBlur and onFocus events. Collapse sidebars.
Frame and window manipulation	Manipulate values and objects in multiple browser frames or other windows. Open and close new windows. Retrieve new content for a given window.
Form manipulation	Upload files through input fields. Use of different cases in form variables (because form.named_input is case-sensitive).
Other	Use of JavaScript that is specific to Internet Explorer, such as document.all and VBScript. When the CTE encounters unsupported syntax, it ceases to run the current script. Subsequent scripts will run. Processing of JavaScript frames. Use of JavaScript URLs that are outside of a elements (links). Use of a history object to move through browser history. Display alerts, prompts, and confirmations. If a user enters invalid information into a field, the CTE does not submit the form. Instead, the CTE clears the invalid field. The user can then reenter the field and submit the form. For prompts and confirmations, the CTE returns "true" unless the script explicitly returns "false" (in which case the event stops running).

Manually Configuring the XPath Expression of an Element

Note This feature is intended only for users familiar with XSL.

You can manually configure an element by editing its XPath expression. This feature provides more flexibility in node selection when applying a rule.You can modify an XPath expression to address one or several nodes.

Table 6-3 contains the XPath expression to use to achieve various results.

Table 6-3 XPath Expression Examples

Intended Selection	XPath Expression
All elements that are not tables (use, for example, to delete everything but the tables)	*[not(self::table)]
Last row (tr element) in a table	tr[position() = last()]
All rows except the last row of a table	tr[position()>=1 and position()<=last()-1]
Every other tr element after the third row	tr[position()> 3 and position() mod 2 = 0]
The third row that has the class attribute	tr[@class][position()=3] tr[@class][3]
The third row that has the class attribute set to specialrow	tr[@class='specialrow'][position()=3] tr[@class='specialrow'][3]
The third row only if it has the class attribute set to specialrow	tr[position()=3][@class='specialrow'] tr[3][@class='specialrow']
The rows that do not have the class attribute	tr[not(@class)]
The first text element only if it equals "Howdy"¹	text()[1][self::text()='Howdy']
The first "Howdy" text element	text()[self::text()='Howdy'][1]
The first text element only if it equals the contents of the text field in the dialog box	text()[1][self::text()=$a4868257202001]

1If the text you want to configure contains special characters, particularly single or double quotation marks, be sure to enter the text in the text field and click Reload to retrieve the XPath expression provided by Design Studio. You must include any text variables provided by Design Studio in your XPath expression.

For more information about XPath pattern matching, see http://www.w3.org/TR/xpath.

To manually configure an XPath expression, perform these steps:

Step 1 In the Configure Rule dialog box, set the depth and position options.

Step 2 Click Manually Configure Element to select it.

Step 3 Click Reload to view the current XPath expression for the node.

Step 4 Edit the XPath configuration in the text box.

Design Studio alerts you if you enter invalid syntax for the XPath.

Step 5 Click OK.

Working with XML Projects

If you have a set of XML pages that you want to make available to users, you work with the XML pages in a Design Studio XML project. For XML projects, you import into Design Studio an XSL style sheet that you created in another application. Design Studio uses the imported XSL style sheet to transform the XML pages.

Note If you need to use more than one XSL style sheet to handle different device protocols, use the Import XSL rule as described in the "Using Several XSL Style Sheets for a Project" section.

The following sections describe how to use Design Studio to work with XML projects:

Creating an XML Project

An XML project contains an XSL style sheet and the XML pages that you want to transform. You create an XSL style sheet outside of Design Studio. Be sure to validate an XSL style sheet before importing it. Design Studio does not validate imported style sheets.

Note Before you import an XSL style sheet, verify that all xsl:template elements in the style sheet have a priority attribute set to greater than 1. This ensures that your style sheet will not conflict with the style sheet generated by Design Studio.

To create an XML project, perform these steps:

Step 1 Verify that the correct configuration file is open.

The name of the current configuration file appears in the title bar of the Design Studio window.

Step 2 From the Projects menu, choose Create Project.

The Create Project dialog box appears.

Step 3 Enter a name to identify the project, for example, "command pages."

Step 4 Click the XML radio button.

Step 5 Click OK.

The Select Location of Style Sheet dialog box appears.

Step 6 Enter the fully-qualified URL of an XSL style sheet, or click Browse, navigate to a filename, and click Open.

Step 7 Click OK.

Design Studio creates the project, imports the style sheet, and adds the Style Sheet tab to the window.

Step 8 To view the style sheet, click the Style Sheet tab.

After you create a project, you add web pages to it as described in the "Adding a Page to an XML Project" section.

Adding a Page to an XML Project

To add a page to an XML project, perform these steps:

Step 1 In the project tree, click a project.

Step 2 Enter the XML page URL in the Address field.

Design Studio opens the requested page in the Browse tab. The XML is formatted according to the XSL style sheet that you imported in this project.

If the requested page does not appear, the CTE server or the server for the web page may not be running.

If the page information pane (lower-left portion of window) includes the message "Passes Identifier Rules," see the "Using an Identifier Rule for Multiple Pages" section.

If a Redirection message displays, see the "Handling Page Redirects" section.

Step 3 In the lower-left pane, click Add Page to Project.

Design Studio adds the XML page to the project and displays it in the View Original tab, formatted according to the imported XSL style sheet.

Step 4 Create identifier rules for the pages as described in the "Identifying a Page" section.

Step 5 Save and publish XML projects just like HTML projects.

Updating an XSL Style Sheet

After you change and validate an XSL style sheet in another application, update it in Design Studio.

To update an XSL style sheet, perform these steps:

Step 1 Right-click the XML project in the project tree.

Step 2 Choose Update Style Sheet from the shortcut menu.

Importing Custom XSL

In addition to using the rich set of transformation rules provided with Design Studio, you can also apply a custom rule to an element or a custom XSL template to a page. This advanced feature enables you to supplement or replace the default XSL template in the XSLT style sheet created by Design Studio.

When you apply a rule such as Select or Move, Design Studio writes an xsl:template element for the rule. You can choose, instead, to create your own rule by modifying or replacing an xsl:template element. The default XSL template provided by Design Studio is associated with a particular node or set of nodes. If you override the default, the XPath pattern in the xsl:template match= statement determines on which nodes the rule is applied.

Importing a custom XSL template rule is useful in cases such as the following:

To perform advanced string manipulation on text or on element attributes.

For example, you might need to reorder something in a URL or you might need to remove part of the beginning and the end of a URL.

To modify dynamically generated content.
To use several custom XSL style sheets for XML pages.
To perform an XSL operation on the page URL. When Design Studio generates a style sheet, it adds a global variable ($url) that contains the page URL. You can use this variable in imported style sheets or in XPath expressions. The following example adds a link to the top of the page:

 
<xsl:element name="a">

 
<xsl:attribute name="href"><xsl:value-of select="$url"/> </xsl:attribute>Go To Top

 
</xsl:element>

The following sections describe how to import custom XSL:

Importing a Custom XSL Template Rule on a Node

To import a custom XSL template rule on a node, perform these steps:

Step 1 In the project tree, select a device type.

Step 2 In the XHTML source view, right-click the node where you want to apply a custom XSL template rule.

Step 3 Choose Import XSL from the shortcut menu.

The Configure: XSL Import Rule dialog box appears.

Step 4 (Optional) Change the rule name, perhaps using a brief description of its content, such as "Custom rule: manipulate URL."

Step 5 Choose whether to apply the rule to all pages in this project or just this page:

Click the Project radio button to apply the style sheet to all pages in this project.
Click the This Page radio button to apply the style sheet only to this page.

Step 6 Choose each device type to which you want to apply the rule.

Step 7 Click the Import XSL tab.

The Import XSL tab appears.

Step 8 To change the XSL template for just this node, leave the Use Default <xsl:template> check box selected.

If you clear the check box, the XSL template that you enter replaces the entire default style sheet for the page.

Step 9 Type the XSL statements for the rule you are creating.

Step 10 Click OK.

Design Studio validates the XSL and displays an error message if the XSL is not well formed or includes unsupported elements such as xsl:keys and xsl:call-template.

Example: Using Custom XSL to Change a Button to Text

By importing custom XSL, you can create your own rules in Design Studio. The following example contains the custom XSL needed to change a button to text.

To create a custom XSL rule that changes a button to text, perform these steps:

Step 1 In the page that contains the button that you want to change, locate the input element for that button.

Step 2 Right-click the input element and choose Import XSL from the shortcut menu.

Step 3 In the Configure: Import XSL Rule dialog box, click the Import XSL tab.

Step 4 Type the following in the text box:

 
<xsl:value-of select="@value"/> 

Leave the Use Default check box selected.

Step 5 Click OK.

Example: Using Custom XSL to Change a URL

This example contains a custom XSL rule that changes a URL by replacing a filename with a path and different filename. The a element that is changed in this example is as follows:

 
<a href="http://192.168.1.1:8080/wrong_page.html?session=12345"

The a element is changed to the following:

 
<a href="http://192.168.1.1:8080/dir/path/new_page.html?session=12345"

To create a custom XSL rule that changes a URL, perform these steps:

Step 1 In the page that contains the URL that you want to fix, locate the a href element for that URL.

Step 2 Right-click the a element and choose Import XSL from the shortcut menu.

Step 3 In the Configure: Import XSL Rule dialog box, click the Import XSL tab.

Step 4 Type the following in the text box:

 
<xsl:copy>

 
    <xsl:attribute name="href">

 
        <xsl:value-of select="concat('/dir/path/new_page.html?', substring-after(@href, '?'))"/>

 
    </xsl:attribute>

 
</xsl:copy>

Note The above XSL is specific to this example.

Leave the Use Default check box selected.

Step 5 Click OK.

Using Several XSL Style Sheets for a Project

To make a set of XML pages available to users, you import into Design Studio one or more XSL style sheets that you created in another application. Design Studio and the CTE use an imported XSL style sheet to transform the XML pages.

If your XML pages have only one XSL style sheet, you can create an XML project, as described in the "Working with JavaScript, XML, XSL, and VoiceXML" section. If your XML pages have several XSL style sheets to support different device protocols, you create an HTML project and import a style sheet for each protocol by replacing the default <xsl:template> element.

To use several XSL style sheets with one project, perform these steps:

Step 1 In the project tree, select a device type that corresponds to a style sheet you want to import.

Step 2 Right-click in the XHTML source view or the browser view.

Step 3 Choose Import XSL from the shortcut menu.

The Configure: XSL Import Rule dialog box appears.

Step 4 (Optional) Change the rule name, perhaps using a brief description of its content, such as "Custom rule: manipulate URL."

Step 5 Choose whether to apply the rule to all pages in this project or just this page:

Click the Project radio button to apply the style sheet to all pages in this project.
Click the This Page radio button to apply the style sheet only to this page.

Step 6 Click the Import XSL tab.

The Import XSL tab appears.

Step 7 Clear the Use Default <xsl:template> check box.

Step 8 Open the XSL style sheet in a text editor such as Notepad.

Step 9 Copy all xsl:template elements in the style sheet.

Step 10 Paste the copied text into the XSL Import Rule dialog box.

Step 11 Click OK.

Design Studio validates the XSL and displays an error message if the XSL is not well formed or includes unsupported elements such as xsl:keys and xsl:call-template.

Step 12 Apply transformation rules as needed.

Step 13 Repeat Steps 1 through 12 for another device protocol.

Note In the XSL Import Rule dialog box, be sure to clear the check box for the previously configured device type.

Previewing VoiceXML Support

Design Studio contains a preview of VoiceXML support (available only for some licensed products). This preview enables you to create a transformation for one static web page that a caller can then access by phone through the BeVocal or Tellme VoiceXML service providers. When a caller dials the number that you set up with a VoiceXML service provider, the service provider sends a request for the page through the CTE. The CTE transforms the page to VoiceXML and delivers the page to the service provider, which then reads the page to the caller, as shown in Figure 6-3.

Figure 6-3 Processing a VoiceXML Request

To set up a VoiceXML transformation, perform these steps:

Step 1 Contact BeVocal or Tellme to set up an account and a portal for the web page.

The service provider will ask you to specify a username, password, IP address, and port number. The service provider will give you a phone number for your VoiceXML portal.

Step 2 Create a project in Design Studio and add the web page that you want to transform to VoiceXML.

Note The page must be available on the Internet. VoiceXML service providers cannot access Intranet content.

Step 3 Specify a page identifier for the page.

Step 4 In the project tree, select VoXML.

Step 5 Use Design Studio transformation rules to select the content callers should hear when they request the page from BeVocal or Tellme.

The content that you select must contain static content; dynamic content is currently not supported. You can include links, but a caller will not be able to select and follow links in this preview release of VoiceXML.

Step 6 Save the configuration file and publish it to the CTE.

Step 7 Dial the phone number for the VoiceXML portal to hear the transformed content.

Table of Contents