Configuring the Queue Element

Many forms may have a queue, or a client-side request queue to store unsubmitted data. For example with create VPC, the request queue would contain a collection of reservations the user wishes to create. For submit job, the queue may contain a collection of jobs that will be submitted upon page submission. The following image is an example of how the queue might look in the create VPC page if the user wants two reservations in their desired VPC:

The queue element defines what data is stored in the queue and the interface for the request queue, which is the list of items generated when a user clicks Add To Request. A queue requires a name attribute, which is the text displayed at the top of the queue. The previous example was configured with the following XML as the top line:

<queue name="Your Current Request">

Queue Items

The parent <queue> element contains one or more child <queue-item> elements. For most requests, there will only be one queue item definition. However, if you want to support heterogeneous queue items, you may specify more than one item.

Heterogeneous Queue Items

Viewpoint supports multiple queue item configurations. For example, one queue item might contain a definition for a virtual machine, whereas a different queue item might contain a physical machine, and the data stored for each item might be completely different.

Each queue item may contain a child <condition> element to determine if the queue item should be added. The child <condition> element should be any Boolean value decider. Each time the user clicks Finish or Add To Queue, each queue item is evaluated to determine whether the item should be added to the list. The item is not added if either the condition evaluates to false or there is no data that is saved in the queue item.

    <queue name="Your Current VPC Request">
      <queueItem>
        <condition comparison="equals">
          <first>
            <component id = "vmtype" />
          </first>
          <second>local</second>
        </condition>

        <title required="false">
          <description>Description</description>
          <component id="sysdescription" />
        </title>

        <row order="1" required="true">
          <description>Procs:</description>
          <component id="procs" />
        </row>
        <!-- ... -->

        <requirement-data id="rsvRequirement">
          <component id="sysdescription" />
          <component id="vmtype" />
          <component id="procs" />
        </requirement-data>
      </queueItem>

      <queueItem>
        <condition comparison="equals">
          <first>
            <component id = "vmtype" />
          </first>
          <second>ec2</second>
        </condition>

        <title required="false">
          <description>Description</description>
          <component id="sysdescription" />
        </title>

        <row order="1" required="true">
          <description>Type:</description>
          <component id="ami" />
        </row>
        <row order="2" required="true">
          <description>key:</description>
          <component id="key_name" />
        </row>

        <requirement-data id="EC2Requirement">
          <component id="sysdescription" />
          <component id="vmtype" />
          <component id="ami" />
          <component id="key_name" />
        </requirement-data>
      </queueItem>

    </queue>

Configure a Queue Item's Appearance

To configure the way a queue item is displayed to the user, use these child elements:

• <title> - This element is the title for each item in the queue. There should be at most one such element. It is for user interface purposes only. The title is the first row on a queue item and its CSS may be configured differently. By default, the title is in bold text. This is an optional element.
• <row> - This element describes a single row for a single item in the queue. There may be zero or more of these elements defined.

Title and Row Element Structure

The <title> and <row> elements have the same underlying structure; they both require the following two child elements:

• <description> - This is the explanatory text that is displayed before the value.
• Any other element representing a string value decider.

All <row> elements have two required attributes:

• order - The order of the row item. This is the order which the indicated line is displayed on the page.
• required - If false, this row only displays if the value is not empty or zero.

Dynamic Rows

Rows may be dynamic, meaning that the exact number of rows is dependent on the components in the form. For example, if the user created a list of three items in a list editor, the corresponding dynamic row would actually add three rows to the queue item, one for each item in the list. Set up dynamic rows using the type and source attributes. The type attribute must be set to dynamic and the source is any component that contains a list of values (such as a list edit component).

In the following example, the second row in the queue item creates however many items are in the "storage-list" component:

<row order="2" type="dynamic" source="storage-list">
   <description>Storage:</description>
   <component id="storage-list" />
  </row>

The title is always the first item to be displayed in the queue, but if the values of both the description and value are empty nothing is shown. The <title> element itself is also optional.

CSS Styles

To customize the view for individual components (for example, italicizing the title while formatting row values with bold), change the CSS styles. The following CSS styles can be modified in the utility-hosting.css file:

• "ace-DynamicQueueItem-titleDescription" - The style applied to the title's description (assuming the description is not empty).
• "ace-DynamicQueueItem-titleValue" - The style applied to the title's value (assuming the value is not empty).
• "ace-DynamicQueueItem-rowDescription" - The style applied to a row's description (assuming the description is not empty).
• "ace-DynamicQueueItem-rowValue" - The style applied to a row's value (assuming the value is not empty).

Queue Data

For forms where there may be multiple requirements (such as the Create VPC page), you may specify what data gets saved for which requirements. A single queue item may contain data about one or more requirements. For details about the requirement specifications, see the administrator configuration for the page you are configuring.

Within the <queue-item> element is an optional child element called <requirement-data>. This element defines the data that is stored from each component each time the user adds a new item to the request queue. This should be a collection of components declared on the form. The data saved is not reflected in the user interface and is only used for computational purposes. If this element is not specified, the queue item will contain the data of all components on the form.

Typically, all components dealing with an individual queue item should be stored as part of the queue item's requirement data; such individual queue item components might include processor count, amount of memory, and so forth. Components that are global to the entire request (like the start time and duration for the Create VPC page), do not need to be stored in the <requirement-data> element.

In the following simple example, there is a single queue item that stores information about a single requirement. Please note that you can add more queue items and more requirement data specifications as necessary.

<queue name="Your Current VPC Request">
  <queue-item>
   <title>
    <description></description>
    <component id="os" />
   </title>
   <row order="1" required="true">
    <description>Procs:</description>
    <component id="procs" />
   </row>
   <row order="2" required="true">
    <description>RAM:</description>
    <component id="memory" />
   </row>
   <row order="3" required="false">
    <description>Storage (GB):</description>
    <component id="disk" />
   </row>
   <requirement-data id="rsvRequirement">
    <component id="os" />
    <component id="procs" />
    <component id="memory" />
    <component id="disk" />
   </requirement-data>
  </queue-item>
 </queue>

Do we really want to remove everything from here down?

The following describes key elements associated with <queue>:

• <component> - The specified value for the id attribute maps to a component defined in the <components> section.
• <row> - Determines which content associated with the component is displayed to the user and in what order it appears. The order attribute indicates the placement of the content in relation to other rows of content. Setting the required attribute to true forces the content to display; setting the attribute to false causes the content to appear only if a user selects the associated value. In the preceding image, Additional Storage (GB): 10 is an optional value that appears because the user requested additional storage.
• <description> - What appears in the user interface as a label representing the content associated with a given component.
• <requirement-data> - Maps what is represented in the user interface to values stored for each item in the queue. The stored data is later passed to Moab. For each item included in the queue, it is necessary to include a child <component> element with an id attribute defining the respective component.

The following is a sample of the <queue> section of the vpcs.xml file:

<queue>
	<queueItem>
		<title>
			<description></description>
			<component id="os" />
		</title>
		<row order="1" required="true">
			<description>Procs:</description>
			<component id="procs" />
		</row>
		<row order="2" required="true">
			<description>RAM:</description>
			<component id="memory" />
		</row>
		<row order="3" required="false">
			<description>Additional Storage (GB):</description>
			<component id="disk" />
		</row>
		<requirement-data id="vmRequirement">
			<component id="os" />
			<component id="procs" />
			<component id="memory" />
		</requirement-data>
		<requirement-data id="diskRequirement">
			<component id="disk" />
		</requirement-data>
	</queueItem>
</queue>