Dojo and WebSphere Portal

Dojo and WebSphere Portal

Overview

WebSphere Portal contains an instance of the IBM Dojo Toolkit, a JavaScript library based on the Dojo toolkit . When developing components that use Dojo, be aware of the way in which the portal uses Dojo, as well as tips and restrictions when using Dojo.
WebSphere Portal v7.0 comes with three versions of Dojo, managed in the WAS admin console...

Dojo v1.4.3

Web application Dojo_Resources
Context root /portal_dojo
Path $PORTAL_HOME/theme/wp.theme.dojo/installedApps/dojo.ear/dojo.war/v1.4.3

Dojo v1.3.2

Web application Dojo_Resources
Context root /portal_dojo
Path $PORTAL_HOME/theme/wp.theme.dojo/installedApps/dojo.ear/dojo.war

Dojo v1.1.1 PORTAL_HOME/installer/wp.ear/installableApps/wps.ear/wps.war/themes/dojo/portal_dojo

All Dojo packages can be used by IBM and non-IBM components.
The Portal theme uses Dojo version 1.3.2 by default in WebSphere Portal v7.0. The Page Builder theme uses version 1.4.3 and is currently only supported by Dojo V 1.4.3 only.
The Dojo Toolkit provided with the portal will be updated as needed over time. This could include entire new Dojo versions, as well as specific defect fixes. Compatibility of future Dojo versions is defined by the Dojo project.
When upgrading to V 1.4.3 or V 1.3.2 of Dojo, refer to the web URL for the related release notes. This includes information about changes or impacts that the newer version can have on custom code.
You can downgrade portal v7.0 themes to Dojo V 1.1.1

Where WebSphere Portal uses Dojo
The Page Builder theme uses Dojo V 1.4.3 to support various page builder widgets and user interface components. The Portal theme includes Dojo V 1.3.2 to support features such as the client side programming model, the search input form, and some portlets. The portlets that use Dojo vary over time. The current set of portlets that use Dojo includes:

Search Center
External Search Results
Tag Cloud
Resource Manager Portlet
Web Content Libraries
Web Content Subscribers
Web Content Syndicators
Feed Schedules
Web2Bookmarks Portlet

The portal components that use Dojo are only supported for use with the bundled Dojo.
To use Dojo in custom portal themes see : Create a new theme.

Upgrade custom portal themes to a later Dojo version supported by the portal

To upgrade existing custom themes from Dojo V 1.1.1 to a later supported version...

Modify the theme to locate Dojo by using the new context root...
/portal_dojo

.and the path to the required version, for example v1.4.3

Replace all full Web path occurrences of...
/wps/themes/dojo/portal_dojo

.with the new...
context root/portal_dojo

.followed by the version specific path within the Dojo Resources application as required.

Also replace all Web application relative web paths of themes/dojo/portal_dojo that might also be referenced by the same new web path /portal_dojo , followed by the version specific path within the Dojo Resources application as required.

If you include Dojo by an external script tag that points directly to the dojo.js , it determines its own base URL, which it uses for all dojo.require calls. However, if you include Dojo through another mechanism, for example inlining it in a dynamic jsp through a jsp include or import call, it cannot detect its base URL. In such cases, you need to define the djConfig object and specify the djConfig.baseUrl property to the correct path where the dojo.js file is located:

In the Dojo V 1.3.2 bundle this location is...
/portal_dojo/dojo/

In Dojo V 1.4.3 this location is...
/portal_dojo/v1.4.3/dojo/

Do not omit the last forward slash.

Dojo usage best practices

Only one instance of Dojo can be loaded in a page, and the current Dojo policy is that the first Dojo included in the page takes precedence. Consequently:

Dojo can be loaded only once per namespace. You can load more than one version of Dojo in the page by using the Dojo native support for scopes. For details refer to the Dojo documentation. For performance reasons, it is best to only load one version of Dojo in the page. However, applications or the theme can load additional Dojo bundles as long as they are scoped to different namespaces than the Dojo defaults. You need to verify applications and portlets that reference Dojo at a particular namespace scope work correctly with the version of Dojo that is mapped to that scope.

Different themes in the same portal can use different versions of Dojo, but you need to verify the portlets that execute in these themes can work with both Dojo versions.

Support for multiple versions of Dojo at run time creates a more robust application which is more stable across migrations and upgrades, but may be slightly more complex depending on the added code complexity.
All portlets using Dojo widgets must manually call the Dojo parser when loading. Setting djConfig.parseOnLoad will have no effect. Otherwise, no widgets will be parsed in the portlet.
All portlets should pass a markup element to the parser. The markup element should only exist inside that portlet's DOM. Otherwise, Dojo parses the entire document body every time the parser is called without a markup element, and other portlets could get parsed two or three times, which will cause the Dojo parser to fail every time it hits a widget that has already been parsed.
Here is an example of correct usage:
<script> 
    dojo.addOnLoad(function() { dojo.parser.parse( "<%=namespace%>portletWidgetContainer" ); } ); 
</script>
<div id="<%=namespace%>portletWidgetContainer">
    <div dojoType="some.Widget"></div>
</div>
The tundra class is set on the body element in the portal Web 2.0 themes, and its corresponding CSS files are linked in as well. To use a different theme within a particular portlet, do not change the CSS classes of the body element from within the portlet because it will have consequences on all other portlets and theme components that use Dijits on the page. Instead, use a separate node within the portlet to contain all the widgets used by that portlet, and assign the different theme class name on the container node inside the portlet.
It is important to note that the placement of the theme class (for example, tundra, soria, and so forth) is vital for the theme to appear correctly in Dijit components. If a Dijit component creates any elements as direct children of the body element, instead of or in addition to the same place in the DOM where the Dijit component was attached, then it is important to explicitly assign the secondary theme's class name to the DOM node that is a direct child of the body, in addition to the containing DOM node of the portlet's widgets as described above. For example, in the following structure:
<body class="tundra">
	...
	
	<div class="wpsPortletBody">
		
		<div class="soria">
			
			<button class="dijit dijitReset dijitLeft dijitInline dijitDropDownButton">
			...
			</button>
		</div>
	</div>
	...
	
	<div class="wpsPortletBody">
		
		...
	</div>
 
	
	<table class="dijit dijitMenu dijitReset dijitMenuTable soria">
		
		...
	</table>
</body>
In this example, when Portlet A creates a new dijit.form.DropDownButton, the code to create that widget also creates a menu component and a new DOM node under the body, but does not assign a CSS class to that DOM node. If nothing else is done after creating the DropDownButton, then the DropDownButton will use the soria class, but the menu that pops up when the button is clicked will use the tundra class. In cases like this, it is important to explicitly set the soria class on the DOM node containing the menu.
If possible, load Javascript code at the end of the theme markup after the rest of the page has been rendered, including the page contents themselves. This allows the initial page to render quickly without blocking requests to serve large Javascript files, including custom layer files. However, provide core Dojo functions in the head section of the page so that user interface components such as portlets and widgets can have access to these core functions.
In relation to loading resources at the end of the theme rather than all inside the head section, the best practice for dojo.require statements in portlet applications, widgets, or other user interface components is to include them immediately before the objects or code within the modules that they load are actually used. This means that if the code is not used until after the page has loaded, for example through an onload handler registered via dojo.addOnLoad, then the dojo.require statement is best served within the onload handler itself. This allows themes to load additional resources at the end of the page in layer files after all page components have already been included. As a result, if the theme has already provided those modules in layer files at the end of the markup, the dojo.require statements can return immediately, when the onload handlers are fired. This also avoids unnecessary requests for modules that the theme loads but that have not been loaded at the point in time when the user interface component is included in the markup on the page.

Dojo usage restrictions

Only one instance of Dojo can be loaded in a page. For details refer to the section about Dojo best practises.
Dojo widgets require special considerations when used in the PortalWeb2 theme.
Widgets need to disconnect all of their event handlers during the destroy method of the widget.
Widgets must not attach events to global elements, such as a document, window, or body.
Other customizations may be required based on specific use cases.
Do not rely on making own updates to the bundled Dojo package. WebSphere Portal support is likely to update individual files over time, and might even replace the entire package.
Refer to the topic about Troubleshooting Web 2.0 issues for other debugging tips.

Parent
Developing

WebSphere Portal Family wiki
Use and migrate Dojo versions with WebSphere Portal themes
Dojo V 1.3 Release notes
Dojo V 1.4 Release notes

+
Search Tips | Advanced Search