Other Form-Related Tasks (Oracle Waveset 8.1.1 Deployment Reference)

Oracle Waveset 8.1.1 Deployment Reference

Other Form-Related Tasks

Miscellaneous form-related tasks include:

Invoking the FormUtil methods
Inserting Javascript into a form
Testing whether a user or object exists
Inserting Alert Messages into XPRESS Forms

Invoking the FormUtil Methods

The FormUtil class is a collection of utility methods that you can call from XPRESS expressions with form objects. They can be used to populate lists of allowed values and validate input. The FormUtil methods are typically called to assist the definition of the allowed values in a list or field.

<invoke class = ’com.waveset.ui.FormUtil’
   name = ’listResourceObjects’>
</invoke>

where the name field identifies the name of the method.

For examples on using these methods within forms, see the section titled Using Hidden Components.

Inserting JavaScript into a Form

To insert pre-formatted Javascript into a form, use the <script> component as follows:

<Field>
  <Expansion>
    <script>
     ............

Testing if an Object or User Exists

You might want to check whether an object exists before performing an action. For example, you could look to see if a user name exists in Waveset before creating a new user, or validate whether a manager name entered in a field is valid.

To test if an object exists, use the testObject method. To specify an object type when using this method, use the object types listed in the section titled Retrieving a List of Accessible Object Types. In the following example, the user type is identified as <s>User</s>. The second string gives the value of the object type (in this example, jdoe).

Example:

<invoke name=’testObject’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
   <s>User:</s>
   <s>jdoe</s>
</invoke>

The testObject method returns true on successful find of an object. Otherwise, this method returns null.

To test if a user exists, use the testUser method. The <s> element identifies the name of the user object to find. Example:

<invoke name=’testUser’ class=’com.waveset.ui.FormUtil’>
   <ref>:display.session</ref>
   <s>jdoe</s>
</invoke>

This method returns true on successful find. Otherwise, this method returns null.

Inserting Alert Messages into XPRESS Forms

You can insert WARNING), error (ERROR), or informational (OK) alert messages into an XPRESS form.

Note –

Although this example illustrates how to insert a Warning ErrorMessage object into a form, you can assign a different severity level.

To Insert an Alert Message

Use the Identity Manager IDE to open the form to which you want to add the warning.

Add the <Property name=’messages’> to the main EditForm or HtmlPage display class.

Add the <defvar name=’msgList’> code block from the following sample code.

Substitute the message key that identifies the message text to be displayed in the Alert box in the code sample string:

<message name=’UI_USER_REQUESTS_ACCOUNTID_NOT_FOUND_ALERT_VALUE >

Save and close the file.

<Display class=’EditForm’>
   <Property name=’componentTableWidth’ value=’100%’/>
   <Property name=’rowPolarity’ value=’false’/>
   <Property name=’requiredMarkerLocation’ value=’left’/>
   <Property name=’messages’>
     <ref>msgList</ref>
   </Property>
</Display>
<defvar name=’msgList’>
  <cond>
    <and>
      <notnull>
        <ref>username</ref>
      </notnull>
      <isnull>
        <ref>userview</ref>
      </isnull>
    </and>
    <list>
      <new class=’com.waveset.msgcat.ErrorMessage’>
        <invoke class=’com.waveset.msgcat.Severity’ name=’fromString’>
           <s>warning</s>
        </invoke>
        <message name=’UI_USER_REQUESTS_ACCOUNTID_NOT_FOUND_ALERT_VALUE’>
          <ref>username</ref>
        </message>
      </new>
    </list>
  </cond>
</defvar>

To display a severity level other than warning, replace the <s>warning</s> in the preceding example with either of the these two values:

error -- Causes Waveset to render an InlineAlert with a red “error” icon.
ok -- Results in an InlineAlert with a blue informational icon for messages that can indicate either success or another non-critical message.

Waveset renders this as an InlineAlert with a warning icon

<invoke class=’com.waveset.msgcat.Severity’ name=’fromString’>
<s>warning</s>
</invoke>

where warning can also be error or ok.

Wizard and Tabbed Forms

Both wizard and tabbed forms are mechanisms for structuring unwieldy, single-page forms into more easily managed, multiple-paned forms. Both contain separators between logical sections, or pages. These page separators can be tabs located at the top of the form -- like the tabbed user form -- or a wizard form, which guide the user through the pages using the next/back navigation buttons.

See Tabbed User Form in this chapter for the XML version of the default Tabbed User Form.

What Is a Wizard Form?

Wizard forms can be a convenient alternative to launching multiple forms from a task when:

Transition logic between pages is simple
Privileged system calls between pages are required

Wizard forms contain the two rows of buttons described below.

Table 2–18 First Row of Buttons


Row of buttons	Description
top row	Next and Back buttons to traverse through the form panes
second row	Contains the standard user form buttons listed in the following table. You can control the second row by setting `noDefaultButtons` option to true and implementing your own buttons.

This second row of button can vary as follows:

Table 2–19 Second Row of Buttons


Wizard page	Default buttons
first page	Next, Cancel
intermediate pages	Prev, Next, Cancel
last page	Prev, Ok, Cancel

Implementing a Wizard Form

Wizard form syntax closely resembles tabbed user form structure. ,

To Create a Wizard Form

Assign the WizardPanel display class to the top-level container (rather than TabbedPanel).

Set the noCancel property to true.

Define one or more EditForm fields that contain the pages of the wizard.

The following example provides comments for guidance purposes:

<Form>
   <Display class="HtmlPage"/> ----- If not set, causes indentation and color problems
   <Field name=’MainTabs’> -- Name of the top container that wraps the tab pages
      <Display class=’TabPanel’/> -- Display class for the top container: 
                                     either TabPanel or WizardPanel
   <Field name=’Identity’> -- Label of the Tab
      <Display class=’EditForm’> -- Each “page” must be an Edit Form
         <Property name=’helpKey’ value=’Identity and Password Fields’/>
      </Display>
   <Field name=’waveset.accountId’>
      <Display class=’Text’>
         <Property name=’title’ value=’_FM_ACCOUNT_ID’/>
      </Display>
<Disable> <ref>waveset.id</ref> </Disable>

   </Field>
   </Field>

</Field>

Tips and Workarounds

Validation errors appear on the last page that the user was on rather than the page on which the attribute appears. To work around this, include information in the validation message to assist the user in navigating back to the correct page.
For complex wizards, give users some visual clue as to where they are in the process. Using labels or section heads at the top of every page that displays text similar to Page 1.
Avoid using conditional navigation in wizard forms. If you must implement it, use Disable expressions for each of the immediate children of the WizardPanel. For example:
```
<Field name=’Page2’>
   <Display class=’EditForm’/>
   <Disable><neq><ref>showPage2</ref><s>true</s></neq></Disable>
...
</Field>
```
Put fields or buttons on previous pages that cause their gating variables to be set. Disabled pages are automatically removed from transition logic.