This chapter covers the following topics:
The Script Author provides three ways to customize panel layouts for graphical scripts:
Using the panel layout editor. This is an integrated component which provides script developers with a convenient method for creating and editing simple formatted panel content without writing HTML code.
Using third-party HTML generation and editing tools. For complex or feature-rich panel layouts, HTML content can be created externally and imported into a script. Using Oracle Scripting-specific HTML tags, the entire panel content, including all answer definitions and answer user interface controls, can be generated in custom HTML and imported into the script.
Using the panel layout editor in combination with custom HTML editing tools. If desired, answers can be defined from the Answer Entry Dialog window, and content can be created in the panel layout editor, and then exported as HTML, enhanced externally, and imported back into the script. Any previous answer definitions and all panel content and formatting is replaced by the imported panel content.
Knowledge of custom Oracle Scripting HTML syntax for is required.
The Script Author includes a panel layout editor, which provides script developers with a convenient method for creating and editing simple panel content without writing HTML code. This simple graphic interface provides users with the ability to enter and format simple panel content, and manipulate typeface, font size and color, create bulleted and ordered lists, and more. In addition, it serves as the way to produce syntactically correct HTML content for Scripting-specific features (such as embedded values) without having to learn custom Oracle Scripting HTML tags and syntax. Answers and text can be interspersed and formatted as desired. The panel layout editor includes one-click formatting of text into two distinct styles, instructional text and spoken text. This provides script developers a consistent, rapid method to format text differently in the panel layout editor to indicate text an agent would speak (or a customer would read) that relates directly to the matter at hand, and to format text providing the script end user with specific instructions.
Nonetheless, for creating any complex layout, and using features of HTML such as tables, it is expected that script developers will use full-function third-party HTML editors (or code HTML by hand) and simply import the HTML content into the Script Author.
This combination ultimately delivers a solution that combines ease of use for simpler implementations with a high level of flexibility for implementations that have unusual or complex requirements. To support this model, this section includes Scripting-specific HTML tags and syntax.
All panel content, whether created in the panel layout editor or externally, renders as Hypertext Markup Language (HTML) in the Scripting Engine runtime interface. Each interface is subject to its own set of restrictions, as well as restrictions that apply to both interfaces.
All panel content, whether created in the panel layout editor or externally, renders as Hypertext Markup Language (HTML) in the Scripting Engine runtime interface. Each interface is subject to its own set of restrictions, as well as restrictions that apply to both interfaces.
When developing scripts to execute in the Scripting Engine Web interface, you should be aware of the following restrictions, described in detail below:
HTML interpretation differs by browser
JavaScript and JScript Support
Agent UI components not included in Web interface
In the Web interface, script HTML (executed as a survey questionnaire) is interpreted by the HTML engines afforded by the particular Web browser used. Thus, survey questionnaires may appear differently when rendered in Microsoft Internet Explorer than they do in Netscape Navigator. Differences may also appear between various releases of the same browser software.
JavaScript is a scripting language intended to execute within any JavaScript-compliant Web browser. All current Web browsers certified for use with Oracle Applications release 11i are JavaScript-compliant.
Note: Microsoft Corporation has created a competing technology to JavaScript known as JScript. Due to browser-specific differences in internal script interpretation, scripts that execute perfectly in one Web browser may not function the same way in a different Web browser (including a different version of the same browser software). JavaScript and JScript developers must be certified in the appropriate relevant technologies and should take browser incompatibilities into account. Further, if scripts are intended for execution in the Web interface, developers must take care to ensure any JavaScripts or JScripts used will support both Netscape Navigator and Microsoft Internet Explorer.
For the purposes of this document, scripts created in JavaScript or JScript are referred to as JavaScripts.
Despite the name, JavaScript and the Java programming language are separate and distinct. JavaScripts can be included in custom panel text for a panel object in the Script Author, if that script will be executed in a Web browser.
Caution: JavaScript is not supported for scripts executed in the agent interface and should not be used.
There are two approaches to including JavaScripts into panel HTML.
Create a complete and syntactically correct panel in the Script Author, and then export the panel HTML. Edit the HTML to include the JavaScript as appropriate.
Identify all requirements for the panel which requires JavaScript, and using a compliant HTML editor or text editor, write the HTML and JavaScript code for the panel. Then, from the Script Author, import the code into the appropriate panel.
For more information, see Exporting Panel Text, Adding JavaScript, and Importing.
When scripts execute in the agent interface, the panels appear in a large work area. Above the panels, if programmed into the script’s global properties, the script information area appears, and below this (if defined), shortcut buttons are included. A progress panel shows the active script’s history to the right of the agent work area. All of these components are surrounded by a frame. At the bottom, right-hand side of the frame, a Disconnect button appears.
For scripts executed in the Web interface, only panels are rendered in the browser. Regardless of whether a script includes defined shortcuts, or timers or text programmed to appear in the script information area, these will not appear in scripts executing in a browser, and will not be accessible at runtime. The progress area will also not appear; to back up in a script executed in the Web interface, use the browser’s Back button. Finally, the frame enclosing the script in the Web interface is the actual Web browser window. Thus, there is also no Disconnect button. The only way a wrap-up group can be accessed is by proceeding through the appropriate flow or flows in the script.
Generally, scripts created for one runtime interface will execute in the other. Nonetheless, the differences noted above must be considered to ensure appropriate flow in scripts executed in the Web interface. Scripts that meet an enterprise’s requirements in the agent interface will also be lacking script information area headers, shortcut buttons, the progress area and the disconnect button, and may therefore not meet the same set of requirements when executed in the Web interface. This fact should be noted by sales, support, technical and functional consultants, and those interaction center staff members responsible for ensuring project requirements are fulfilled.
Swing and HTML Incompatibilities
In the Java-based agent interface, script HTML interpretation and rendering is provided by the Swing Java classes compatible with JavaSoft's Java Development Kit (JDK) 1.1.8.
While this entire area of Swing has been rewritten and is much improved in JDK 1.3, Scripting is unable to upgrade its version of Swing until all Oracle Applications upgrades to JDK 1.3 as well. Consequently, scripts executed in the agent interface inherit the HTML incompatibilities created by using the older version of swing. The following are known issues with this version of Swing for HTML rendering:
Horizontal alignment of containers. While Swing does support alignment of individual elements, it cannot handle alignment of tables and logical containers (as specified by the <div>...</div> tag).
Table width attribute. The "width=<pixel value or percentage>" attribute of the <table>...</table> tag is ignored by Swing.
Avoid use of the <br> (break) tag. Swing has known issues with HTML that uses the <br> tag. One option is to use paragraph tags instead. For example, use:
<p> </p>
Use well-formed HTML only. Swing is known to have problems with HTML that is not well-formed; that is, all start tags should have corresponding end tags (e.g. <p> should always have a corresponding </p>).
HTML 3.2 Compatibility
The HTML specification used for this version is HTML 3.2. Tags from later HTML specifications, including HTML 4.0, may not appear as expected when executed in the agent interface. Consequently, rigorous testing should be performed for all custom scripts including custom HTML code.
JavaScript and JScript
JavaScript and JScript are not supported for scripts executed in the agent interface and should not be used.
When defining an answer in the Script Author, the following answer user interface types are supported: Text fields, text areas, radio buttons, check boxes, buttons, drop-down lists, password fields, check box groups and multi-select list boxes. Each of these answer UI control types has its own corresponding properties (discussed in detail in the Understanding Answers section of Oracle Scripting User Guide). Additionally, several of these answer UI control types have unique HTML tags, attributes, and syntax. Custom syntax for these answer UI types are summarized in the table below.
| Answer UI Type | HTML Tag Set | Control Definition Syntax |
|---|---|---|
| radio button | <rbgroup>...</rbgroup> | <input name="answer definition name" type="radio"> |
| check box group | <cbgroup>...</cbgroup> | <input name="answer definition name" type="checkbox"> |
| button group | <pbgroup>...</pbgroup> | <input value="pbLabel" name="answer definition name" type="submit"> |
Individuals editing or creating panel text external to the script author must be familiar with and follow the appropriate syntax for any panel in order for custom HTML to function within a script. Additionally, when editing or creating radio buttons, buttons, or checkbox groups, answer UI-specific custom syntax must be included.
In panel HTML created by the panel layout editor, an HTML table is automatically generated in the body of the HTML document. This table starts just above the first node (also known as a question or an answer definition).
In the HTML tags defining the table, the table has a name property, which must contain the value "IES_ControlManifest". The tag, when generated by the panel layout editor, appears as follows:
For answer UI types that take lookup values, the number of buttons to be displayed and their labels are determined at runtime. Thus, despite the introduction of the What-You-See-Is-What-You-Get (WYSIWYG) paradigm, there is no way to have a WYSIWYG display of button, radio button, drop-down or multi-selection list, or checkbox group controls in the panel layout editor. When these answer UI types are viewed in the panel layout editor, a single control of the appropriate type is displayed, with no values. Instead of the lookup value, generic labels appear next to the appropriate control: rbLabel for radio buttons, cbLabel for check box groups, pbLabel for buttons. Labels (as populated in the Label for reporting field of the Answer Entry Dialog window) will render in the panel layout editor as well as at runtime.
In the panel HTML, a single set of custom tags defines the answer control. There is specific syntax associated with the button, radio button, and checkbox group answer UI controls. This syntax, which is built automatically with the panel layout editor, must be maintained in order for the panel to function at runtime.
Using the appropriate stands, answer UI controls can also be defined externally using a text editor or HTML generation and editing tool.
Note: Code samples for HTML may exclude spaces or special characters. For example, the ASCII symbol for a space (  ) appears in panel layout editor-generated HTML but is generally excluded in this document.
This section describes syntax for the custom Oracle Scripting radio button group HTML tag set:
<rbgroup> ... </rbgroup>
Within the open and close radio button group tag set, there are two required tags, which can appear in any order, and can be surrounded by any valid HTML content.
One required tag is the radio button definition:
<input name="answer definition name" type="radio">
The name attribute includes the answer definition name, surrounded by quotes. This attribute associates the HTML control with its panel node or answer definition.
The other required tag is the radio button label definition tag set. The tags include:
<rblabel>rbLabel</rblabel>
Since the actual labels of the individual radio buttons will be determined at runtime, this tag set, including the single rbLabel, appears once in panel HTML (when reviewed before runtime), regardless of how many lookups you define. This serves as a placeholder into which the Scripting Engine at runtime will dynamically insert code for each defined lookup, one per radio button value. For example, consider a radio button group with three lookup values defined, one for each available flavor of an ice cream sundae. Each lookup value includes a display value and the actual value passed by the application (in this example, chocolate/c, vanilla/v and strawberry/s).
The panel HTML for this example appears as follows:
<rbgroup> <input name="flavors" type="radio"> <rblabel>LookupValue1</rblabel> </rbgroup>
At runtime, all custom tags above, starting with the rbgroup tag set, are replaced dynamically. For each lookup value, an instance of the input tag is generated, coded with the value of that lookup. Thus, continuing the above example, the HTML code that actually displays might appear as follows:
<p><input name="flavors" type="radio" value="c"><b>chocolate</b></p>
<p><input name="flavors" type="radio" value="v"><b>vanilla</b></p>
<p><input name="flavors" type="radio" value="s"><b>strawberry</b></p>
This section describes syntax for the custom Oracle Scripting checkbox group HTML tag set:
<cbgroup> ... </cbgroup>
Within the open and close checkbox group tag set, there are two required tags, which can appear in any order, and can be surrounded by any valid HTML content.
One required tag is the checkbox group definition:
<input name="answer definition name" type="checkbox">
The name attribute includes the answer definition name, surrounded by quotes. This attribute associates the HTML control with its panel node or answer definition.
The other required tag is the checkbox label definition tag set. The tags include:
<cblabel>cbLabel</cblabel>
Since the actual labels of the individual checkboxes in this checkbox group will be determined at runtime, this tag set, including the single cbLabel, appears once in panel HTML (when viewed before runtime) regardless of how many lookups you define. This serves as a placeholder into which the Scripting Engine at runtime will dynamically insert code for each defined lookup, one per checkbox value. For example, consider a checkbox group with three lookup values defined, one for each topping on an ice cream sundae. Each lookup value includes a display value and the actual value passed by the application (in this example, sprinkles/s, chocolate syrup/cs, and chopped nuts/cn).
The panel HTML for this example appears as follows:
<cbgroup> <input name="topics" type="checkbox"> <cblabel>LookupValue1</cblabel> </cbgroup>
At runtime, all custom tags above, starting with the cbgroup tag set, are replaced dynamically. For each lookup value, an instance of the input tag is generated, coded with the value of that lookup. Thus, continuing the above example, the HTML code that actually displays might appear as follows:
<p><input name="topics" type="checkbox" value="s"><b>sprinkles</b></p>
<p><input name="topics" type="checkbox" value="cs"><b>chocolate syrup</b></p>
<p><input name="topics" type="checkbox" value="cn"><b>chopped nuts</b></p>
This section describes syntax for the custom Oracle Scripting button group HTML tag set:
<pbgroup> ... </pbgroup>
The button answer UI type can only be used when it is the single answer control defined for a panel. The most typical use of the button answer UI type is to provide a single value (such as "Continue") to advance the flow of the script. This answer UI type also supports multiple lookup values for the single answer definition (thus the designation of this tag set as a group). The result at runtime is that, for each lookup defined, the display value appears as the text label of a button at the bottom of the active panel. In panel layout editor-generated HTML, the series of buttons appear horizontally, left-aligned, in succession. If necessary, second or subsequent rows of buttons are right-justified.
Within the open and close button group tag set, there is a single required tag, the button definition, which can be surrounded by any valid HTML content:
<input value="pbLabel" name="answer definition name" type="submit">
The value attribute identifies this HTML string as a button. Unlike the other custom Oracle Scripting tags, there is no separate label tag.
The name attribute includes the answer definition name. This attribute associates the HTML control with its panel node or answer definition.
The type attribute identifies this control as a submit button.
The label tag is not supported for the button answer UI type. Therefore, any value entered into the answer definition in the Label for reporting field is ignored.
For example, consider a button group with three lookup values defined, one for each container type for an ice cream sundae. Each lookup value includes a display value and the actual value passed by the application (in this example, small cup/sc, large cup/lc and banana split/bs). However, only the display value for each button (derived at runtime from lookup values defined) is included in the button’s HTML content at runtime. Therefore, display values for multiple lookup choices for any one button answer definition must be unique.
The panel HTML for this example appears as follows:
<pbgroup> <input value="pbLabel" name="containers" type="submit"> </pbgroup>
At runtime, all custom tags above, starting with the rbgroup tag set, are replaced dynamically. For each lookup value, an instance of the input tag is generated, coded with the value of that lookup. Thus, continuing the above example, the HTML code that actually displays might appear as follows:
<p><input value="small cup" name="containers" type="submit">  </p>
<p><input value="large cup" name="containers" type="submit">  </p>
<p><input value="banana split" name="containers" type="submit">  </p>
For panels containing answer UI types other than button, HTML code is required at the bottom of the panel to display a submit button at runtime. The function of this button is to progress the flow of the script from the current panel to the next object in the flow (dynamically determined at runtime). This is referred to as the Continue button.
Panels containing the button answer UI type use that control to progress the flow of the script. As described in Section 6.3.2.3, "Button Answer UI Panel Syntax", that answer control has its own distinct syntax requirements and rules.
When using the panel layout editor, HTML code is automatically generated for the Continue button. If you are building panel content external to the Script Author, this tag is required of all panels not containing the button answer UI type.
The attributes for this required tag can appear in any order, and can be surrounded by any valid HTML content. The syntax for this control is:
<input value="Continue" name="IES_CONTINUE" type="submit">
The value attribute is automatically provided by the panel layout editor, and is recommended for consistency. The contents of this attribute control the button label at runtime. This attribute alone may be modified for this required tag.
Unlike the custom button answer UI type, the Continue button tag supports only a single button.
When embedded values are added to a panel layout, the Script Author stores values toward the end of the HTML panel text in an embedded value string.
At the time of this writing, these values are stored after the close HTML tag. In order to fix incompatibilities with some HTML editors, the location in panel HTML where this string is stored will likely change in the future. Nonetheless, the presence of the iesembeddedvalue string, and its attributes, are required in order for the commands contained in embedded values to function.
The structure for the embedded value string is as follows:
<!--iesembeddedvalue iesuid="[unique string]" iescommandtype="[embedded value command type]" iescommand="[command name]" iescommanditerate="[true or false]"-->
The iesuid value is a unique identifier string.
The iescommandtype value identifies the command type (e.g., "blackboard" for a blackboard command).
The iescommand value is the name of the Script Author command.
The iescommanditerate value is a literal string of true or false, indicating whether the parameter must iterate.
This section describes how to customize the content in a panel.
Of the nine supported answer user interface control types, four do not require lookup values to be entered. These include the three text entry UI types (text field, text area, and password field), and the single checkbox. Text entry answer UI types take keyboard inputs or null values at runtime. The single checkbox control, which takes a click or null value, displays its checkbox label from the Label for reporting field.
All other answer UI types require lookups. These can be explicitly specified (hard-coded) lookup values, or table, cursor, or command lookups.
For all answer UI types except button, a "Continue" submit button will automatically be generated at the bottom of the panel, regardless of whether the panel contains a single answer definition or many.
For the button answer UI type, you must define a lookup value.
Caution: Although the Script Author application does not prohibit you from leaving the value and display value fields empty for a button (resulting in a narrow button with no label at runtime), this course of action is not recommended by Oracle and is not supported.
All panel content, regardless of whether it is generated from the Script Author only, from custom HTML only, or a combination, requires at minimum:
One or more answer definitions.
The default for distinct branching attribute selected for one answer definition, unless the panel contains a multiple-answer UI type such as checkbox group or multi-select list box.
HTML code for a submit button, which allows the script to continue to the next object in the flow at runtime.
Answer Definitions
Each panel in a script requires one or more answers to be defined.
If the answer user interface type is a button, there can only be a single answer for that panel.
Default for Distinct Branching
The default for distinct branching attribute must be selected for one answer definition per panel.
The only exception to this rule is a panel containing an answer definition of UI type check box group or multi-select list box. Only one answer can direct the flow of the script, whereas these answer UI types support multiple potential answers to the same question/answer definition. Thus, panels containing one or more of these answer UI types are absolved from this requirement.
Regardless of whether a distinct branch is used, each panel requires at least one answer definition to be set as the trigger for distinct branching. This trigger is set by checking the Default for distinct branching option in an answer definition’s Answer Entry Dialog window.
The Default for distinct branching option must be selected for panels with a button answer UI.
If you have a panel with only one answer defined, it must be set as the trigger for distinct branching (unless it is a check box group or multi-select list box).
Regardless of how many answers you define in a panel, only one can be set as the default to trigger distinct branching. Thus, the last answer definition or node for which this attribute was selected is the default for the panel.
Submit Button Code
An HTML submit button on every panel allows the script to continue to the next object in the flow at runtime. This is either:
An explicitly programmed button answer definition following the custom Oracle Scripting button syntax, or
A Continue button, generated automatically by the panel layout editor or explicitly in custom panel HTML, following the custom Oracle Scripting Continue button syntax.
You can write syntactically correct HTML for a panel outside of Scripting and import the code into a script using the Script Author. With the introduction of WYSIWYG panel editing as of release 11.5.6 and later, you can now create the entire contents of the panel HTML, including answers, in custom-generated HTML. Previously, answers were required to be created in the Script Author.
Before using an HTML editor or a text editor to create the panel HTML, you must ensure you have all the required information to code. You will need:
Panel content, including:
Panel text (spoken and instructional text), including any formatting requirements.
Hypertext links.
Images, in Graphics Format Interchange (GIF) or Joint Photographic Experts Group (JPEG) format.
Answer properties, including:
The boolean value for default for distinct branching.
The answer definition name (sometimes referred to as the question name).
The answer UI type. The range includes text fields, text areas, radio buttons, check boxes, buttons, drop-down lists, password fields, check box groups and multi-select list boxes.
Data dictionary properties.
Java Bean properties are no longer supported for answers in a panel. No information should be provided in the Answer Entry Dialog window in this section. You can still replace an entire panel with a Java bean.
Data dictionary properties. Data dictionary properties may be defined for each answer definition. Possible data dictionary properties include:
Validation commands, to validate the answer provided at runtime.
Default commands, to provide a constant value for an answer.
Data sources, linking to tables to obtain answers from a database table.
Table information, to connect to database tables
Lookup reference information, to provide table, cursor, or command lookups, or to specify hard-coded lookup values as choices for each answer.
If creating a script for subsequent HTML modifications, you may want to use the Script Wizard to first generate a syntactically correct script, and then convert it to a graphical script, from which you can import custom HTML.
Data dictionary properties may be defined for each answer definition. A separate data dictionary is maintained for each answer definition in a panel. Possible data dictionary properties include:
Validation commands, to validate the answer provided at runtime.
Default commands, to provide a constant value for an answer.
Data sources, linking to tables to obtain answers from a database table.
Table information, to connect to database tables
Lookup reference information, to provide table, cursor, or command lookups, or to specify hard-coded lookup values as choices for each answer.
Some answer UI types require data dictionary properties to be defined. For example, buttons, radio buttons, drop-down lists, multi-select list boxes and checkbox groups require, at minimum, lookups to be defined.
Note: Be aware that the standard checkbox answer UI type (as opposed to the checkbox group) obtains its contents not from a lookup value in the data dictionary, but rather from the Label for reporting field in the Answer Entry Dialog window.
Text entry answer UI types (text fields, text areas and password fields) do not require any data dictionary properties to be specified. Nonetheless, data dictionary properties may be defined for any answer UI type. For example, password fields display asterisks when text is entered at runtime. However, without the script developer explicitly associating validation to an answer definition in the data dictionary, no validation is performed on password fields.
Drop-down lists and radio buttons only have binary validation. In other words, when an answer definition of one of these types is either the only answer definition in a panel, or is set as the default for distinct branching, the Scripting Engine will not allow the script end user to bypass either of these controls and progress to the next panel without the user first selecting an option from the control. Technically, the button answer UI type can also be considered to have binary validation, because a panel containing an explicitly defined button (which does not allow any other answer controls) must receive a button click in order to progress to the next panel.
Write the JavaScript code.
Create a syntactically correct panel, including answer definitions.
Identify the panel into which JavaScript will be included.
Steps
Create a complete and syntactically correct panel in the Script Author.
If the script is created using the Script Wizard, graph the script (convert it to a graphical script). From the Script Manager wizard window, select the appropriate script and click Graph.
Open the panel layout editor for the panel.
From the File menu, select Export.
The Save window appears.
From the Location list and files displayed in the Files window, select the location on your network or filing system where you want to save the exported file.
In the File Name field, type the name you want to assign to the exported panel code, and click Save.
Note: The Script Author expects a file extension of .HTML. If you provide a file extension of .HTM, you may need to adjust the File Type filter to recognize the file when you attempt to re-import it.
Using a text editor or an HTML, modify the HTML code to include your JavaScript, and save your work.
In the Script Author, open the panel properties for the panel you edited.
From the panel properties tree, select Panel Layout.
In the Panel Layout pane, click Panel Layout Editor.
The panel layout editor for that panel appears.
From the File menu, select Import....
The Open window appears.
From the Location list and files displayed in the Files window, locate the modified file you want to import. Use the File Type filter if necessary.
When a suitable file is selected, its name appears in the File Name field.
Click Open.
The code populates the panel. All information is visible in the panel layout editor.
From the File menu, select Save and then Exit.
The panel text is saved and the panel layout editor window closes.
After any other desired changes in the Panel Properties window, click OK to save your work and close the window.
The canvas appears.
From the File menu, select Save.
Guidelines
Oracle Applications 11i-certified Web browsers such as Netscape Navigator and Microsoft Internet Explorer interpret JavaScript differently. This is traditionally an area of concern for Web developers. Issues with compatibility of custom JavaScript are generally a Web browser issue. As with all custom code, such issues are not supported by Oracle.
Panels with JavaScript must either be created or edited outside of the Script Author and imported as panel text prior to compiling and deploying the script.
Many custom JavaScripts are required to be included within the <HEAD> and </HEAD> tags of any HTML page.
Microsoft FrontPage does not allow the inclusion of any content after the </HTML> tag. When editing panel text containing any embedded values, ensure that the HTML editor has not removed embedded value codes. One workaround is to create embedded values after otherwise customizing panel layout content.