12.1 Creating Custom HTML Pages |
|
12.1 Creating Custom HTML Pages |
|
Viewpoint is a highly customizable application that can be modified to suit your organization's needs.You can add and modify your own custom HTML pages to Viewpoint. These custom pages utilize Viewpoint’s Queue and Summary pages. The pages themselves are created outside of Viewpoint, and are added to the Viewpoint directory structure.
Custom HTML pages should be placed in the /webapps/moab directory in Tomcat. This folder contains the following directories (and possibly some others):
IMPORTANT: You should create your own custom directory that is a symbolic link to a folder somewhere on the file system outside of the $TOMCAT_HOME/webapps directory, such as $TOMCAT_HOME/webapps/moab/custom. You will need to create the /custom directory. Doing so ensures that future application updates do not overwrite your custom pages, files, libraries, images, or scripts.
After a file has been placed in the root Web file system, that file can then be accessed using the "Local" plugin. This Viewpoint plugin requires the "page" parameter to be set to the page you wish to display. For example:
{root}/app#Local;page=path/to/page.html
If you would like to put a link in the navigation to a custom page, you would create a link in the navigation section in core.xml that uses the 'Local' page and has a parameter called 'page' that would be the url to the custom file. For example, if you wanted to show a page that was located in $TOMCAT_HOME/webapps/moab/custom/create_vc.html, you would use the following:
<link href='page://Local;page=custom/create_vc.html' label='Create Environment' />
When the client requests the page, all parameters except the "page" parameter are passed to the HTTP GET request for that page. Therefore, links to the Java Web application LocalFilePresenter may contain many parameters which are not used by Viewpoint, but may be consumed via your script.
For example, the administrator creates the following link in the core.xml:
<link href='page://Local;page=custom/perform_action;request=cloud;role=creator' label='Create Environment' />
When Viewpoint gets this request, it will request this page and pass in the url all the parameters requested. If this was done on a browser's address bar, it would look like this:
custom/perform_action?request=cloud&role=creator
This follows the standard for parameter passing using URLs.
Included in Viewpoint's /js directory are various Javascript libraries that your custom pages may use. You may wish to add other libraries your pages need; if you add libraries, they should be added outside the $TOMCAT_HOME/webapps directory so they are not overwritten on upgrade. Already included with Viewpoint are JQuery 1.5 (with various plugins for validation, tables, and UI components), and fusioncharts (used for showing graphics on the dashboard). There is also a utilities.js file that contains some helper functions that are useful for any page.
In addition to the .js files, Viewpoint will export top-level Javascript methods that may be used by your class. This is done using the DOM's 'top' object and calling the method.
This method is used to set both page's header title, as well as the header string at the top of your page, below the navigation. If the page does not specify the page title, the title will be the URL of the requested page. This method may be called at any time.
This method is used to set the icon located to the left of the header string at the top of your page, below the navigation. The first parameter is the url of the image to display. The boolean parameter specifies if the image exists on the default /images directory, and therefore the path does not need to be pre-pended to that directory. If the page does not specify an icon title, the icon defaults to an image of a world. This method may be called at any time.
top.setIcon('request-environment64.png, true) - Set the icon to "request-environment64.png" that already exists in the /images directory
top.setIcon('custom/images/my_cool_image.png', false) - Set the icon where the icon exists in a custom directory
This method will hide the header area (also known as the context area) that displays the title and icon on the top of the custom page. Setting the icon or page title value after calling this method will make the header area visible again.
This method is used to change the URL of the top-level object to an internal, Viewpoint place. It is helpful to use this method since the custom page is shown in a frame, which does not handle history. Typically, any change from one page to another within Viewpoint should use this method instead of using "a href" links.
In order to handle functionality across all browsers, you should always use changePlace() instead of target="_top"
top.changePlace("Local;page=html/create_vc_final.html;queue=vc;showTable=true");
Or when used as a link:
<a href="#Local;page=custom/myPage" onclick="top.changePlace('Local;page=custom/myPage')">Go Home</a>
This method takes in a string "type" that must be one of the following status levels: success, warning, loading or error. It also receives the text that you wish to have displayed. The color of the background of the text that you wish to be displayed will be set in accordance with the status level. The status levels display briefly on the top center of the Viewpoint screen.
Viewpoint's server side scripts will return a 401 if your request has not been authenticated with Viewpoint's security. This may happen for various reasons, the most common of which is trying to access a resource without logging in first, but may also happen if your session has expired. When the client receives this error, it is helpful to redirect users to the appropriate login page, which is why the Javascript API includes this helper method. When this method is called, a status message appears informing the user they are being redirected to the login page. After a short delay, the browser is automatically redirected to the appropriate page.
Example:
if (status == 401)
top.reauthorize();
This method will show a confirm dialog box with a header you define, a message you define, and two buttons at the bottom: "Yes" and "No". The first parameter to the method is a header string. Typically, the header is a short sentence describing the action and the message contains more detailed information about what will happen if the user clicks on "Yes". The third parameter is a Javascript function that is called when the user confirms the choice.
Example:
var fnOnConfirm = function() {...}
top.showGWTConfirmDialog("Delete All Environments?","This will remove all environments on the system. Are you sure you want to do this?",fnOnConfirm);
In order to utilize 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. See the next section for more details about creating a queue or utilizing an existing queue.
In order to use the Viewpoint queue system, any local page can use this method to specify the ID of a queue for that page. When a page uses Viewpoint's queue, two major changes happen on the page:
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.
This method accepts 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:
The "display" child object contains two child objects:
Example:
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);
This method will return a list of all items in the queue, as well as their quantities. It will return 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.
This method will 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)
In addition to the various methods described above, the Viewpoint queue framework also allows the user to view a table with the queue item details in a nice list format. This cannot be done via a Javascript method, but instead requires a URL change with the parameter "showTable" set to "true".
If you would like a button that takes the user to the request table page, here is the recommended action for that button (or link) action:
top.changePlace("Local;page=custom/your_form;queue=vc;showTable=true");