Customising the Standard Web Enactment Interface: The Mapping File

Certain PROforma components can be mapped to alternative content via the use of a XML mapping file. The mapping between the alternative content and the enactable process is achieved by binding a definition attribute in the XML to the name of the component in the PROforma content.

The XML mapping file conforms to the ‘http://www.cancerresearchuk.org/acl/proforma/ content#’ schema. If you have downloaded the Tallis Web Enactment suite, you can find the schema in \Apache Software Foundation\Tomcat 5.0\webapps\WEB_APP\WEB-INF\PROforma Content.xsd (or see The Mapping File XML Schema).

File Structure

Guideline Element

The content of the mapping file is contained within the guideline tag:

Task Elements

Five elements can populate the guideline tag: action, decision, enquiry, plan and task (i.e., keystone).

Customisations for each task are defined within task definition tags, which identify the specific task by adding the value of its PROforma Task Name to the definition attribute, e.g.:

A URI attribute, which specifies a specific page of content to be used rather than the automatically generated content, can be added to the task definition tag:

Customisations in a separate file override customisations in the mapping file. For more information about customised task pages see Customised Task Pages.

Another useful attribute that can be added to each task is stylesheet. It specifies a specific style sheet to be used rather than the standard runtime style sheet. Tasks inherit the stylesheet attribute of their parent-plan.

Customising PROforma Entities

The caption and the description of PROforma entities can be modified by using the mapping file.

Caption & Description

The caption tag will override the caption property of a PROforma component.

The description tag will override the description property of a PROforma component.

Both tags MUST be nested within a valid action, decision, enquiry, plan, task, candidate, argument, or source tag. They can contain any valid XML content.

Example:

Customising Tasks

A task’s caption and description can be modified as described above.

Additionally, the task’s context can be modified by using the context tag. The context tag can contain any valid XML content.

Customising Actions

In addition to the base task properties described above, an action’s procedure can be modified by using the procedure tag. The procedure tag can contain any valid XML content.

The delegate attribute of the action tag can be used to group and display a set of actions on one page, by pointing to a specified PROforma plan. This is described in the Customising Plans section below.

Customising Enquiries

The mapping file enables users to control the order of the sources displayed for an enquiry and the user interface widget used for each source, and to introduce dependencies between sources.

The enquiry task definition tag can contain a sources tag – which contains at least one source tag – and one or more dependency tags.

The delegate attribute of the enquiry tag can be used to group and display a set of enquiries on one page, by pointing to a specified PROforma plan. This is described in the Customising Plans section below.

Source Tag

The source tag has three attributes:

• definition – identifies a PROforma source by its Name value
• position – an integer which defines the position of the source on the page, according to the following order:
• 
• dropdown – determines whether the source values are displayed using radio-buttons (or checkboxes in the case of multiple selection of values) or a dropdown list. By default, checkboxes or radio-buttons are used (dropdown=false).

Example:

On the left is the default screen layout; on the right is the screen layout using the above mapping file customisation.

Dependency Tag

This tag determines dependencies between sources. The tag defines a source attribute and a keyword value for that source, for which the nested source would be disabled, e.g.:

The pregnancy source is disabled if the male value is selected for the sex source.

Customising Decisions

If a decision has sources, it can be customised just like an enquiry (see Customising Enquiries above). Additionally, captions and descriptions of decisions, candidates and arguments can be modified using the relevant tags (see Customising PROforma Entities above).

Each decision tag can have one candidates tag. This tag must contain at least one candidate tag. A candidate tag can contain one arguments tag. This tag must contain at least one argument tag.

The maxRecommendations attribute of the decision tag can be used to determine the maximum number of candidates to be presented to the end-user as recommended, irrespective of how many are actually recommended by the enactment engine.

Example:

Note: In the current version of Tallis Composer (1.4) arguments do not have a Name field. Instead, the argument’s condition is automatically entered as argument name in the PROforma definition. This makes the use of the argument tag cumbersome and error-prone.

Customising Plans

Plans extend the base task properties by allowing an optional grouping sub-element. The grouping element must contain valid action or enquiry definition names from within the mapping file. The action and enquiry elements must also use their delegate attribute to bind to the name of the plan mapping. Any actions or enquiries listed in the grouping and that are in the in_progress state are rendered within the same page rather than individually.

The plan has to point to a customised plan page that will display the multiple enquiries (if you have downloaded the Tallis Web Enactment suite, you can find a customised plan page for enquiries (enquiryGroup.jsp) and one for actions (actionGroup.jsp) in \Apache Software Foundation\Tomcat 5.0\webapps\WEB_ APP\customisations\pages\).

Example:

Location

The mapping file has to be placed within the web enactment application folder, e.g.:

webapps/tallis/MappingFile.xml

or

webapps/tallis/customisations/mappings/MappingFile.xml

Pointing to the Mapping File

The customised process-description has to point to the mapping file. This is done via the Context field of the top-level plan.

In the Context field of the top-level plan type:

#metadata
tallis.content = PATH_TO_MAPPING_FILE

The path is relative to the web application, e.g:

#metadata
tallis.content = /customisations/mappings/mappingFile.xml

See Also

• Customising the Standard Web Enactment Interface

• Hands-on Tutorial

• Tallis Interface Primer

• The Mapping File XML Schema