DOJO connection with WebSphere Portal


WebSphere Portal contains an instance of the IBM Dojo Toolkit, a JavaScript library based on the Dojo toolkit (

When developing components that use Dojo, we must be aware of the way WebSphere Portal uses Dojo, as well as tips and restrictions when using Dojo.

The bundled Dojo is packaged in the wp_profile_root/installedApps/node_name/wps.ear/wps.war/themes/dojo/portal_dojo directory. It is intended to be usable by both IBM and non-IBM components.

In WebSphere Portal 6.1, the instance of the IBM Dojo Toolkit is based on version 1.1.1 of the Dojo toolkit. However, this bundled version 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?

  • WebSphere Portal uses the bundled Dojo extensively in the PortalWeb2 theme.
  • The Portal theme also includes Dojo for use in the client-side programming model, the search input form, and some portlets. The set of portlets using Dojo will vary over time (currently this set includes the Search Center, Site Management, and Feed Reader portlets).
Note: The portal components that use Dojo are only supported for use with the bundled Dojo.

Dojo – Best Practices

  • Only one instance of Dojo can be loaded in a page, and Dojo's current policy is that the first Dojo included in the page takes precedence. Portlets should check to see if Dojo has already been loaded before attempting to load it themselves. Portlets should verify compatibility with the loaded Dojo version. If a page can contain portlets that reference different Dojo versions, care must taken to ensure the expected Dojo version is loaded. Loading Dojo in the theme is the recommended way to accomplish this.
  • 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.
Example of correct usage
dojo.addOnLoad( function () { dojo.parser.parse( "<%=namespace%>portletWidgetContainer" ); } );

<div id="<%=namespace%>portletWidgetContainer">
<div dojoType="some.Widget"></div>
  • The xyzClass 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.
  • The placement of the theme's class (for example, class1, class2, 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="xyzClass">
<!-- Portlet A -->
<div class="wpsPortletBody">
<!-- Contents of this portlet -->
<div class="xyzTheme">
<!-- Any Dijits here will use the xyzTheme theme instead of xyzClass-->
<button class="dijit dijitReset dijitLeft dijitInline
<!-- Portlet B -->
<div class="wpsPortletBody">
<!-- Any Dijits created here will use the xyzClass theme --> ...
<!-- This table node was created for the dijit.Menu component as part of the dijit.form.DropDownButton from Portlet A -->
<table class="dijit dijitMenu dijitReset dijitMenuTable xyzTheme">
<!-- This menu will use the xyzTheme theme instead of xyzClass, but needs to have it explicitly assigned since none of its ancestors have the soria class applied -->
  • In the previous 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.

Dojo – Usage restriction

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

How to disable Dojo loading ?

Every time your portal page is loaded leads to loading of DOJO and DIJIT java scripts. But in many cases if  you are just building simple portal pages having simple themes applied to it which doesn't use DOJO then it is unnecessary to load DOJO functions each time the portal page gets loaded. Hence what we can do is we can disable this DOJO loading. In order to reduce DOJO loading which is associated with our theme go to the head_links.jspf and comment out the below lines if you know your theme is not using them and you don't want your page to load them.

Disable Dojo
Disable Dojo

1 comment:

new in MA said...

For now I guess I wont have to use it but its good to know, thanks for sharing.

Post a Comment

Recent Posts

Popular Posts

© 2011-2019 Web Portal Club