Dojo and WebSphere Portal

WebSphere® Portal contains an instance of the IBM® Dojo Toolkit, a JavaScript library based on the Dojo toolkit (http://dojotoolkit.org). When developing components that use Dojo, you must be aware of the way in which the portal uses Dojo, as well as tips and restrictions when using Dojo.

WebSphere Portal Version 8.0 comes with five versions of Dojo:

Dojo v1.7.2. This is packaged in its own web application named Dojo_Resources. You can manage it in the WebSphere Integrated Solutions Console. By default it is deployed at the context root wps/portal_dojo . The path for the Dojo V 1.7 files is PortalServer_root/theme/wp.theme.dojo/installedApps/dojo.ear/dojo.war/v1.7 .
Dojo v1.6.1. This is packaged in its own web application named Dojo_Resources. You can manage it in the WebSphere Integrated Solutions Console. By default it is deployed at the context root wps/portal_dojo . The path for the Dojo V 1.6 files is PortalServer_root/theme/wp.theme.dojo/installedApps/dojo.ear/dojo.war/v1.6 .
Dojo v1.4.3. This is packaged in its own web application named Dojo_Resources. You can manage it in the WebSphere Integrated Solutions Console. By default it is deployed at the context root /portal_dojo . The path for the Dojo V 1.4.3 files is PortalServer_root/theme/wp.theme.dojo/installedApps/dojo.ear/dojo.war/v1.4.3 .
Dojo v1.3.2. This is packaged in its own web application named Dojo_Resources. You can manage it in the WebSphere Integrated Solutions Console. By default it is deployed at the context root /portal_dojo . The path for the Dojo V 1.3.2 files is PortalServer_root/theme/wp.theme.dojo/installedApps/dojo.ear/dojo.war .
Dojo v1.1.1. This is packaged in the directory PortalServer_root/installer/wp.ear/installableApps/wps_theme.ear/wps_theme.war/themes/dojo/portal_dojo .

All Dojo packages can be used by IBM and non-IBM components.

Notes:

The Portal 8.0 theme uses Dojo v1.7.2 by default in WebSphere Portal v8.0. This is the only supported version of Dojo with the Portal 8.0 theme.
The Portal 7.0.0.2 theme uses Dojo v1.6.1 by default in WebSphere Portal v7.0.0.2. This is the only supported version of Dojo with the Portal 7.0.0.2 theme.
The Page Builder theme uses Dojo v1.4.3 by default in WebSphere Portal v7.0.
The Portal theme uses Dojo v1.3.2 by default in WebSphere Portal v6.1.5 and v7.0. This is the only supported version of Dojo with the Portal theme.
The PortalWeb2 theme uses Dojo v1.1.1 by default in WebSphere Portal v6.1 and Dojo v1.3.2 by default in WebSphere Portal v6.1.5. These are the only supported versions of Dojo with the PortalWeb2 theme.
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.

Where WebSphere Portal uses Dojo

The Portal 8.0 theme uses Dojo v1.7.2 to support various portlets and edit-mode user interface components. The portlets and components that use Dojo vary over time. The current set of portlets that uses Dojo includes Managed Pages edit-mode user interface components, Search Center, External Search Results, Tagging and Rating, Tag Cloud, Active Site Analytics, Resource Manager Portlet, Unified Task List, WidgetWrapper Portlet, WCM Rendering Portlet, Web Content Libraries, Web Content Subscribers, Web Content Syndicators, Feed Schedules, Web2Bookmarks Portlet, CMIS Picker Portlet, and Quickr Pickr Portlet.

Note: The portal components that use Dojo are only supported for use with the bundled Dojo.

Dojo is packaged as a module as part of the modular architecture for the Portal 8.0 (and Portal 7.0.0.2) theme. For performance optimization, the minimal profile does not load Dojo at all, and the default deferred profile does not load Dojo initially for view mode, but, rather, only when a page is put into edit mode. As long as you don't load the Dojo module or any module that is a prerequisite the Dojo module in the non-deferred part of your profile, then you will not pay any performance price of loading Dojo in view mode and at run time. If you elect, you are now free to use a different JavaScript library in the view mode for your custom theme and run time. Simply creating and load your own modules for the library.

Using Dojo in your custom portal themes

For information about how to use Dojo in custom portal themes that you create see the topic about Creating a new theme.

Upgrading your custom portal themes to a later Dojo version supported by the portal: To upgrade your existing custom themes to a later supported version of Dojo, see the following sections:

Portal 7.0.0.2 theme, Dojo v1.6.1 -> Portal 8.0 theme, Dojo v1.7.2: see Updating a Portal 7.0.0.2 theme to use Dojo 1.7.
Page Builder theme, Dojo v1.4.3 -> Portal 7.0.0.2 theme, Dojo v1.6.1: see Updating a Page Builder theme to use Dojo 1.6.
Dojo v1.3.2 -> Dojo v1.4.3: see Dojo and WebSphere Portal.wp7
Dojo v1.1.1 -> Dojo v1.3.2: see Dojo and WebSphere Portal.wp7

Dojo usage best practices

When working with Dojo and portal components, be aware of the following 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 see 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 make sure that 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 make sure that 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 has 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 the DOM of the portlet. Otherwise, Dojo parses the entire document body every time the parser is called without a markup element. Other portlets might get parsed two or three times, which causes 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 has 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) is vital for the theme to display 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 class name for the secondary theme to the DOM node that is a direct child of the body, in addition to the containing DOM node of the portlet's widgets. For example:
```
<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 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 uses 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 is rendered, including the page contents themselves. The initial page can then 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 using dojo.addOnLoad, then the dojo.require statement is best served within the onload handler itself. The theme can then load additional resources at the end of the page in layer files after all page components are 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

Observe the following restrictions when using Dojo with the portal:

Only one instance of Dojo can be loaded in a page.
Do not rely on making your 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.