Moab Viewpoint
Home Up Previous Next
Configuring the Pages Element

Configuring the Pages Element

The <pages> element allows you to define the layout of the user interface. The layout can be either static or dynamic, which you must specify via the <pages> element ui-type attribute by assigning a value of either "static" or "dynamic". The <pages> element can have one or more <page> child elements.

To create a page, add a child <page> element in the parent <pages> element. Every page requires a unique identifier and any page can be the first page in the user interface. There must be exactly one page that has the first attribute set to "true".

The <page> element has four child elements:

  • <description> - An optional element describing the page.
  • <sections> - A required element containing a list of sections to display on the page.
  • <navigation> - An element describing which page to load next. This child element is required if there is more than one <page> element. The <navigation> element is only used with a dynamic layout.
  • <validation> - An optional element that determines if the values on the page are valid.

You can optionally hide a page from a user by requiring permissions to view it. Use the permission attribute to specify what permission is needed. If the user does not have the specified permission, the page is not displayed.

    <pages ui-type="dynamic">
      <page id="page1" first="true"></page>
      <page id="page2"></page>
      <page id="page3" permission="advancedvpc"></page>
     </pages>
...

In the preceding example the third page is viewable only by users with the "advancedvpc" permission. If no permission is specified, anyone can view the page.

<description>

Use the optional <description> element to describe the page. The description is not displayed to the user. The following is a simple example of how you might use the <description> element:

    <pages>
      <page id="page1" first="true">
        <description>First page. Shows the environment options.</description>
        ...
       </page>
      <page id="page2"></page>
      <page id="page3"></page>
     </pages>
...

<sections>

Every page must have a <sections> element. The <sections> element has one or more child <section> elements. Each section contains a description visible to the user and an ordered list of components that are defined in the <components> element. Use the following child elements of the <section> element to supply a section description and a components list:

  • <description> - One <description> element is required for each <section> element. The description is displayed to the user as the title for the section on the GUI.
  • <component> - One or more <component> elements are required for each <section> element. The components are the choices or options presented to the user.

Each <section> element has a unique identifier specified by the id attribute. The <component> elements in a section also support the permission attribute. The value can be any permission. If set, only users with the specific permission can view the page.

The following example depicts a page with one section that has three components.

<page>
  <sections>
    <section id="s1" permission="advancedvpc">
      <description>Environment Options</description>
      <component id="starttime" order="1" />
      <component id="duration" order="2" />
      <component id="securityZone" order="3" permission="advanced-user-2" />
     </section>
   </sections>
</page>
...

In the preceding example, the "s1" section is viewable only by users with the "advancedvpc" permission. Only those with the "advanced-user-2" permission may set the security zone component. If no permission is specified, anyone can view or use the section or component.

Page Layouts

There are two types of page layouts supported in Viewpoint:

  • Dynamic Layout - This is where the user is presented with a sequence of pages that lead the user through a series of well-defined steps commonly referred to as a wizard layout. The next page in the layout may be dependent on the inputs on previous pages. This layout allows for dynamic page creation and navigation branching (described in details that follow).
  • Static Layout - This is where the user is shown all pages at once and can skip to any page at a given time. There is no navigation branching in this layout.

Dynamic Layout

A dynamic layout is useful when dealing with complex tasks or when it is helpful to guide users through an unfamiliar process. With a dynamic layout, it is possible to use navigation branching, which means what appears on, and the ability to proceed to, the next page depends on input to previous pages and the values in the current page. More information on configuring navigation is in the <navigation> section.

To specify a dynamic layout, use the attribute ui-type and specify the value dynamic in the <pages> element.

When using a dynamic layout, the <validation> element can be defined for each page, and should therefore be a child of the <page> element. For more details about validation, see the <validation> section.

<navigation>

Navigation is specified by the <navigation> element. If there is only one page in the GUI, the <navigation> element is not required. The <navigation> element is unrecognized if the <pages> element includes the ui-type attribute set to dynamic.

To specify the next page, add the <next-page> child element to the <navigation> parent element. The <next-page> element must specify the set-next attribute. This attribute contains the ID of the next page to show. In the following example, when the user clicks Next, the flow goes from the first page ("page1") to the next page ("page2").

<pages>
  <page id="page1" first="true">
    <description>First page. Shows the environment options.</description>
      <navigation>
        <next-page set-next="page2" />
      </navigation>
    ...
  </page>
  <page id="page2">...</page>
  <page id="page3">...</page>
</pages>
...

The destination page can be dependent on the values the user selects on the current page. This allows you to configure a branching mechanism so page flow can be customized. For example, when clicking Next with 'value A' selected, 'page A' is displayed. If 'value B' is selected, 'page B' is displayed. That is, the next displayed page can be dependent on a condition.

To set up the conditional branching, a <next-page> element can have child <rule> element that, if evaluated to true, directs users to the specified page. This rule is a boolean decider. If no rule is specified, the default next page is what is specified in the set-next attribute. If there are multiple <next-page> elements with rules, the user is directed to the first one that is evaluated to true. It is recommended to create requirements that are mutually exclusive, so as to avoid confusion of which page is next in the navigation flow. A <next-page> element without requirements is considered to be the default next page. The GUI redirects to the default next page only if none of the other <next-page> elements have requirements that evaluate to true. It is recommended to have exactly one default next page (in other words, one <next-page> element with no <rule>).

In the example below, a component exists on the Provision VPC page asking if the user has an account or if they are new. If the user selects the 'New user' value for the "newOrExistingUser" component, they are directed to the "newUser" page. If the user indicates they have an existing account, the requirement operation evaluates to false and the following <next-page> element ("existingUserPage", in this example) is evaluated to true . The default value is "newUserPage" and is placed only as a safeguard to make sure the next page is specified.

<page id="firstPage">
  <description>First Page asks if they are new or not</description>
  <sections>...</sections>
  <navigation>
    <next-page set-next="newUserPage">
      <rule comparison="equals">
        <first>
          <component id="newOrExistingUser" />
        </first>
        <second>
          <value>New user</value>
        </second>
      </rule>
    </next-page>
    <next-page set-next="existingUserPage" />
    <next-page set-next="newUserPage" />
  </navigation>
</page>
...

Static Layout

A static layout is recommended for more advanced users or users that may only need to change a few components when submitting the form. In this layout, the user is presented with all pages at the same time. Users are shown the list of pages on the left side (the context area) and can skip to any page at any time.

When using a static layout, the <validation> element is defined for all pages, and should therefore be a child of the <components> element. See the validation section for more information.

To specify a static layout, use the attribute ui-type and specify the value static in the <pages> element.

By default with static layouts, there is a context area on the left side of the form that shows the currently selected tab. You can make this context area disappear by setting the attribute hide-context to true in the pages element.

 <pages ui-type="static" hide-context="true">

<validation>

With the <validation> element, you can set rules to check if the inputs on a page are valid. A user cannot proceed to the next page until inputs are valid values. After the user tries to proceed to the next page, the validation is checked and the response is fired. Once this occurs the validation is continuously checked on the page. As soon as the user enters a valid value, the warning messages go away and the Next button is re-enabled. This differs from the individual component validation which is constantly being checked as soon as the user starts entering data.

There are two types of checks to make sure a component is valid:

  • Checks against the value in the component itself.
  • Checks against the value in the component in relation to other components.

Typically, the first type of validation is taken care of during the creation of the GUI component. For example, the email address text box must contain @ or the input is invalid.

The second type is more complicated. These checks look at multiple components on the page (or even other pages) and determine whether the values are correct altogether. For example, the start date of a reservation must be before, and the duration must not go past, September 30th. The user can input a start date of August 1st, but the duration cannot be more than 2 months.

To accomplish cross-component validation, you must specify a requirement and the associated response. In the <validation> element, create a child <requirement> and <response>. The <requirement> element must evaluate to false for the response to occur. The <response> element describes the behavior of the GUI when <requirement> evaluates to false.

A <response> element defines which components to invalidate and the corresponding error message. The <response> element has a child <message> element as well as any number of child <component> elements that get invalidated with the message.

In this example, validation is configured to prevent users from creating more than ten reservations of any type.

<validation>
  <requirement logical-operation="and">
    <rule comparison="lessthan">
      <first>
        <variable binary-operation="add">
          <first>
            <component id="linuxVMCount" />
          </first>
          <second>
            <component id="windowsVMCount" />
          </second>
        </variable>
      </first>
      <second>
        <value>10</value>
      </second>
    </rule>
  </requirement>
  <response>
    <message>You cannot create more than a total of 10 VMs</message>
    <component id="linuxVMCount" />
    <component id="windowsVMCount" />
  </response>
</validation>
...
Home Up Previous Next