Dojo and WebSphere Portal

Dojo and WebSphere Portal

+
Search Tips | Advanced Search

WebSphere Portal contains an instance of the IBM Dojo Toolkit, a JavaScript library based on the Dojo toolkit v1.1.1 .
The IBM Dojo Toolkit is usable by both IBM and non-IBM components.
The bundled Dojo is packaged in...
WP_PROFILE/installedApps/node/wps.ear/wps.war/themes/dojo/portal_dojo

WebSphere Portal uses the bundled Dojo extensively in the PortalWeb2 theme.
The Portal theme also includes Dojo for use in...

client-side programming model
search input form
some portlets

The set of portlets using Dojo will vary over time. Currently this set includes...

Search Center
Site Management
Feed Reader portlets

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

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 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.
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.
The placement of the theme's 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.
Dojo usage restrictions
Observe the following restrictions when using Dojo with WebSphere Portal:

Dojo widgets are not supported for use in the PortalWeb2 theme.
All widgets need to disconnect all of their event handlers during the destroy method of the widget.
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.

Parent topic
Designing a portal site