Technical Note: Managing Sun Java System Portal Server 7.1 Update 1 AJAX Table Container

Previous: Book Information

Managing the AJAXTableContainerProvider

This technical note contain the following sections:

Technical Note Revision History

Version	Date	Description of Changes
10	June 07	First release of this technical note.

Overview of the AJAXTableContainerProvider

This section contains the following:

AJAXTableContainerProvider Features

The AJAXTableContainerProvider integrates Asynchronous JavaScript and XML (AJAX) capabilities at the portal framework level. The container provides asynchronous loading of individual channels and portlets. Therefore, a slow channel or portlet will not affect the loading time of the other channels and portlets on a page, improving overall performance. The AJAXTableContainerProvider includes AJAX based interaction for all container controls and features which provides for a much richer and faster user experience.

The AJAXTableContainerProvider also supports rich user interface functionality such as:

Drag and drop positioning of channels and portlets on the page.
Asynchronous interaction for channel container controls such as minimize, remove, and maximize.
Independent refresh for individual channels and portlets without refreshing the complete page.
Edit channels and portlets inline without refreshing the complete page.
Easy addition and removal of channels.
Multiple layouts for portal page.

AJAXTableContainerProvider Constraints

The AJAXTableContainerProvider has the following constraints:

Javascript must be supported and enabled on client browsers.
The AJAXTableContainerProvider will not automatically enable content within a channel or portlet for AJAX. It is the channel or portlet developer's responsibility to incorporate AJAX functionality (if required) in the channel or portlet content.
By default, channels and portlets do not display edit pages inline. The display profile property channelsEditInline must be set to true for channels that will display edit pages inline. For more information, see Display Profile properties. Edit pages of channels and portlets must be customized to appear properly in the inline edit box. This customization is required because of less screen width available for edit forms in the AJAXTableContainerProvider as compared to other containers where the complete screen width is available.
Nesting of AjaxTableContainerProvider is not supported. Only one instance of AjaxTableContainerProvider can be used per portal page.

AJAXTableContainerProvider Architecture

The AJAXTableContainerProvider is based on a hybrid architecture. Unlike other portal containers where all the processing takes place on the server and only the HTML content is returned to a browser, in the AJAXTableContainerProvider, several tasks such as page construction, style, and container controls are handled at the client side using DHTML and Javascript. The server-side component of the container provider sends a JavaScript Object Notation (JSON) message in response to requests, and the client-side JavaScript processes the JSON message to make the appropriate changes to the portal interface. Similarly, if the user modifies the portal interface, the changes are persisted to the server using AJAX.

This diagram shows the high-level architecture of the
AJAXTableContainerProvider.

The diagram shows the high-level architecture of the AJAXTableContainerProvider. The container is divided into two pieces:

Server-side Container Architecture

The AJAXTableContainerProvider is implemented as a JSPTableContainerProvider instance on the server. All the provider logic is implemented in JavaServer Page (JSP) template files of the AJAXTableContainerProvider. The container provider class remains JSPTableContainerProvider. For a content request, the AJAX Container returns a JavaScript object as a JSON representation of the display profile for the current user.

Example 1 JSON Representation of the Display Profile

An example JSON Representation of the Display Profile is shown here.

    "title": "News",
    "name": "NewsContainer",
    "layout": 3,
    "isAuthless": false,
    "maximizedChannel": "",
    "channelsIsMinimizable": {"SiteSearch": false},
    "channelsIsMinimized": {
        "NewsContainer/NextTourPoll": false,
        "SiteSearch": false
    },
    "channelsHasFrame": {
        "SiteSearch": false,
        "NewsContainer/google": true
    },
    "selectedChannels": [
        {
            "width": 1,
            "isEditable": false,
            "title": "Vote for our Next Tour",
            "description": "A poll to vote for what tour should be offered next.",
            "refreshTime": 0,
            "name": "NewsContainer/NextTourPoll",
            "id": "NextTourPoll"
        },
        {
            "width": 1,
            "isEditable": false,
            "title": "Search",
            "description": "Enter search term to search site content.",
            "refreshTime": 0,
            "name": "SiteSearch",
            "id": "SiteSearch"
        }
    ],
    "channelsIsDetachable": {"SiteSearch": false},
    "channelsRow": {
        "SiteSearch": "1",
        "NewsContainer/NextTourPoll": "1"
    },
    "refreshTime": "0",
    "isEditable": true,
    "channelsColumn": {
        "SiteSearch": "3",
        "NewsContainer/NextTourPoll": "1"
    },
    "description": Search",
    "channelsIsMaximizable": {"SiteSearch": false},
    "availableChannels": [
        {
            "width": 1,
            "isEditable": false,
            "title": "Customer Favorites",
            "description": "The top tours as rated by customers.",
            "refreshTime": 0,
            "name": "NewsContainer/CustomerFavorites",
            "id": "CustomerFavorites"
        },
        {
            "width": 2,
            "isEditable": false,
            "title": "UrlScraper Channel",
            "description": "This is a test for urlscraper",
            "refreshTime": 0,
            "name": "NewsContainer/google",
            "id": "google"
        }
    ]
}

The AJAXTableContainerProvider uses JSON Java API to construct a JSON representation of the display profile. The following JSON Java API classes are currently used in AJAXTableContainerProvider to construct the JSON message:

org.json.JSONObject
org.json.JSONArray
org.json.JSONException

Client-side Architecture

There are three high-level client side components:

AJAXTableContainerProvider JavaScript library

The AJAXTableContainerProvider JavaScript library handles the core logic of the container layout, style and container functionality. This library defines the following JavaScript classes:

sunportal.AJAXTableContainer: Defines methods that constructs the container and handles container functionality.
sunportal.AJAXChannel: Defines methods for individual channel control and display. A separate instance of this class is created for each channel on the page.
sunportal.AJAXRequest: Defines methods that handle the AJAX network Input and Output.
sunportal.AJAXPageOptions: Defines methods that handle the page preferences module.
sunportal.AJAXAddContent: Defines methods to preview and add new container content.
sunportal.AJAXPageStyles: Defines methods to modify the container style.
sunportal.AJAXChangeLayout: Defines methods to modify the container layout.
sunportal.AJAXUtils: Utility methods for other package classes.
portal.dnd.ChannelDropTarget: Defines methods for drag and drop functionality.
portal.dnd.ChannelDragSource: Defines methods for drag and drop functionality.

AJAXTableContainerProvider CSS

The AJAXTableContainerProvider ships with three out-of-the-box CSS themes: blue, orange and gray. Each CSS theme has the following directory structure:

styles
|---- <css theme name>
| |---- PrintableFloatingPane.css
| |---- images
| | |---- ajaxChannelEdit.png
| | |---- ajaxChannelHelp.png
| | |---- ajaxChannelMaximize.png
| | |---- ajaxChannelMinimize.png
| | |---- ajaxChannelRefresh.png
| | |---- ajaxChannelRemove.png
| | |---- ajaxChannelTitlebarBackground.gif
| | |---- ajaxChannelUnmaximize.png
| | |---- ajaxChannelUnminimize.png
| | |---- preview.png
| |---- screen.css

To create a customized theme, developers can copy an existing theme directory and modify the screen.css file, PrintableFloatingPane.css file, and the images to desired design and color. The screen.css file defines all the CSS classes used by the container. The PrintableFloatingPane.css is used by the floating pane widget that is used by some channels in the container.

Dojo JavaScript library

The AJAXTableContainerProvider uses Dojo, an open source Javascript library, for all the DOM manipulation, network I/O and visual effects. More information about Dojo can be found at http://www.dojotoolkit.org. The Dojo packages & classes used in the container are listed below

dojo.io.*
dojo.event.*
dojo.html
dojo.widget.Toggler
dojo.widget.ContentPane
dojo.widget.Dialog
dojo.dnd.*
dojo.fx.html

AJAXEditContainer Overview

In addition to AJAXTableContainerProvider, an AJAXEditContainer is also implemented. AJAXEditContainer allows inline editing of channel preferences from the AJAXTableContainerProvider. AJAXEditContainer is an instance of JSPSingleContainerProvider. AJAXEditContainer sends back HTML content for edit pages, and a JSON response upon successful completion of edit process. Examples of JSON messages returned by the AJAXEditContainer are shown below.

Example 2 Success Message

{
   "response": {
        "status": "SUCCESS",
        "messages": [
            ""
        ]
    }
}

Example 3 Failure Message

{
   "response": {
        "status": "FAIL",
        "messages": [
           "A serious error has occured in the Desktop. 
						This may have been caused by a mis-configuration on the server.",
           "Please report this problem to your administrator.",
           "Possible causes : Your session has expired or has been otherwise 
						terminated. Please re-login.",
       ]
   }

}

Using the AJAXTableContainerProvider

This sections contains the following:

Installing the AJAXTableContainerProvider

The AJAXTableContainerProvider is available, by default, on the Portal Server Enterprise sample with a fresh install of this relase of the Portal Server software. The container provider is added to the top level organization of the portal server and will be available in all the sub-organizations created under the top level organization. However, the AJAXTableContainerProvider will not be installed with other samples because other samples do not need the AJAXTableContainerProvider to function. However, AJAXTableContainerProvider can be easily added to the display profile to allow usage on any other custom portal.

To add the AJAXTableContainerProvider to a New Portal

Set up configuration information.

To set up configuration information:
1. Create a temporary directory to store the configuration files.
2. Copy the input.properties.template file from PortalServer-BaseDir/samples/portals/shared/ directory to the temporary directory as input.properties file.
3. Edit the input.properties file (in the temporary directory) and replace all the tokens that begin and end with % with the appropriate portal settings.

Set up password information.
1. Copy the password.properties.template file from PortalServer-BaseDir/samples/portals/shared/ directory to the temporary directory (created in Step 1,a) as password.properties file.
2. Edit the password.properties file in the temporary directory and replace all the tokens that begin and end with % with the appropriate portal settings.

Deploy the AJAXTableContainerProvider.

To deploy, type Ant-Home/bin/ant -buildfile PortalServer-BaseDir/samples/portals/build.xml install_ajax. This command will install just the container provider and make it available at the global level DP for use in any portal. This will not deploy the static files to the webapp.

To deploy the static files, type PortalServer-BaseDir/bin/psadmin redeploy -u amadmin -w amadmin-password -p portal-ID. Now, the portal webapp will be redeployed and AJAXTableContainerProvider will be made available.

Adding a Container Based on the AJAXTableContainerProvider

To Add a Container Based on AJAXTableContainerProvider to a Portal

Navigate to the Manage Channels and Containers section of the organization

Select the container under which you want to add the AJAX container.

Typically this is a tab container or a single page container.

On the right frame, click on New Channel or Container.

Go through the wizard and select the steps to add a new container.

Ensure that you select AJAXTableContainerProvider as the container provider

After adding the new container, customize the container title and description properties, and add channels to the container by clicking on the Show or Hide Channels and Containers on Portal Desktop link.

Display Profile properties

The AJAXTableContainerProvider defines the following new display profile properties:

channelsEditInline: A collection of boolean properties used to determine whether a channel will display it's edit content inline. If set to TRUE, inline editing is enabled for the channel or portlet. If set to FALSE or missing, edit pages will be displayed using JSPSinglePageContainer.
activeStyle: A string property, it specifies the name of the style to be used by the container. The provider ships three styles out of the box: orange, gray and blue.
pageStylePath: A string property, it specifies the relative path for the styles directory in the portal webapp. The default value is /desktop/ajaxcontainers/styles/.
availableStyles: A collection, it lists styles that can be used by the container. The provider ships three styles out of the box: orange, gray and blue.
My Channels: A collection, it lists channel names that must be displayed under the My Channels category.

Customizing the AJAX Container

The AJAXTableContainerProvider allows customization of the styles. You can add a new style by copying an existing style directory and modifying the contents of that style. For more information on the structure of a style directory, see AJAXTableContainerProvider CSS. The JavaScript that is shipped with the AJAXTableContainerProvider is compressed for performance optimization. Hence the JavaScript cannot be customized easily using a script editor.

Using the AJAXTableContainerProvider JavaScript API

Channels and Portlets can use the AJAXTableContainerProvider JavaScript API to quickly incorporate AJAX functionality in their content. Note that JSR-168 Portlets using this JavaScript API will not be portable across containers. AJAXTableContainerProvider methods can be accessed using an instance object by name container. The container is available on a portal page to all page elements, including channel and portlet elements.

Utility Methods

The following table shows the utility methods that can be called on the container object.

container.submitContentForm (channelName, formId)

This method can be called from any channel to submit a form asynchronously. The form is submitted with the POST method. The existing channel content is automatically replaced with the response content of the form submit. It takes the following arguments:

channelName: Name of channel or portlet as a String
formId: ID of the form element

The JavaScript source file is AJAXTableContainer.js.

container.getSelectedChannelByName(channelName)

Gets the HTML node element of a channel or portlet. It takes the channelName argument to specify the name of the channel or portlet. The JavaScript source file is AJAXTableContainer.js.

container.getChannelContentNode(channelNode)

Returns the HTML node element of the content DIV of a channel. It takes the channelNode argument to specify the HTML node element of the channel. The JavaScript source file is AJAXTableContainer.js.

container.getChannelEditNode(channelNode)

Returns the HTML node element of the inline edit DIV of a channel. It takes the channelNode argument to specify the HTML node element of the channel. The JavaScript source file is AJAXTableContainer.js.

Getting a channel Name or ID

To make changes to a channel, the HTML node element of the channel is required. The HTML node element can be obtained using the container.getSelectedChannelByName(channelName) method. This however requires the name of the channel or portlet.

The name can be obtained in the JavaScript logic of a channel using one of the following ways:

If the channel uses JSP files, then the channel name can be substituted dynamically into the JavaScript during execution. For example, in the JavaScript logic you can have a statement like:

container.submitContentForm('<%=jsChannelName%>', '<%=jsChannelName%>_form');

The value of jsChannelName will be substituted during runtime by the proper channel name. jsChannelName can be initialized as follows in the JSP:

<dt:obtainChannel channel="$JSPProvider">
		<dtpc:providerContext>
			<dt:getName id="jsChannelName"/>
			<jx:declare id="jsChannelName" type="java.lang.String" />
			:
     	:
		</dtpc:providerContext>
</dt:obtainChannel>

For more information refer to the portal desktop tag library documentation.

For static HTML files or channels and portlets that do not use JSP, a token, %{CHANNEL_NAME}, can be used in place of the channel name. This token will be replaced by the AJAXTableContainerProvider JavaScript with the appropriate channel name at runtime. For example, a JavaScript can be written as:
container.submitContentForm('%{CHANNEL_NAME}', '%{CHANNEL_NAME}_form');
Similarly, a token, %{CHANNEL_ID}, can be used to get the channel node ID.

Using Dojo

AJAXTableContainerProvider ships with Dojo 0.3.1. The Dojo object is available for channels and portlets to use on the portal page. The Dojo object instance name is dojo. Channels can call utility methods of Dojo, such as dojo.byId() using the dojo object. Channels can also create Dojo widgets using the dojo object, and also use dojo.io.bind for content requests. For example, a channel can use dojo.io.bind to fetch content from some URL (that has to be on the same domain as the portal).

Namespacing Channel Elements

Namespacing your channel elements to avoid conflicts is very important. To ensure that two channel elements do not conflict, unique names for elements have to be used.

Channels names can be made unique by any of the following ways:

Add the channel name to elements in a JSP Provider channel as follows:

var <%jsChannelName%>_name = "test";
<%=jsChannelName%>_doSomething = function() { ... }
...
<div <%jsChannelName%>_content"></div>

Add the portlet namespace in a JSR-168 channel as follows:

<portlet:namespace/>_loadInvoice = function (invoice) {
...
<div id="<portlet:namespace/>_content"></div>

In static content that does not use JSP, use tokens:

var %{CHANNEL_NAME}_name = "test"; 
%{CHANNEL_ID}_doSomething = function() { ... }

Cross-domain AJAX

At the core of every AJAX request lies the XMLHttpRequest object. One of the security restrictions of the XMLHttpRequest object is that cross domain requests cannot be made. You cannot use the XMLHttpRequest object on the portal page to fetch content from a server that resides on a different domain than the host portal. This restriction applies to sunportal.AJAXRequest and dojo.io.*. There are work arounds for this restriction, such as implementing a cross-domain proxy and on-demand JavaScript loading. You can find more information about these techniques on AJAX related websites.

AJAXTableContainerProvider Localization

All the English messages used by the AJAXTableContainerProvider are defined in ajaxcontainers.properties resource bundle deployed under /var/opt/SUNWportal/portals/portal-ID/desktop/classes (on Solaris).

Accessing Sun Resources Online

The docs.sun.com^SM web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. Books are available as online files in PDF and HTML formats. Both formats are readable by assistive technologies for users with disabilities.

To access the following Sun resources, go to http://www.sun.com:

Downloads of Sun products
Services and solutions
Support (including patches and updates)
Training
Research
Communities (for example, Sun Developer Network)

Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note –

Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, go to http://docs.sun.com and click Send Comments. In the online form, provide the full document title and part number. The part number is a 7-digit or 9-digit number that can be found on the book's title page or in the document's URL. For example, the part number of this book is 820-0042-10.

Previous: Book Information