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

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).