Using the Viewpoint queue

3.5 Using the Viewpoint queue

In order to use Viewpoint's built-in queue system, a page may call the setQueue JavaScript method or specify a queue URL parameter when querying for the page. Each queue must have a unique ID, and pages that share a queue should share this ID.

When the page uses Viewpoint's queue, two major changes happen:

The layout of the page changes to allow for a summary panel to be displayed on the right-hand side outside of the iframe.

Various other JavaScript functions are available to interact with the queue. Each queue has a unique ID associated with it to allow for each page (or set of pages) to interact with its own queue. This configuration will allow each queue page or set of pages to operate independently. At any given moment, the user may have many queue objects in memory, but only the queue the page deals with will be shown at a time. As of Viewpoint 6.1, the queue is stored in the browser cache on the local user's machine, but it disappears after the user navigates away from Viewpoint.

To utilize Viewpoint's queue

Use the setQueue(string) method to specify the ID of a queue for the page.

Use the addQueueItem(JavaScript) method to accept a JavaScript object that will be parsed and added to Viewpoint's queue for that object. The JavaScript object (JSO) should have three child objects:

Object	Description
display	Defines how the queue items should be displayed and contains two child objects: summary – Any string that will be interpreted as HTML to be displayed in the queue summary panel displayed on each form page. This should be a shorted, summary view of the item. description – Any string that will be interpreted as HTML to be displayed in the queue table that can (optionally) be displayed on the last page of the request. This contains more detailed information about the queue item.
>values	Contains a mapping of key, value pairs for the data stored on a single queue item.
qty	(Optional) Since each item in the queue may have an associated quantity, this attribute defines the quantity for this queue item. If not specified, the default value of 1 is used.

Object

Description

display

Defines how the queue items should be displayed and contains two child objects:

summary – Any string that will be interpreted as HTML to be displayed in the queue summary panel displayed on each form page. This should be a shorted, summary view of the item.
description – Any string that will be interpreted as HTML to be displayed in the queue table that can (optionally) be displayed on the last page of the request. This contains more detailed information about the queue item.

>values

Contains a mapping of key, value pairs for the data stored on a single queue item.

qty

(Optional) Since each item in the queue may have an associated quantity, this attribute defines the quantity for this queue item. If not specified, the default value of 1 is used.

var display = new Object();

display.description = "Image: " + image + "

vCPU: " + procs + "

RAM: " + mem + " GB

Disk: " + disk + " GB";

display.summary = image + ": " + procs + " vCPU, " + mem + " GB RAM, " + disk + " GB HD";

var myObject = new Object();

myObject.values = {

"image" : image,

"procs" : procs,

"mem" : mem,

"disk" : disk

};

myObject.display = display;

top.addQueueItem(myObject);

Use the getQueueItems() method to return a list of all items in the queue, as well as their quantities. It returns a JavaScript array, where each item in the array follows the same syntax and structure explained above.

This method is necessary since the Viewpoint framework allows users to remove items and update quantities outside of the form page. Therefore it is recommended to let Viewpoint keep track of the queue completely, and your page should only query for the information when it is ready to perform the action.

Use the clearQueue() method to remove all the items from Viewpoint's queue. No URL changes are made. Typically, this method should also take the user back to the first page of the form (if there are multiple pages). Therefore it is typically a good idea to use a changePlace request with this method (unless there is only a single page that makes up the view)

Show the queue table by making a URL change with the showTable parameter set to "true".

top.changePlace("Local;page=custom/your_form;queue=vc;showTable=true");

The buttons takes the user to the request table page.