Some screens and attributes during a Web Determinations interview are complex or ambiguous and need further explanation. Commentary functionality in Web Determinations allows the rulebase author to provide extra information about screens and attributes, which can be accessed by the user during the interview when more information or explanation is required. The commentary functionality also allows an external webpage to be displayed as commentary.
When commentary is available for a screen or attribute, the attribute/screen label is rendered as a link that the user can click on to view the commentary information. By default, commentary is displayed in a frame to the right of the interview screen. Optionally, it is possible to configure Web Determinations to display commentary information in a new window (for more about the configuration, see Configuration files). Attributes and screens do not have to have commentary, and it is possible for a Web Determinations interview to have commentary available for some screens/attributes only.
Commentary plugins are Engine Session plugins that manage commentary in a Web Determinations interview. The main functionality is to determine whether commentary for a screen/attribute is available, and to be able to provide the commentary content to those screens/attributes when requested. Commentary plugins have the flexibility of being able to retrieve content from datasources accessible in a Java/.NET class, or returning a URL to be displayed in the commentary frame/window. The ability to return a URL allows Commentary plugins that can make use of a client's existing information web pages.
Web Determinations ships with a default Commentary plugin that uses commentary HTML files generated from Oracle Policy Modeling by the rulebase author. For more information about the default Commentary, see the topic, Use the default Commentary.
Like many other plugins, only one Commentary plugin can be registered per Web Determinations interview.
Commentary plugin and the Web Determination architecture
Developing a Commentary plugin for a specific project/implementation
Sample code (RedirectCommentary)
The following are common scenarios that require custom Commentary plugins:
Ability to store and use commentary content from a datasource
There may already be commentary content stored in an existing datasource (for example, a file or database). Alternatively, there may be a desire to manage the commentary information via a Content Management System or other enterprise application. A custom Commentary plugin allows a Web Determinations interview to display commentary information from any datasource (or several datasources) by retrieving data from those datasources, formatting the data into a HTML page, and displaying the page.
Ability to display other web pages as commentary
There may already be existing web pages that serve as commentary to some attributes/screens of a Web Determinations Interview. These web pages can be the client's internal web pages, or even an external page owned by another party. A custom Commentary plugin allows a Web Determinations interview to provide a URL as commentary for a screen/attribute, and the web page of the URL is displayed as the commentary.
The following details how the Commentary plugin fits into the Web Determinations architecture, and how to use it in the Web Determinations environment:
When a Web Determinations interview begins, Web Determinations checks for custom Commentary plugins to register. If there is a custom Commentary plugin available, Web Determinations registers that plugin for the interview session. If there are no custom plugins, Web Determinations registers the default Commentary plugin.
During the Web Determinations interview, whenever a screen and control is to be rendered and displayed, Web Determinations uses the Commentary plugin to check whether:
The above allows Web Determinations to render screen and attribute labels as links. Screens/attributes that have available commentary can be clicked by the user to view commentary information, while screens/attributes without commentary are not able to be clicked.
When the user clicks on a screen/attribute label to see commentary information, Web Determinations calls the Commentary to provide commentary information. Web Determinations first checks the Commentary plugin to see if it will be returning a URL redirect or HTML content for the target (the screen/attribute that requires commentary). The Commentary plugin can read the target information provided and the current interview session data to determine whether to return a URL or HTML content.
If the Commentary plugin returns a URL for the target, Web Determinations gets the redirect URL from the Commentary plugin, and displays the web page of the URL as the commentary information.
If the Commentary plugin returns HTML content for the target, Web Determinations gets the HTML content from the Commentary plugin, and displays the HTML.
As mentioned in the overview, when the user clicks on a screen/attribute for commentary, Web Determinations will display the URL/HTML content as a frame to the right of the interview screen by default. But it is possible to configure the Web Determinations to display commentary information in a new window.
Other ways in which Commentary plugins can be used in Web Determinations is through other Web Determinations extensions.The Commentary plugin is accessible via the InterviewSession object, so only Web Determinations extensions with access to this object or its parent object SessionContext may use Commentary plugins.
As with other Web Determinations extensions, raising an exception is the common way to handle errors. Note that RuntimeExceptions must be raised in Java, not the generic exception.
A Commentary plugin implements the CommentaryProviderPlugin interface which in turn extends the InterviewSessionPlugin interface.
The CommentaryProviderPlugin interface requires the following when implemented:
| Method Signature | Description |
|---|---|
| boolean isCommentaryEnabled( InterviewSession session) |
|
| boolean hasCommentary( InterviewSession session, String target) |
|
| boolean isCommentaryRedirect( InterviewSession session, String target) |
|
| String getCommentaryURL( InterviewSession session, String target) |
|
| TypedInputStream getCommentaryContent( InterviewSession session, String target) |
|
The following explains the various approaches on designing and developing a Commentary plugin for a specific project/implementation:
There are 2 main input arguments provided to the Commentary plugin methods: the InterviewSession, and a string that represents the identifier for the target screen/attribute.
The InterviewSession has information about the current Web Determinations interview such as the locale selected, the rulebase being used, rulebase data model, and also data provided by the user to the interview so far. Information about using/accessing the InterviewSession object can be found in Understanding the InterviewSession
The 'target' string identifier identifies the screen or attribute that the Web Determinations needs to know more about from a commentary perspective. Web Determinations can ask the following questions about a target screen/attribute to the Commentary plugin:
The 'target' string is of a specific format. By default, it includes the type (attribute or screen), and the ID of the attribute/screen; for example:
To create a custom Commentary plugin that exclusively returns URLs for commentary:
To create a custom Commentary plugin that exclusively returns HTML content for commentary:
It is possible to create a Commentary plugin that can return HTML content or URL depending on the target (and/or InterviewSession). This requires the isCommentaryRedirect() method to be able to decide based on target and InterviewSession whether to return URL or HTML; this has the flow on effect that the hasCommentary() may also need to have separate checking mechanisms for targets that will return URL and targets that will return HTML