Perspective Subsystem Page Flow

This page discusses how perspective pages from perspective webapps outside rhq.ear will be embedded in the core GUI, and how the perspective webapp will notify the RHQ Server that a page flow is complete.

Extension Point URLs and Their Targets

Extension points typically have a URL associated with them. This URL could be either a link to some other core UI page, e.g.:

/Dashboard.do

, a link to a page in a co-located perspective WAR, e.g.:

/rhel-perspective/provision-server.xhtml

, or a link to some arbitrary external page, which may or may not be a Java-based webapp, e.g.:

http://foobar.com/do-something

The URL would usually (always?) displayed in a portion of the page, rather than taking over the entire page. The portion of the page that the URL would target would vary depending on the type of extension point, e.g.:

For tabs or sub-tabs, clicking on the tab would always cause the URL's content to be displayed in the area below the tab bar on the right side of the page.
For resource or group tasks, clicking on the task link would typically display the URL's content in the area below the bread crumbs and summary properties on the right side of the page.
For global tasks, clicking on the task link would typically display the URL's content in the area below the menu bar. That is, it would take up almost the entire page, but the menu bar would remain to maintain continuity in the GUI.

We may also allow certain extension points to take over the entire page, though I currently am in favor of always maintaining the menu bar for the sake of continuity.

Embedding the Content of Extension Point URLs

So the obvious question is how do we embed the content of an arbitrary URL within some portion of a core GUI page? Based on my research so far, I think there are two options:

the HTML <object> tag, e.g.:

<object data="/foo-perspective"
        style="border: 0; margin: 5px; width: 100%; min-height: 100%; height: auto !important; height: 100%;">
   ERROR: Perspective-defined page could not be embedded. Please make sure you're using IE6+ or FF2+.
</object>

the HTML <iframe> tag, e.g.:

<iframe src="/foo-perspective"
        style="border: 0; margin: 5px; width: 100%; min-height: 100%; height: auto !important; height: 100%;">
   ERROR: Perspective-defined page could not be embedded. Please make sure you're using IE6+ or FF2+.
</iframe>

For an overview of these two tags and their differences, see:

http://www.w3.org/TR/REC-html40/struct/objects.html#embedded-documents

And for more details, see the following links:

It's still up in the air which one to use. Here are some potential advantages of each:

Advantages of object

We want it to be as transparent as possible that the embedded content was retrieved from an external URL, so ideally I don't think we want the following features of iframes:

The <iframe> element may be a target frame (see the section on specifying target frame information for details) and may be "selected" by a user agent as the focus for printing, viewing HTML source, etc.
User agents may render selected frames elements in ways that distinguish them from unselected frames (e.g., by drawing a border around the selected frame).

<iframe> is deprecated in XHTML 1.0 transitional, while <object> is not.

Advantages of iframe

iframes are meant to handle external HTML pages (complete with css and javascript). So using iframes instead of <object> is semantically correct.
iframes place many restrictions on the pages loaded inside them that are essential for cross-domain security. I can't say the same about <object>.
<object> is tricky cross-browser implementation; an <iframe> is so much more reliable.

Accessing the Embedded Page via JavaScript

Whichever element is used, some JavaScript/DOM trickery will be required to set the height correctly on the object or iframe element, so it doesn't always get rendered with its own vertical scrollbar. By default, this trickery is only permitted when the perspective URL is located on the RHQ Server (to prevent cross-site scripting attacks). However, this can be worked around by setting the document.domain property to the same value in both the outer and inner pages (see http://www.nczonline.net/blog/2009/09/15/iframes-onload-and-documentdomain/).

Navigation Back to Core GUI From Embedded Perspective Page

After the form submit button has been clicked within an embedded perspective page, we need a mechanism for the perspective to report the outcome back to the RHQ Server, and a way for the RHQ Server to redirect the GUI to a new page, whose URL would depend on the outcome reported by the perspective. This URL could be some page in the core GUI (e.g. /Dashboard.do) or it could be another perspective page (e.g. /rhel-perspective/provision-server-step2.xhtml) in the case of a multi-page perspective workflow (i.e. a wizard).

These outcome-based page flows could be defined in the perspective descriptor, e.g.:

   <resourceTask name="restart-app-server"
                 displayName="Restart this Apppliation Server"
                 href="/jboss-perspective/restart-app-server.seam"
                 target="body" category="Provision">
      <!-- one or more Resource types that this task should be displayed for -->
      <resourceType plugin="JBossAS" name="JBossAS Server"/>
      <resourceType plugin="JBossAS5" name="JBossAS Server"/>
      <outcome name="success" redirectUrl="/rhq/resource/summary/overview.xhtml" target="fullPage"/>
      <outcome name="failure" redirectUrl="/jboss-perspective/restart-app-server.seam" target="body"/>
   </resourceTask>

Then there would be a method provided by the PerspecticeManager remote API:

void advancePageFlow(String perspectiveContextId, String outcome);

whose impl would look something like:

String redirectUrl = getRedirectUrl(outcome);
org.jboss.seam.faces.Redirect redirect = org.jboss.seam.faces.Redirect.instance();
redirect.setViewId(redirectUrl)
redirect.execute();

The outcome abstraction could also be removed, but this would have the disadvantage of the redirect URLs being hard-coded in the perspective WARs rather than being defined in the perspective descriptor. That is, there would be no outcome elements in the descriptor, and the remote API method would look like this instead:

void advancePageFlow(String perspectiveContextId, String redirectUrl);

Design-Perspectives-PageFlow