FENG-SHUI Architecture

Overview:	A description of the "FENG-SHUI" architecture for flexible branding, navigation, and look-and-feel, developed for the GPMS Portal
Author:	Rich Fozzard
Last Updated:

The Challenge

The GPMS Portal team was asked to support a high degree of flexibility in the user interface of its products. For example, we might need to have the same underlying Java code and XML vocabulary support different:

Service Provider organizations (e.g., Inflow or WeManage)
Service Consumer organizations (e.g., "abc.com", a company with a colocated web server).
Locales (e.g., English-speaking Canada vs. Flemish-speaking Belgium)
Document (page or request) types (e.g., a request for storage might need to look different from a contact management page)
Users with specific sets of privileges ("security roles")

To get an idea of the requirements, here is a sample page from the application:

Global Navigation stuff (Menus) here Look-and-feel unique to Organization (Service Provider or Service Consumer)
Navigation options filtered by Organization and Security Role

Local Navigation stuff (Menu Items) here

Welcome, Tom Cruise of EyesWideShut.com!

Look-and-feel unique to Organization (Service Provider or Service Consumer),
Navigation options filtered by Organization and Security Role

Creamy Center stuff here

Modify Storage

Branch	System	Service	Used	Allocated	Remaining
Boulder	Nicole1	Storage: 100/90	247 GB	GB	3 GB

Two Requests (as defined in the Use Case) are possible here: Expand Storage and Reduce Storage. Arguably, these two should be combined into a single Request: Change Storage Amount. A GUI supporting separate Expand and Reduce Requests would be awkward to users.

On this page, the central portion (containing a form to modify a consumer's storage allocation) is determined by the 'requestName' sent to the Request Handler. The peripheral portions of the page contain branding and navigation that is organization-specific and document-type-specific (logo, background color, etc.) The navigation options are filtered by the privileges assigned to the current user (sometimes referred to as the Actor).

The Solution

The solution we came up with is FENG-SHUI: a Flexible, Extensible, Next Generation, Scalable, Hierarchical User Interface. Okay okay, so the acronym is kind of hokey. But it's the architecture that counts here, so let's roll the video tape!

A conceptual model

Conceptually, pages in Portal can be understood as nested tables (which is what they are in HTML) with the following layout:

  __________________________________________
 |                                          |         
 |                     outer top            |         
 |__________________________________________|
 |        |                                 |        
 |        |                                 |        
 |        |                                 |        
 |        |                                 |        
 |        |                                 |        
 |        |                                 |      
 | outer  |          CONTENT AREA (Body)    | 
 | left   |                                 | 
 |        |              a.k.a              |        
 |        |            the creamy           |        
 |        |              center             |        
 |        |                                 |        
 |        |                                 |        
 |        |                                 |        
 |        |                                 | 
 |________|_________________________________||

The current design uses only the "outer top" and "outer left" for the Global Navigation and Local Navigation areas, repectively. This structure could be easily extended to support even more complex page layouts (e.g, a set of "inner" top, left, right, and bottom cells).

Directory hierarchy

The various branding/navigation areas of the page are handled by Page Area Templates (PATs), image, and CSS files that reside in a directory hierarchy on the file system under the web server's documentRoot (so that images and .css files can be referenced). [We haven't yet finalized how the HTML files generated by the Help system will be handled, but they will also probably be in this same directory hierarchy.]

The 'requestName' part of PAT file names identifies the particular web page being requested for display (e.g., a viewOrganizationDetails page).

The final HTML snippet for each cell is generated by the PAT, and the page assembled from the cells by XSL from (X)HTML "snippets" existing in the hierarchical directory structure.

The structure and relevant files are:

xml/
    dtds/               (DTDs of message content to be transformed)
    xsl/
        bodypat.xsl         (message processing and error handling used by all PATs)
        gpmsproperties.xsl  (property file paths and convenience templates)
        
        default/            (this directory is used if [orgKey] is not present)
            [locale]/           (the region and country codes; eg. US-EN)
                ...                 (rest of default/ hierarchy is same as [orgKey] below)
        
        [orgKey]/           (the Organization's unique key assigned at creation)
            [locale]/           (the region and country codes; eg. US-EN)
                global.xsl          (PAT for Global Navigation area of page)
                local.xsl           (PAT for Local Navigation area of page)
                response.xsl        (PAT for the entire page, including HTML HEAD and BODY)
                vocabulary.xml      (commonly used page tags; eg. Countries, Time Zones)
         
                css/                (CSS stylesheets for this Org/Locale)
                images/             (image files for this Org/Locale)
                error/				(custom templates for error conditions)
                    responseError.xhtml (custom template for handling message errors from Core)
                    [error].xsl         (other error conditions; eg. validation, authentication)
                
                [topic]/            (determines which Local Navigation set is used)
                    [requestName].xsl   (PAT for the Body content area of page)
                    help/
                        [note: filenames follow documentation group convention here(?)]

Another way to picture this structure is to describe which files handle which areas of the page:

[orgKey]/[locale]/response.xsl (entire page)
  ___________________________________________________
 |                                                   |
 |             [orgKey]/[locale]/global.xsl          |
 |___________________________________________________|
 |           |                                       |
 |           |                                       |
 |           |                                       |
 |           |                                       |
 |           |                                       |
 |           |                                       |
 | [orgKey]/ |          CONTENT AREA                 |
 | [locale]/ |                                       |
 | local.xsl |             a.k.a.                    |
 |           |           the creamy                  |
 |           |             center                    |
 |           |                                       |
 |           |  [orgKey]/[locale]/                   |
 |           |     [topic]/[requestName].xsl         |
 |           |                                       |
 |___________|_______________________________________|

Programatic flow

Every http request to the GPMS Portal server goes through the RequestManager Java servlet. After authentication and authorization of the user (not covered in this document), a subclass of PageRequest is instantiated based on the requestName parameter, and the rest of the http request is passed along in the canonical form of a CPRequest (to abstract us from the HTTP implementation).
The PageRequest instance determines whether to get the page content from GPMS Core, or the local file system. In either case, XML content (which is not parsed) is returned to the RequestManager, which passes this content along to the Response class.
Response then requests page area HTML snippets from three classes GlobalNavigationDocument, LocalNavigationDocument, and Body.
GlobalNavigationDocument and LocalNavigationDocument both request XML data from the PortalRepository which includes a filtered list of navigation items available to the current user. The navigation items are rendered as buttons, links, or whatever is desired by [orgKey]/[locale]/global.xsl and [orgKey]/[locale]/local.xsl respectively. (If the [orgKey]/ directory is not present, the default/ directory is used instead.)

gpmsportal.properties

Conclusion

The FENG-SHUI approach has the following benefits:

each Service Provider can support separate look-and-feel for different locales, including different images, fonts, and help files, if desired.
a Service Consumer can have its own custom look-and-feel
each requestName can have its own look-and-feel
whenever a file (css, image or html) is not found for the specific Service Provider, locale, or Service Consumer, then an appropriate default file is used. The default look and feel can be determined by each Service Provider.
anyone with HTML knowledge can add a new Service Provider, locale, Service Consumer, or requestName GUI simply by adding HTML "sniplets" in the appropriate directory on a production system. Changes are effective immediately, with no recompiling or restarting of the system (though we might have to purge any caches we use).

If you have any questions regarding FENG-SHUI, contact Rich Fozzard at fozzard@fozzard.com