The purpose of this guide is to provide information about the Oracle Web Determinations templates in relation to how they are used to construct screens during an interview. This is intended to assist potential template developers in navigating the Oracle Web Determinations templates, explaining the design concepts behind the file structure and template architecture implementations, and the data available to templates from the Interview Engine.
The structure is as follows:
Sections 1 and 2 provide basic and core knowledge of the Oracle Web Determinations screens and templates.
Section 3 contains information on what templates are used for each screen. The information from the first two sections is useful to know, because it helps to understand what the screens are, and where the templates are located.
Section 4 is useful for an understanding of what data/information from the Interview Engine is available to Oracle Web Determinations templates
Note:
Oracle Web Determinations templates rely on the Apache Velocity template engine. It is important to be familiar with the Velocity templating language; see the Velocity Templates Developer Guide.
When a user goes through an Oracle Web Determinations interview, he/she will most likely encounter the screens below. These screens provide the core functionality of Oracle Web Determinations - conducting an investigation and allowing traceability for goals that have been determined successfully
The screens below may also be encountered depending on the Oracle Web Determinations setup, rulebase complexity, and other factors:
The following is a list of all of the screens available in Oracle Web Determinations, and a description of each one:
Screen name | Description |
---|---|
Rulebase Select | Displayed - when there are multiple rulebases and the user enters the Oracle Web Determinations webapp base URL. |
Locale Select | Displayed - when the user selects a rulebase, and the rulebase has more than one locale. |
Summary Screen | Displayed - when the user finishes investigating a goal, or the user clicks on the Summary link in the menu bar, or when the user starts a rulebase interview. |
Data Review | Displayed - when the user clicks on the Data Review link in the menu bar. |
Decision Report | Displayed - when the user clicks on the [Why] link next to a Goal that has been successfully investigated. |
Question Screen - Automatic | Displayed - during an investigation of a Goal, an Automatic screen is displayed if an attribute does not belong to an authored screen and needs to be asked for the determination of the current Goal. |
Question Screen - Authored | Displayed - during an investigation of a Goal or a Flow, attributes that need to be asked and belongs to an authored screen is displayed. The key difference between Automatic and Authored is that Authored usually has multiple attributes per screen, Automatic screens can only ask one attribute per screen. |
Entity Collect | Displayed - if the rulebase has Entities that need to be collected for the current Goal, the interview will present an Entity Collect screen to gather Entity Instances. Can be Automatic or Authored question screen. |
Relationship Reference | Displayed - if the rulebase has a many-to-many relationship between two Entities and the two Entities need to be collected for the current goal Can be Automatic or Authored question screen. |
Load Screen | Displayed - if the user clicks on the Load button. |
Save Screen | Displayed - if the user clicks on Save As, or in certain circumstances the Save screen. |
Load and Save Success | Displayed - when the user successfully saves or loads a session. |
Close/Restart Session | Displayed - when the user attempts to close or restart the current session. |
Error/Fail Page | Displayed - when there is a general error, or failure to perform a certain action such as save, load, restart or close. |
Commentary popup | Displayed - when the Oracle Web Determinations has been setup so the commentary opens in a new window instead of a frame. Clicking on a commentary link opens this popup. |
The Oracle Web Determinations templates are located in the following filepath (the template parent folder):
<OWD webapp>/WEB-INF/classes/templates
As an example, for a local Tomcat install it would be:
C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\web-determinations\WEB-INF\classes\templates
Base templates are templates that have the <html> tag. Therefore they are never included by any other template (unless that template is simply a 'proxy').
The base templates are most or all of the templates that are located directly under the template parent folder.
templates folder - the templates folder contains all the base template files, and also contain sub-folders that categorize the templates.
controls sub-folder - contains all the templates to render each control type. The name of the template maps to the classname of the Control object that depends on it (since the Interview Engine renders a screen by rendering Control objects inside the current Screen object). Note that some controls are used in screens other than the Question screen.
includes sub-folder - as the name implies, contains templates that are 'included' by all base templates. It contains Javascript includes and also page components that is displayed in most screens such as the header, footer, and bars.
investigation sub-folder - contains templates that are mostly used during 'investigation'; that is, Question screens.
session_control sub-folder - contains templates that are used for saving and loading a session. Some of the templates are 'proxy' templates in that they simply include a base template such as the 'generic_screen.vm'.
Below is a listing of the folder and file structure under the template parent folder. The underlined text are folders and the bold text are important templates
Below are descriptions for some of the templates that are important or would benefit from further explanation:
Template name | Description |
---|---|
generic_screen.vm | Template used for generic form-based screens such as the load or save as screens |
frameset.vm | Used when commentary is available for the rulebase, and commentary is displayed as frames. |
main.vm.css | Contains the CSS for each screen displayed (added inside the HTML head tag), added as a VTL reference $css-text in base templates. |
question_screen.vm | Used as the base template for any question screen (both authored and automatic) |
investigation/form.vm | Template included by any base screen that will display a 'form'. |
confirm_end_session_screen.vm | Template used by the Restart and Close (session) functions. |
includes/javascript-init.vm | Contains one Javascript function that is called by each base template for any 'Javascript initialisation' procedures. |
includes/javascript-browser-workarounds.vm | Contains Javascript functions that is solely for browser workarounds. |
includes/global-velocity.vm | Included by every base template, useful for setting Velocity variables that should be available in all templates. |
investigation/identifier-text.vm | Displays the attribute identifier next to the Control label of an attribute; for example, 'applicant_age'. |
investigation/input-style-override.vm | Implements the CSS Class and CSS Style 'override' from the Oracle Policy Modeling Screen Authoring. Included by many control templates. |
investigation/Link.vm | Used for various non-commentary links such as the link for documents (in the Summary screen) and the link in Load/Save Successful. |
investigation/control-text.vm | Displays the label of an input control depending on commentary availability and setting (setting - to frame or popup window). |
investigation/error.vm and
investigation/warning.vm |
Used by the screen-messages.vm and controlMessages.vm to display warning and error messages during an interview. |
controls/ButtonGroup.vm | Used in screens that have groups of buttons, such as the Save and Cancel buttons in the Save As screen. |
This section describes how the template files are used by the Templating Engine to build an Interview screen.
Oracle Web Determinations templates rely on one of the base templates as the 'skeleton' of a screen; for example, the Summary screen relies on the summary_screen.vm template as it's skeleton/foundation.
The following is a sequence diagram that demonstrates at a high level how Oracle Web Determinations decides which 'base' template' to use for the next screen:
To get a better understanding of how Oracle Web Determinations generates screens using templates, here is a run-through of a sample scenario and the process that Oracle Web Determinations goes through to generate the HTML for the screen using templates. The sample scenario starts at the point where a user answers the last Question screen with input data that completes the goal investigation, thus triggering Oracle Web Determinations to return the Summary screen as the next screen:
From the above scenario, steps 3 and 4 are the key steps. In these two steps, Oracle Web Determinations has determined the base template file for the next screen, and processes it through the Velocity Template engine to parse it from the template format to a full HTML format.
It should also be noted that Oracle Web Determinations base templates are really made up of sub-templates (which themselves also use sub-templates). Having sub-templates promotes re-use, so that the same component for different screen elements are reused and can be changed from one sub-template file; for example, the header.
This section explains how a base template and its sub-templates hierarchy is parsed by the Velocity Engine to generate the HTML form.
For Oracle Web Determinations, the Velocity Engine provides the following functionality:
When the Velocity Engine goes through the base template, it processes the VTL directives of the template.
It's much simpler to understand how a base template is processed to generate HTML by demonstrating it using a sample base template. This example provides a run-through of the start_screen.vm base template.
Analyze the start_screen.vm, and it's sub-templates for #parse statements; for example, '#parse("includes/header.vm")'
After analyzing the source for the start_screen.vm templates and all its other sub-templates, it is evident that the base template has one level of sub-templates; that is:
In the start_screen.vm template, the following code demonstrates Velocity references used as both HTML metadata (locale, pagedirString) and HTML display data (header-title):
<html lang="${locale}" dir="${pagedirString}">
<head>
<title>${header-title}</title>
From the start_screen.vm template, the following code demonstrates a Velocity reference ($rulebases) used in a for loop. The $rulebases reference is using a Java List that has been exposed by the Interview Engine to this template:
<div class="column">
<ul>
#foreach($rulebase in $rulebases)
<li><a name="${rulebase.key}" href="${rulebase.value}">${rulebase.key}</a></li>
#if($velocityCount % 23 == 0)
</ul>
</div>
<div class="column">
<ul>
#end
#end
</ul>
</div>
From the includes/header.vm, the code below demonstrates a Velocity reference (from appearance.properties file) being used in an if condition:
#if( ${show-application-name} == "true" )
<p class="application-name">${application-name}</p>
#end
With the above explanations, let's follow a detailed step-through for generating HTML from start_screen.vm:
Adding new templates is useful to ensure that template modifications are maintainable; this is particularly useful when making complex template modifications. Adding and using new template/s is done as follows:
Notes:
The following table contains a useful reference to the important screens and their base template/sub-template hierarchies:
* = may or may not be parsed depending on runtime values
Screen name | Screen template hierarchy |
---|---|
Summary Screen |
|
Data Review |
|
Decision Report |
|
Question Screen - Automatic |
|
Question Screen - Authored |
|
Maps all the screens to a base template as follows:
Screen name | Base template |
---|---|
Rulebase Select | start_screen.vm |
Locale Select | locale_selection_screen.vm |
Summary Screen | summary_screen.vm |
Data Review | data_review_screen.vm |
Decision Report | question_screen.vm |
Question Screen - Automatic | question_screen.vm |
Question Screen - Authored | question_screen.vm |
Load Screen | generic_screen.vm (via session_control/list.vm) |
Save Screen | generic_screen.vm (via session_control/save_as.vm) |
Load and Save Success | generic_screen.vm |
Close/Restart Session | confirm_end_session.vm |
Error/Fail Page | error_screeen.vm |
Question Screen with Commentary | frameset.vm |
The following diagram illustrates the default page structure and core layout for the Question screen:
The Velocity templates in Oracle Web Determinations have access to variables from property files, and objects/arrays/variables from the Interview Engine during runtime.
Oracle Web Determinations templates have access to the values of property files that are loaded for the template. Since each property is a key/value pair, Oracle Web Determinations templates simply refer to the property key to access the template.
The following are the property files that each Oracle Web Determinations template has access to during runtime:
It is possible to add properties to the property files, so that configuration settings for new template customizations stay in the property files. It is very simple to add new properties as follows:
The Interview Engine exposes many useful objects and variables to the Oracle Web Determinations templates; for example, it is possible to get the title of the current screen, or instance data of a certain entity's attribute, or the rulebase locale.
The Interview Engine exposes various properties that are accessible directly. These properties are application constants that are handy to have direct access to from any template. The following table contains the application constants from the Interview Engine:
Property name | Description |
---|---|
user-id |
|
locale | The locale of the current interview session. If the user has not selected a rulebase or locale, this uses the default locale in application.properties. |
image-resource-request |
|
context-root-path | The relative URI path to access the Oracle Web Determinations webapp from the webserver address; for example, if Oracle Web Determinations was set up in a Tomcat environment as 'web-determinations' webapp, the context-root-path is /web-determinations. |
resource-request |
|
rulebase | Name of the rulebase. |
rulebase-version | Version of the currently selected rulebase. |
rulebase-build-time | Time the currently selected rulebase was built, expressed as an ISO 8601 UTC data time. |
opm-version | Version of Oracle Policy Modeling with which the currently selected rulebase was built. |
version | Version of the Oracle Web Determinations running; for example, 10.1.0.1. |
case-id | Current case id attached to the session. |
page-uri | URI of the current screen. |
save-case-uri | URI to go to the Save screen. Used by the menu bar Save button. |
save-case-as-uri | URI to go to the Save As screen. Used by the menu bar Save As button. |
summary-screen-uri | URI to go to the Summary screen. Used by the menu bar Summary button. |
data-review-screen-uri | URI to go to the Data Review screen. Used by the menu bar Data Review button. |
close-session-uri | URI to go to the Close Session screen. Used by the menu bar Close button. |
restart-session-uri | URI to go to the Restart Session screen. Used by the menu bar Restart button. |
load-case-uri | URI to go to the Load screen. Used by the menu bar Load button. |
The Interview Engine exposes many useful objects via the Screen and InterviewSession objects. The InterviewSession object encapsulates other useful objects inside it. These objects need to be accessed via one of the Interview Session's methods and stored in a Velocity variable as follows:
#set $rulebase = $screen.getInterviewSession().getInterviewRulebase().getRulebase()
${rulebase.getLocale()}
The following table contains useful objects from the Interview Engine (or more accurately the Class), along with their description, and usage tips. For specific variables and methods of each Class, refer to Interview Engine's API:
Object name | Description | Usage |
---|---|---|
Screen |
|
|
InterviewSession |
|
|
SessionContext |
|
|
Session |
|
|
Rulebase |
|
|