Skip navigation.
Architecture Briefs

Widgets

Wizard Pages

The wizTemplate.xhtml template provides the overall structure of a wizard and places it properly within the application menu and pane hierarchy.

As with all XHTML, the contents of wizard pages must be valid, well-formed XML. Loose HTML, such as un-closed tags, will result in an error. All wizard pages must contain something like the following:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
        xmlns:ui="http://java.sun.com/jsf/facelets"
        xmlns:f="http://java.sun.com/jsf/core"
        xmlns:h="http://java.sun.com/jsf/html"
        xmlns:c="http://java.sun.com/jstl/core"
        xmlns:wiz="http://www.tolven.org/jsf/wizard"
        xmlns:trim="http://www.tolven.org/jsf/trim">
    <head>
        <title>This title is ignored but useful for documentation</title>
    </head>
    <body>
        <ui:composition template="wizTemplate.xhtml">
        <ui:param name="title" value="#{trim.trim.act.title.ST.value}"/>
        <ui:param name="author" value="Tolven"/>
        <ui:param name="subject" 
         value="#{menu.menuDataItem.parent01.string02} #{menu.menuDataItem.parent01.string01}"/>
        <ui:define name="steps">
            ... see below  ...
        </ui:define>
    </body>
</html>

Composition of a Wizard

A wizard is composed of steps. The first step, by convention, usually provides a "Getting Started" overview of thw wizard so that the user knows what is about to occur. The last step is always where submit occurs. There are a number of special behaviors assiated with the last step:

  1. The last step must not contain any user enterable widgets.
  2. The last step is a display-only rendering of the data to be submitted.
  3. The last step is rendered from a "drilldown" display, not steps and widgets
  4. The last step will contain an error summary with links to specific widgets in the wizard ocntaining error that need to be fixed before submission.
  5. The last step is always a direct rendering from the server. In other words, the data on the last step must already exist in the database.
  6. The drilldown page used for the last step is also used for subsequent drilldown after the submission has occured. The wizard itself cannot be displayed again after submission. The document is immutable after submission. (An update is always to a new version of the document, not the submitted version)

The data behind most wizards is a TRIM document. The TRIM document is initially instantiated on the server. A work in process item is usually created so that if the user does not complete the work, it can be finished later.

Each question widget has a hidden error message display field that is revealed when an error is detected.

Steps are typically composed of groups (field sets) that visually encapsulate groups of one or more questions. Groups can be nested. For example, a group entitled "abdomen" might have groups within it named "upper left quadrant, upper right quadrant, etc"

A question can contain more than one data entty (form) field but usually only contains one.

Conditional Display

Widgets have an optional attribute that controls the visibility of that widget and the widget's children. Visibility is evaluated dynamically. For example, checking a checkbox might immediately affect the visibility of other widgets in a wizard.

Visibility of a widget is always controlled by the widget itself, not some other widget. For example, a checkbox that "controls" visibility of an "additional details" section simply represents the value of that setting. Each widget in the additional details section must reference the checkbox.

Visibility of widgets extends to the entire wizard but no further. For example, a checkbox on the first step of a wizard may affect the visibility of widgets on any other step in that wizard. While the visibility of a widget can be dependent on the value of another widget visually after the widget being controlled, this would be difficult for the user to folllow.

If a step itself has conditional visibility, and if the step is determined to be invisible, then the icon representing that step in the wizard header is disabled but not hidden. A navigation to the "next step" will skip over any disabled steps as if the step were not there.

Visibility of a widget is determined by evaluating the boolean result of a Javascript expression evaluation.

The answers given in a conditional section of the wizard are not removed when the section becomes hidden. Therefore, when the section becomes visible again, the contained questions are as they wer before being hidden.

As implied above, all questions are stored in the document, even trivial questions like "hide/show details". This is done for two reasons.

  1. There may be a need later to know what the user's response was to that trivial question.
  2. The answer to trivial questions (as well as the critical questions) are used to restore a wizard from "work in process". For example, a user that has answered a few questions, is called away and then must return to the same wizard, the answers to these trivial questions should be restored.

In the following, a simple yesno question is asked regarding additional details and then two groups depend on the answer to that question for visibility. 

<wiz:group title="Additional Details" >
    <wiz:yesno id="weightDetails">Add?</wiz:yesno>
    <wiz:group title="Device" visible="$('#{menu.elementLabel}:weightDetails').isTrue();">
        <trim:CE id="device" layout="pageDirection" valueSet="device" 
            value="#{trim.trim.act.relationships[1].act.observation.value}"/>
    </wiz:group>
    <wiz:group title="Clothing" visible="$('#{menu.elementLabel}:weightDetails').isTrue();">
        <trim:CE id="clothing" valueSet="clothing" 
            value="#{trim.trim.act.relationships[0].act.observation.value}"/>
    </wiz:group>
</wiz:group>

The Javascript syntax within the visible attribute can be explained as follows: 

visible="$('#{menu.elementLabel}:weightDetails').isTrue();"

'#{menu.elementLabel}:weightDetails' yields the exact id of the yes-no widget. #{menu.elementLabel} is the id prefix applied to the specific instance of the wizard (more than one wizard may be open at the same time).

 

$() does a getElementById to yield the actual widget from its name.

The isTrue() function returns true if the yesno radio widget has a true value (a no or unanswered question would yield false)

Conditional Expressions

Conditional expressions are evaluated in Javascript so references on that language may prove useful. Comparisons are done in the datatype of the value of the question being interrogated (boolean, string, or number).

The folllowing are a list of expressions supplied by tolven and a few Javascript operators:

 

Syntax Description
arg1 && arg2 Return true if arg1 and arg2 are both true, otherwize false
arg1 || arg2 Return true if either arg1 or arg2 is true. Return false if both arg1 and arg2 are false.
gt(value ) Return true if answer is greater than value
ge(value ) Return true if answer is greater than or equal to value
lt(value ) Return true if answer is less than value
le(value ) Return true if answer is less than or equal to value
eq(value ) Return true if answer is equal to value
ne(value ) Return true if answer is not equal to value
is(value )  
isTrue( ) Return true if answer is true or contains the string true
isFalse( ) Return true if object is false or contains the string flase.
isAnswered( ) Return true if the question has been answered
isNotAnswered() Return true if the question has not been answered
isNotTrue() Return true if the question has not been answered or it has been answer false.
isNotFalse() Return true if the answer has not been answered or it has been answer true.
getAnswer() Return the answer
( ) Modify natual precidence of evaluation

 

Backing Data

A wzard containing widgets is tied to a Tolven document created by an instantiation process that is described elsewhere. While many of the general-purpose widgets don't depend on any particular document format, others specifically depend on TRIM-based documents and therefore the bulk of this document assumes a TRIM-based document.

In some cases, this means accessing Tolven-specific features of a TRIM document such as the generic field map but most often reference is made to HL7 RIM-defined elements. In fact, there are a number of widgets that interact explicitly with HL7 datatypes or RIM objects.

While documents are typically stored as XML, they are made available to web pages as an object model in server memory (not on the browser). For example, TRIM documents are represented by the classes in the package org.tolven.trim. Access to document instance data is via the MenuAction backing bean and a subclass of that bean called TrimBean.

The Java Universal Expression Language (javax.el) is used to access the resulting object tree. For example, the following expression references the title attribute of the root act of a trim object (the second trim) accessible from the trim backing bean (the first trim). The job of the backing bean is to provide access to the TRIM object represented by the parameters supplied in the servlet request. In other words the trim backing bean knows how to make the correct trim object available. From there, each 

#{trim.trim.act.title}

This expression doesn't actually yield a primitive datatype. It yields a TRIM attribute "slot" which contains an appropriate datatype for the attribute, in this case, either ST or ED datatypes are appropriate.

General Widgets

These widgets are used for general data entry. Some of the widgets, such as body and step are necessary elements used in all wizards.

wiz:body

Defines the body of a single wizard step. Each step must have exactly one body.

wiz:body
Attribute Description Required
title The title to be displayed for the step required
visible Boolean expression indicating visibility of step (in the case of an invisible step, the step icon at the top of the pane is dimmed but not hidden. optional

 

		
<wiz:step title="Getting Started" >
    <wiz:body>
        <p>Click the next button...</p>
    </wiz:body>
    <wiz:help>
        <h1>getting Started</h1>
        <p>Help provides additional information about each page</p>    
    	<p>You can close this form by clicking the [x] above at any time. 
        </p>
    </wiz:help>
</wiz:step>
wiz:certainty

This widget asks a canned question about cetainty expressed as a radio button with choices of Certain or Hesitant. For more information, see wiz:radio.

wiz:certainty
Attribute Description Required
id The unique id of the question required
wiz:check

This wiget presents a simple checkbox as a question.

wiz:check
Attribute Description Required
id The unique id of the question required
value A boolean attribute where the result of the checkbox is displayed/stored required

The children of this tag will be used as the label for the text field. 

<wiz:check id="interruptok" value="#{trim.trim.act.interruptibleInd}">
    <h:outputText value="Can this be interrupted?"/>
</wiz:check>
wiz:checkGeneric

This wiget presents a simple checkbox as a question and stors the result in the generic answer section of the document. The response is stored in the map of answers under the id.

wiz:checkGeneric
Attribute Description Required
id The unique id of the question required

The children of this tag will be used as the label for the text field. 

<wiz:checkGeneric id="showDetails">
    <h:outputText value="Show Additional Details?"/>
</wiz:checkGeneric>
wiz:downloadStep

[TBD] This wiget presents a download option to the user such as to create an email containing the contents of some document.

wiz:downloadStep
Attribute Description Required
id The unique id of the question required
wiz:group

This wiget surrounds a group of questions with a fieldSet. A group can also have a visibility test so that a group of questions can be hidden or shown.

wiz:genericText
Attribute Description Required
id The unique id of the question required
size The number of characters wide to make the text box required

The children of this tag will be used as the label for the text field. 

<wiz:genericText id="comment" size="40">
    <h:outputText value="Your comments"/>
</wiz:genericText>
wiz:help

The help wiget defines a help section within a wizard step or a wizard group.

wiz:genericText
Attribute Description Required
title The Name of the help section required

The children of this tag will be used as the contents of the help box. Help is toggled by the ? Icon on the page. 

<wiz:help title="comment">
    <p>The weight you enter should be taken directly from the scale. 
    Do not estimate this value.</p>
</wiz:help>
wiz:info

 

wiz:integerGeneric

The integer wiget defines an input field that accepts only a number in the form of a whole integer.

wiz:genericText
Attribute Description Required
id The unique id of the value field required
min The minimum value allowed required
max The maximum value allowed required

The children of this tag will be used as the Label for the field. 

<wiz:integerGeneric id="pushups" min="0" max="10000">
    How many pushups
</wiz:integerGeneric>
wiz:question

 

wiz:radio

 

wiz:radioGeneric

 

wiz:step

 

wiz:textGeneric

This wiget presents a text box and stores the resulting text in the generic answer section of the document. The text the gerneric map is stored and can be fetched by the id property.

wiz:genericText
Attribute Description Required
id The unique id of the question required
size The number of characters wide to make the text box required

The children of this tag will be used as the label for the text field. 

<wiz:textGeneric id="comment" size="40">
    <h:outputText value="Your comments"/>
</wiz:textGeneric>
wiz:uploadStep

 

wiz:yesNo

 

TRIM Widgets

These convenience widgets know how to access Specific HL7 Datatypes and certain RIM classes. They also access the label attribute from the TRIM document rather than the label being hard-coded in the form.

trim:AD
trim:CE
trim:ED
trim:EN
trim:II
trim:patient
trim:person
trim:PQ
trim:TS

 

Defining Custom Widgets

The widgets described here are defined using the Facelets

Support

Rely on the Tolven support team to help resolve problems during any stage of your application development lifecycle, deployment or implementation.

Visit TolvenHealth.com