Field Display Properties (Oracle Waveset 8.1.1 Deployment Reference)

Oracle Waveset 8.1.1 Deployment Reference

Field Display Properties

The Display element is common to all visible form fields. Display elements contain Property elements that define the characteristics of the field rendered by the browser. By defining a Display element for a form, it will be visible on the screen unless there is a Disable element in the field that evaluates to true. There can be conditions in which the form is displayed until another field or value is set and when the form recalculates the field can become hidden from the screen. See the section titled Disabling Fields.

Display

Describes class and properties of the visible field. This element specifies a component class to instantiate and a set of property values to assign to the instance.

<Display class=’Text’>
   <Property name=’size’ value=’20’/>
   <Property name=’maxLength’ value=’100’/>
</Display>

The class attribute of the Display element must be the name of a Component class. By default, these classes are expected to reside in the com.waveset.ui.util.html package and include Applet, Button, and DatePicker among others. A list of all the default classes and their descriptions can be found in the Base Component Class section of Chapter 7, HTML Display Components To reference a class that is not in this package, you must use a fully qualified class name for the class attribute. All classes described in this document are in the default package and do not require qualified names.

Property

Occurs within the Display element. The property value defines the names and values of properties that are to be assigned to the component. The property name is always specified with the name attribute.

Specifying Property Values for a Display Element

You can specify the Property value for a Display element through the use of:

a value attribute
an XML Object language
an expression to specify a value

For most property values, you can use the value attribute and let the system coerce the value to the appropriate type.

Use of the value Attribute

The most common way of specifying the property value is with the value attribute. The value of the value attribute is treated as a string, but if necessary, the system will coerce it to the data type desired by the component. In the previous example, the property size is set to the integer value 20, and the property maxLength is set to the integer value 100.

The following example creates a field that uses SimpleTable to organize several subfields. Within XML forms, the most common Container components used are SimpleTable and ButtonRow.

Example 2–6 Field that Uses the SimpleTable Element

<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>

Within the Display element are zero or more Property elements. These define the names and values of properties that are assigned to the component. The Property name is always specified with the name attribute. The property value is most specified with the value attribute. The value of the value attribute treated as a string, but if necessary it will be coerced to the data type desired by the component.

Use of the XML Object Language

You can also specify property values using the XML Objects language. This approach is useful primarily when specifying list values. This language provides a syntax for describing several standard Java objects as well as other objects defined by Waveset.

The more common Java XML objects include:

List
Map
MapEntry
String
Integer
Boolean
Object

When you use the XML Object syntax to specify property values, an element is placed inside the Property element. For more information on the XML Object language, see Chapter 6, XML Object Language.

Example 2–7 Property Element

<Property name=’size’>
   <Integer>10</Integer>
</Property>

<Property name=’title’>
   <String>New Password</String>
</Property>

<Property name=’leftLabel’>
   <Boolean>true</Boolean>
</Property>

<Property name=’allowedValues’>
   <List>
      <String>Texas</String>
      <String>Iowa</String>
      <String>Berkshire</String>
   </List>
</Property>

All properties that expect list values recognize the List element. Most attributes, in addition, recognize the comma list syntax for specifying lists.

Use of an Expression to Calculate the Value

You can also specify a Property value through an expression. This allows a value to be calculated at runtime, possibly combining fixed literal values with variable values defined by the page processor. Example:

Example 2–8 Property Value

<Property name=’title’>
   <concat>
      <s>Welcome </s>
      <ref>waveset.accountId</ref>
      <s>, select one of the following options.</s>
   </concat>
</Property>

In the preceding example, waveset.accountId is a reference to a variable. When the system generates the HTML for this component, the page processing system supplies the value for the waveset.accountId variable. The names of the variables that can be referenced are defined by the page processor. In most cases, these are defined by a view that is used with the XML form. Form designers must be aware of the view with which the form will be used and only reference attributes defined by that view.

Disable Element

Calculates a Boolean value. If true, the field and all its nested fields will be ignored during current form processing.

Do not create potentially long-running activities in Disable elements. These expressions run each time the form is recalculated. Instead, use a different form element that will not run as frequently perform this calculation.

Note –

The display.session and display.subject variables are not available to Disable form elements.

Example

This example illustrates a field definition that uses an expression within the <Disable> element to control the visibility of the field. accountInfo.typeNames is used to find the type of all resources that a user is assigned to. The type returned is a list of all the user’s resource types. If the list of returned type names contains Solaris, then this field is displayed on the screen. Otherwise, this field is disabled.

<Field name=’HomeDirectory’ prompt=’Home Directory’>
   <Display class=’Text’/>
      <Disable>
         <not>
            <contains>
               <ref>accountInfo.typeNames</ref>
               <s>Solaris</s>
            </contains>
          </not>
   </Disable>
</Field>

Disable elements are typically used to check values of other fields on the form. Often the other field being referenced is calculated based on other input fields.

<Field name=’special value subfield’>
   <Comment>Show only when otherField has the value ’special value’</Comment>
   <Disable>
      <neq>
         <ref>otherField</ref>
         <s>special value</s>
      </neq>
   </Disable>
</Field>
<Field name=’account correlation rule’>
   <Comment>If synchronization on a resource supports an account correlation rule,
allow one to be selected, otherwise don’t show the field.  If a process rule has been
selected, then a correlation rule won’t be run, so don’t show the field.</Comment>
   <Disable>
      <or>
         <isnull>
            <ref>resourceAttributes[correlationRule].displayName</ref>
         </isnull>
         <notnull>
            <ref>resourceAttributes[processRule].value</ref>
          </notnull>
      </or>
         </Disable>
   </Field
...
</Field>>

Default Element

Calculates a value to be used as the value of this field, but only if the field does not already have a non-null value. Default is essentially the same as Derivation, except that the value applies only if the current value is non-null. Default expressions are calculated when:

the form is first loaded
data is retrieved from one or more resources
the form is recalculated or saved until the field value is non-null.

Example

This example shows a field definition that uses string manipulation expressions to return a default account ID composed of the first initial of the first name plus the user’s last name.

<Field name=’waveset.accountId’>
   <Display class=’Text’>
      <Property name=’title’ value=’AccountID’/>
   </Display>
   <Default>
      <concat>
         <substr>
            <ref>accounts[AD].firstname</ref>
               <i>0</i>
               <i>1</i>
            <ref>accounts[AD].lastname</ref>
         </substr>
      </concat>
   </Default>
</Field>

Derivation Element

Unconditionally calculates a value for the field. Whenever a Derivation expression is evaluated, the current field value is replaced.

Derivation expressions are calculated when the form is first loaded or data is returned from one or more resources

The following example shows a field definition that uses conditional logic to map one set of values into another set. When this field is processed, the expression in the <Derivation> element is evaluated to determine the descriptive value to be displayed for this field based on the location code returned from the resource.

<Field name=’location’>
   <Display class=’Text’>
      <Property name=’title’ value=’Location’/>
   </Display>
   <Derivation>
         <switch>
            <ref>accounts[Oracle].locCode</ref>
            <case>
               <s>AUS</s>
               <s>Austin</s>
            </case>
               <s>HOU</s>
               <s>Houston</s>
            </case>
            <case>
               <s>DAL</s>
               <s>Dallas</s>
            </case>
            <case default=’true’>
               <s>unknown</s>
            </case>
         </switch>
   </Derivation>
</Field>

Expansion Element

Unconditionally calculates a value for the field. It differs from Derivation in the time at which the expression is evaluated.

Expansion statements are calculated when:

the page is recalculated
the form is saved

The following example shows a field definition that uses conditional logic to convert the value derived for the location field in the previous example back into a three-letter abbreviation that will be stored on the Oracle resource. Notice the difference in the field names. The location field value is not saved on any resource. It is used to calculate another field.

<Field name=’accounts[Oracle].locCode’>
   <Expansion>
      <switch>
         <ref>location</ref>
         <case>
            <s>Austin</s>
            <s>AUS</s>
         </case>
         <case>
            <s>Houston</s>
            <s>HOU</s>
         </case>
         <case>
            <s>Dallas</s>
            <s>DAL</s>
         </case>
      </switch>
   </Expansion>
</Field>

Validation Element

Determines whether a value entered in a form is valid. Validation rules are evaluated whenever the form is submitted.

This example Validation rule checks to make sure that a user’s zip code is five digits.

<Validation>
   <cond>
      <and>
      <eq><length><ref>global.zipcode</ref></length>
            <i>5</i>
      </eq>
            <gt><ref>global.zipcode</ref><i>99999</i></gt>
      </and>
      <null/>
      <s>zip codes must be five digits long</s>
   </cond>
</Validation>

Editing and Container Fields

When the Display element appears with the Field element, it describes the component that will be used to render that field. There are two types of fields:

editing fields. These are associated with a particular value to modify.
container fields. These surround one or more fields.

Editing fields must have names and are always used with one of the editing components such as Text or Checkbox.

Example Editing Field

<Field name=’waveset.email’>
   <Display class=’Text’>
      <Property title=’Email Address’/>
      <Property size=’60’/>
      <Property maxLength=’128’/>
   </Display>
 ...
</Field>

The name of an editing field is typically a path expression within a view that is being used with the form. In the preceding example, waveset.email refers to the email address associated with a user object in the Waveset repository.

A Container field may not have a name and is always used with one of the Container components, such as ButtonRow, SimpleTable, or EditForm.

One common type of container is the EditForm container, which builds an HTML table that contains titles in one column and components in another. These titles are defined in the title property and are rendered on the Waveset page associated with the form.