Working with Display Elements (Oracle Waveset 8.1.1 Deployment Reference)

Oracle Waveset 8.1.1 Deployment Reference

Working with Display Elements

The display elements you will most modify or add to an Waveset form are buttons, fields, and text entry boxes. Other display elements include tables and section headers.

Any display element that does not have a specified Display class will be hidden.

Buttons

To create a typical push button, use the <Button> component.

To align multiple buttons in a horizontal row, use the <ButtonRow> component.

<Field>
   <Display class=’Button’>
      <Property name=’location’ value=’true’/>
      <Property name=’label’ value=’Cancel’/>
      <Property name=’command’ value=’Cancel’/>
   </Display>
</Field>

To position the button in a button row, include the following code in your button definition: <Property name=’location ’ value=’ button ’/>. If you do not set this Property field, the button will appear in the form in the order in which you include it in the form.

Assigning or Changing a Button Label

When defining a button, its label is identified by the value setting in the label property as indicated below.

<Display class=’Button’>
   <Property name=’label’ value=’Cancel’/>

The browser displays the preceding code as a button labeled Cancel.

Overwriting Default Button Names

Two buttons typically are displayed at the bottom of Waveset forms. By default, the buttons are labeled Save and Cancel.

To Change Default Button Names

On the line that defines the form name (in the header), change the name field

<Form name=’Anonymous User Menu’>

   to

<Form name=’Anonymous User Menu’ noDefaultButtons=true>

At the bottom of the form, add the following fields for the Save and Cancel buttons, and change the labels as desired:

<Field>
   <Display class=’Button’>
      <Property name=’label’ value=’Submit’/>
      <Property name=’name’ value=’submitButton’/>
      <Property name=’value’ value=’true’/>
      <Property name=’command’ value=’Save’/>
   </Display>
</Field>
<Field>
   <Display class=’Button’>
      <Property name=’label’ value=’Cancel’/>
      <Property name=’command’ value=’Cancel’/>
      <Property name=’location’ value=’true’/>
   </Display>
</Field>

Command Values and Buttons

Note –

This section is important only if you are building Button objects. If you are building components from XML forms, you can assume that the values in the following table are recognized.

All pages in the Waveset interfaces have used the post data parameter named command as a mechanism to convey which form submission button was pressed. Page processing systems using components are not required to follow the same convention, but there are some components that contain special support for the command parameter, in particular the Button component.

Some page processing systems, notably the one that processes XML forms, expect the command parameter to be used. Further, several command parameter values have been used to indicate particular actions. These values are described in the following table.

Table 2–11 Possible Values for the command Parameter


Parameter	Description
Save	Indicates that the contents of the form should be saved.
Cancel	Indicates that contents of the form should be thrown away.
Recalculate	Indicates that the form should be refreshed based on entered data.

Any value can be used for the command parameter, but you must know which unrecognized command value usually results in a redisplay of the page.

Aligning Buttons with <ButtonRow> Element

To align multiple buttons in a row, use the ButtonRow element.

<Field name=’OrganizeButtons’>
   <Display class=’ButtonRow’>
      <Property name=’title’ value=’Choose a Button’/>
   </Display>
<Field name=’ChangePassword’>
   <Display class=’Button’>
      <Property name=’label’ value=’Change Password’/>
      <Property name=’value’ value=’Recalculate’/>
   </Display>
</Field>
<Field name=’ResetPassword’>
   <Display class=’Button’>
      <Property name=’label’ value=’Reset Password’/>
      <Property name=’value’ value=’Recalculate’/>
   </Display>
</Field>

Text Fields

You can include both single-line and multi-line text entry boxes in a form. To create a single-line text entry field, use the <Text> element. To create a multi-line text entry field, use the <TextArea> element.

<Display class=’Text’>
   <Property name=’title’ value=’Zip Code’/>
   <Property name=’size’ value=’10’/>
   <Property name=’maxLength’ value=’10’/>
   <Property name=’required’ value=’true’/>
</Display>

Assigning or Changing a Field Label

When defining a text field or area, its label is identified by the value property of the label property as indicated below.

<Display class=’Text’>
   <Property name=’label’ value=’Input’/>

The browser displays the preceding code as a text entry field labeled Input.

Containers

Some display elements are contained within components called container components. Container components offer a way to:

Collect multiple components to visually organize in a particular way. Simple containers can concatenate the components horizontally or vertically. Other containers allow more flexible positioning of components and can add ornamentation around the components.
Group components that you want to hide or disable on a form.

Creating a container class typically results in the generation of an HTML table tag.

Typical container components are described in the following table.

Table 2–12 Typical Container Components


Component	Description
`<SimpleTable>`	Arranges components in a grid with an optional row of column titles at the top
`<ButtonRow>`	Arranges button in a horizontal row. This component is essentially a panel that is preconfigured for horizontal layout.
`<BorderedPanel>`	Positions components into five regions: north, south, east, and west
`<SortingTable>`	Displays a blue and beige table with sortable columns.

Creating a Simple Table

The <SimpleTable> component is a frequently used container component in Waveset forms. It arranges components in a grid with an optional row of column titles at the top. The only property for this display component is columns, which assigns column titles and defines the width of the table as defined in a list of strings.

In the following example, a field that uses SimpleTable to organize several subfields:

<Field name=’SelectionTable’>
   <Display class=’SimpleTable’>
      <Property name=’columns’>
         <List>
            <String>Account</String>
            <String>Description</String>
         </List>
      </Property>
   </Display>
   <Field name=’accounts[LDAP].selected’>
      <Display class=’Checkbox’>
         <Property name=’label’ value=’LDAP’/>
      </Display>

   </Field>
   <Field>
      <Display class=’Label’>
         <Property name=’text’ value=’Primary Corporate LDAP Server’/>
      </Display>
   </Field>
   <Field name=’accounts[W2K].selected’>
      <Display class=’Checkbox’>
         <Property name=’label’ value=’Windows 2000’/>
      </Display>
   </Field>
   <Field>
      <Display class=’Label’>
      <Property name=’text’ value=’Primary Windows 2000 Server’/>
      </Display>
   </Field>

</Field>

Grouping Components

To group multiple components on a form to hide or disable them, use the <SimpleTable> container as shown in the following example.

Example 2–10 Grouping Components for a Form

<Field>
   <Disable>
      <not>
         <contains>
            <ref>accountInfo.typeNames</ref>
            <s>Windows Active Directory</s>
         </contains>
      </not>
   </Disable>
   <Field name=’accounts[AD].HomeDirectory’>
      <Display class=’Text’>
         <Property name=’title’ value=’Home Directory’>
      </Display>
   </Field>
</Field>

Working with Lists

The component you use to create a list depends upon list length and whether the user can select more than one option simultaneously.

Text boxes often supply a list of options from which a user can select. These lists are populated by specifying choices within a property called allowedValues or by obtaining values dynamically through a method call (FormUtil class methods) to the resource. For information on populating text areas with lists, see the section titled Populating Lists in this chapter.

The following table describes typical list types and the HTML display components used to create them.

Table 2–13 Typical List Types and Associated Display Components


Type of List	HTML Component
Option list that offers mutually exclusive values such as true and false	`<CheckBox>` See the section titled Creating a Checkbox.
Multiple-option list in which users can select only one option	`<RadioButton>` See the section titled Creating a Radio Button.
Multiple-option list (with many options) in which users can select only one option	`<Select>` See the section titled Creating a Single-Selection List.
Multiple-option list in which multiple options can be selected simultaneously	`<MultiSelect>` See the section titled Creating a Multiselection List.

Creating a Checkbox

Use the <Checkbox> component to display a checkbox. When selected, the box represents a value of true. ACreating a Checkbox Creating a Checkbox cleared box represents a false value. You can change the checkbox name by editing the value of the label property.

Example 1

<Field name=’accounts[LDAP].selected’>
   <Display class=’Checkbox’>
      <Property name=’label’ value=’LDAP’/>
   </Display>
</Field>

Example 2

<Field name=’global.Password.Expired’>
   <Display class=’CheckBox’>
      <Property name=’title’ value=’User must change password at
      next login’/>
      <Property name=’alignment’ value=’left’/>
   </Display>
</Field>

Creating a Radio Button

Use the <Radio> component to display a horizontal list of one or more radio buttons. A user can select only one radio button at a time. If the component value is null or does not match any of the allowed values, no button is selected.

<Field name=’global.EmployeeType’>
   <Display class=’Radio’>
      <Property name=’title’ value=’EmployeeType’/>
      <Property name=’labels’ value=’Employee, Contractor, Temporary, Part Time’/>
      <Property name=’required’ value=’true’/>
   </Display>
</Field>

Creating a Single-Selection List

Along with the <MultiSelect> component, the <Select> component provides a list of items to select from. With longer lists of values to select from, the radio buttons can begin to take up precious space on a form. Alternatively, select lists can provide a way for the user to select from a long list of possible values. This list supports type-ahead if the list is ordered. You can use the allowedValues property to specify the choices from which the user can pick.

<Field name=’global.title’>
   <Display class=’Select’>
      <Property name=’title’ value=’Title’/>
      <Property name=’allowedValues’>
         <List>
         <String>Staff</String>
         <String>Manager</String>
         <String>Director</String>
         <String>VP</String>
         </List>
      </Property>
   </Display>
</Field>

Creating a Multiselection List

The <MultiSelect> component displays a multiselection list box. This textbox displays as a two-part object in which a defined set of values in one box can be moved to a selected box. Values for the list box can be supplied by allowedValues elements or obtained dynamically through a method call, such as getResources.

Along with the <Select> component, the <MultiSelect> component can dynamically provide a list of items from which to select. These lists are populated by specifying choices within a property called allowedValues or by obtaining values dynamically through a method call to the resource. For information on populating lists within a multiselection entry box, see the section titled Populating Lists.

<Field name=’waveset.roles’>
   <Display class=’MultiSelect’ action=’true’>
      <Property name=’title’ value=’Roles’/>
      <Property name=’availableTitle’ value=’Available Roles’/>
      <Property name=’selectedTitle’ value=’Current Roles’/>
      <Property name=’allowedValues’>
            <invoke name=’getObjectNames’ class=’com.waveset.ui.FormUtil’>

               <ref>display.session</ref>
               <s>Role</s>
               <ref>waveset.original.roles</ref>
            </invoke>
      </Property>
   </Display>
</Field>

Alternative Display Values in a Select List

You can create a Select list that displays a different set of values than the values that will actually be assigned to the field. This is often used to provide more recognizable names for cryptic values, or to perform internationalization. This is accomplished by using the valueMap property to associate the displayed value with the actual value, as shown in the following example:

Example 2–11 Changing Values for Select Lists Using the `valueMap` property

<Field name=’waveset.organization’>
<Display class=’Select’>
<Property name=’title’ value=’Add Account’/>
<Property name=’nullLabel’ value=’Select...’/>
<Property name=’valueMap’>
<list>
<s>Top</s>
<s>Top Level</s>
<s>Top:OrgB</s>
<s>Ted’s Organization</s>
<s>Top:OrgC</s>
<s>Super Secret Org</s>
</list>
</Property>
</Display>
</Field>

In the preceding example, the value map is specified as a list of pairs of strings. The odd-numbered strings are the actual values that are assigned to this field. The even-numbered strings are the values that are displayed in the select list. For example, if the select list entry Ted’s Organization is selected, the value of this field becomes Top:Orgb.

Populating Lists

Lists are frequently populated with options that are dynamically calculated from information that resides in the user object or an external resource. When creating this type of list, you must first create the HTML list components in the form before populating the list. (For additional information on using the HTML text box components, see the sections titled Creating a Single-Selection List and Creating a Multiselection List.)

There are two ways to populate these lists, including the methods covered in this section:

Populating lists with the allowedValues property
Using FormUtil methods to populate either single-selection or multiselection lists with information dynamically derived from an external resource.

See the section titled Representing Lists in XML Object Language and XPRESS for a discussion of the advantages to using XML Object language rather than XPRESS for certain tasks.

Populating Lists of Allowed Values

The most typical way of populating lists in forms is through the use of the allowedValues property. From this property, you can specify an optional list of permitted values for <Select> and <MultiSelect> elements. The value of this component is always a list and usually contains strings.

<Field name=’department’>
   <Display class=’Select’ action=’true’>
      <Property name=’title’ value=’Department’/>
      <Property name=’allowedValues’>
         <List>
         <String>Accounting</String>
         <String>Human Resources</String>
         <String>Sales</String>
         <String>Engineering</String>
         </List>
      </Property>
   </Display>
</Field>

Dynamically Populating a Multiselection List of Groups

Multiselection lists typically contain two parts:

The left side of the list displays the items that are available for selection. These values are defined by the allowedValues property. This property can be a list of strings, a list of XML object strings, or a list of strings returned from a call to a Java method.
The right side of the list displays the items that are currently selected. These values are set by selecting one or more items from the left side’s allowedValues list and pushing these selections to the selected list. The right side of the list is also populated when the form is loaded and the current settings are retrieved.

Adding a Multiselection List of Groups

To add a multiselection list of groups that is populated dynamically from the resource

Add groups to the right side of the schema map. The values displayed in the right side of a text area that displays a multiselection list are populated from the current value of the associated view attribute, which you identify through the field name.
Add the following text to any form, changing only the Field name, prompt, availabletitle, selectedtitle, and the name of the resource as needed.

Note –

In the following example, the: (colon) that precedes display.session indicates that you can ignore the base context of the form and reference objects from the root of the workflow context.

In the following example, the : (colon) that precedes display.session indicates that you can ignore the base context of the form and reference objects from the root of the workflow context.

<Field name=’global.AD Groups’>
  <Display class=’MultiSelect’ action=’true’>
    <Property name=’title’ value=’AD Group Membership’/>
    <Property name=’availableTitle’ value=’Available AD Groups’/>
    <Property name=’selectedTitle’ value=’Selected AD Groups’/>
    <Property name=’allowedValues’>
      <invoke class=’com.waveset.ui.FormUtil’  name=’listResourceObjects’>
        <!-- send session information which will be used by the method to 
             validate authorization user -->
        <ref>:display.session</ref>
        <!-- resource object type–  This will differ from resource to 
             resource, but common types are account, group, and 
            “distribution list” -->
        <s>Group</s>
        <!—- Name of resource being called -->
        <s>AD Resource Name</s>
        <!-- options map–  Some resources have options like the context 
             that the group is listed in.For example, active directory has multiple 
             containers. By default, the container used will be the one specified on 
             the resource.The value can be overridden by specifying it here. 
             If the resource does not support options,the value should be <null/> -->
        <Map>
         <MapEntry key=’context’ value=’ou=Austin,ou=Texas,dc=Sun,dc=com’/>
        </Map>
        <!-- cacheList–  specify true or false whether you would like this list to 
             appear in the Resource Object List Cache-->
        <s>true</s>
      </invoke>
    </Property>
  </Display>
</Field>

Note –

If the resource does not support options, the value of options map should be null. Some resources have options such as the context that the group is listed in. For example, Active Directory has multiple containers. By default, the container used will be the one specified on the resource. This value can be overridden by specifying it here.

Specify the value of cacheList as true or false to designate whether this list should be stored in the Resource Object List Cache. This will cause the method to be run once, and the results are stored on the server.

Creating a Text Entry Field in a Selection List

There are some conditions under which you’d like to include an option in a selection list in which the user can enter a value instead of choosing from the list. You can create this feature by implementing the three fields as shown in the following example.

This example creates a selection box with the text string Other in it and an adjacent text box. When the user selects the Other option from the selection box, the page presents a new field in which the user can enter custom information.
Implements the defvar element to create a variable that defines a list of job positions from which a user can select a relevant position.

Note –

Consider putting into a rule any variables that will be referenced in a form multiple times. In the following example, a list of items to select from is stored in a variable (in the example, titleList), which allows the Derivation rule to search through it.

The following example is interspersed with descriptive text.

<defvar name=’titleList’>
  <list>
    <s>Manager</s>
    <s>Accountant</s>
    <s>Programmer</s>
    <s>Assistant</s>
    <s>Travel Agent</s>
    <s>Other</s>
  </list>
</defvar>

The next part of this example contains two visible fields called title and otherTitle. The otherTitle field is displayed only if the user chooses the other option on the selection list. The third hidden field is global.Title, which is set from either Title or otherTitle.

The Title field is the main field that the user will select from. If the user cannot find the item that he wants in the list, he can select Other. This is a transient field and is not stored or passed to the workflow process when you click Save. A Derivation rule is used to send the value from the resource and determine if the value is in the list.

Note –

In the following example, action is set to true to ensure that form fields populate automatically.

<Field name=’Title’>
   <Display class=’Select’ action=’true’>
      <Property name=’title’ value=’Title’/>
      <Property name=’allowedValues’>
      <Property name=’nullLabel’ value=’Select …"/>
         <expression>
           <ref>titleList</ref>
         </expression>
      </Property>
   </Display>
   <Derivation>
      <cond>
         <isnull><ref>global.Title</ref></isnull>
         <null/>
      <cond>
         <eq>
            <contains>
               <ref>titleList</ref>
               <ref>global.Title</ref>
            </contains>
            <i>1</i>
         </eq>
         <ref>global.Title</ref>
            <s>Other</s>
      </cond>
      </cond>
   </Derivation>
</Field>

The Other field will appear on the form only if the user has selected Other from the title field. The value of the Other field is set when the form is loaded. It is based upon the value of the Title field and the global.title field.

<Field name=’otherTitle’>
    <Display class=’Text’>
      <Property name=’title’ value=’Other Title’/>
      <Property name=’rowHold’ value=’true’/>
      <Property name=’noWrap’ value=’true’/>
      <Property name=’size’ value=’15’/>
      <Property name=’maxLength’ value=’25’/>
    </Display>
    <Disable>
      <neq>
        <ref>Title</ref>
        <s>Other</s>
      </neq>
    </Disable>
    <Derivation>
      <cond>
        <eq>
          <ref>Title</ref>
          <s>Other</s>
        </eq>
        <ref>global.Title</ref>
      </cond>
    </Derivation>
</Field>

The value of Field is based on the value of the Title field. If the value of this field is set to Other, then the field value is defined by the value of the otherTitle field. Otherwise, it will be the value of the Title field.

<Field name=’Title’>
   <Expansion>
     <cond>
       <eq>
         <ref>global.fieldTitle</ref>
         <s>Other</s>
       </eq>
       <ref>otherTitle</ref>
       <ref>Title</ref>
     </cond>
   </Expansion>
</Field>

Filtering the List of Resource Accounts before Display in a Form

You can filter the list of resource accounts before displaying them in a form. By default, no filters are applied, except with the Change Password Form in the User Interface, which preserves the default behavior of filtering disabled accounts from the list displayed to the user.

This Exclude filter is defined as a Form property. The filter is a list of one or more AttributeConditions that, when evaluated, determine if a given resource account should be excluded from the displayed list.

Forms that Support This Feature

The following Forms support the specification of an Exclude filter as a Form property:

Change Password Form (User Interface)

Administrator Interface Forms:

Change User Password Form
Deprovision Form
Disable Form
Enable Form
Rename Form
Reprovision Form
Reset User Password Form
Unlock Form

<Exclude> Property Format

The Exclude Form Property takes the following form:

<Configuration wstype=’UserForm’ ...
   <Extension>
     <Form noDefaultButtons=’true’>
  ...
  <Properties>

To include disabled resource accounts in the list of displayed accounts, remove the disabled attribute condition from the list.

</Property>
<Property name=’Exclude’>
  <list>
    <new class=’com.waveset.object.AttributeCondition’>
       <s>disabled</s>
       <s>equals</s>
    </new>
  </list>
 </Property>
 </Properties>
 ...
</Form>
</Extension>
</Configuration>

Valid View Attributes

The list of valid attribute names are those exposed by the views that are associated with each Form listed above for each instance of a currentResourceAccounts object. Valid attributes include:

accountDisplayName (string)
accountId (string)
directlyAssigned (true/false)
disabled (yes/no)
exists (yes/no)
id (string)
lastPasswordUpdate (string)
resource (string)
selected (true/false)
type (string)
userPwdRequired (yes/no)

Example: Excluding an LDAP Resource Type from a List of Resource Accounts

To exclude from the list of any given form all resource accounts of type LDAP that are not directly assigned, set the Exclude property as follows:

<Property name=’Exclude’>
 <list>
    <new class=’com.waveset.object.AttributeCondition’>
       <s>type</s>
       <s>equals</s>
       <s>LDAP</s>
       <s>LDAP</s>
    </new>
    <new class=’com.waveset.object.AttributeCondition’>
       <s>directlyAssigned</s>
       <s>equals</s>
       <s>false</s>
    </new>
 </list>
</Property>

Calling a FormUtil Method from within the allowedValues Property

From within the allowedValues property, you can also call FormUtil methods that permit you to dynamically retrieve and process information from a resource external to Waveset, such as a database.

This example shows how to call a FormUtil method to populate a <Select> list. In the following example, the method is called from within the allowedValues property. The getOrganizationsWithPrefixes method (or any FormUtil method) is invoked from within an expression.

<Field name=’waveset.organization’>
   <Display class=’Select’>
      <Property name=’title’ value=’Organization’/>
      <Property name=’autoSelect’ value=’true’/>
      <Property name=’allowedValues’>
            <expression>
            <invoke class=’com.waveset.ui.FormUtil’
               name=’getOrganizationsWithPrefixes’>
               <ref>:display.session</ref>
            </invoke>
            </expression>
         </Property>
   </Display>
</Field>

XPRESS also supports the ability to invoke calls to Java methods from within a resource or ActiveSync adapter. The results of the calls can then be used to populate multiselection or select lists. For information on invoking methods from an expression, see Chapter 5, XPRESS Language

Creating a Label Field

Labels are useful components for displaying the value of a read-only field. Properties of the <Label> component permit you to define the display characteristics of the label, including color, value (string), and font style.

<Field>
   <Display class=’Label’>
      <Property name=’text’ value=’Primary Corporate LDAP
         Server’/>
   </Display>
</Field>

The value attribute is always a string.