Dojo and WebSphere Portal

WebSphere Portal v6.1.5 contains two versions of the IBM Dojo Toolkit, a JavaScript library based on the Dojo toolkit...

Dojo v1.3.2	Packaged in its own Web application named Dojo_Resources. Managed in WAS administration console. Context root... /portal_dojo Files are under... profile_root/installedApps/node_name/Dojo_Resources.ear/dojo.war
Dojo v1.1.1	Packaged in the directory... profile_root/installedApps/node_name/wps.ear/wps.war/themes/dojo/portal_dojo

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

The Portal and PortalWeb2 themes use version 1.3.2 by default in WebSphere Portal v6.1.5.

Page Builder and widgets are currently supported on Dojo 1.3.2 only.

You can downgrade portal v6.1.5 themes to Dojo v1.1.1

Where WebSphere Portal uses Dojo

The themes provided with the portal use Dojo v1.3.2 by default. Themes that use Dojo v1.3.2 extensively include...

• PortalWeb2
• Tab Menu - Page Builder

The Portal theme uses Dojo in...

• client-side programming model
• search input form

Portlets currently using Dojo include...

• Search Center
• Site Management
• Syndicated Feed Portlet

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

Use Dojo v1.3.2 in custom portal themes

To use Dojo v1.3.2 in custom portal themes see Creating a new theme.

Upgrade custom portal themes to Dojo v1.3.2:

To upgrade existing custom themes from Dojo v1.1.1 to v1.3.2...

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

   ...with the Web path...

   /portal_dojo

2. Replace all Web application relative Web paths of...
   themes/dojo/portal_dojo

   ...with the Web path...

   /portal_dojo

3. 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 will not be able to detect its base URL. In such cases, define the djConfig object and specify the djConfig.baseUrl property to the correct path where the dojo.js file is located...

   /portal_dojo/dojo/

   The last slash is important.

Dojo usage best practices

• Only one instance of Dojo can be loaded in a page. The first Dojo included in the page takes precedence.

  Applications or the theme can load additional Dojo bundles using Dojo native support as long as the Dojo bundles are scoped to different namespaces than the Dojo defaults. For performance reasons, it is best to only load one version of Dojo in the page.

  Make sure that applications and portlets that reference Dojo at a particular namespace scope work correctly with the version of Dojo mapped to that scope.

  Different themes in the same portal can use different versions of Dojo, but 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 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">
      ...
      <!-- Portlet A -->
      <div class="wpsPortletBody">
          <!-- Contents of this portlet -->
          <div class="soria">
              <!-- Any Dijits here will use the soria theme instead of tundra -->
              <button class="dijit dijitReset dijitLeft dijitInline dijitDropDownButton">
              ...
              </button>
          </div>
      </div>
      ...
      <!-- Portlet B -->
      <div class="wpsPortletBody">
          <!-- Any Dijits created here will use the tundra theme -->
          ...
      </div>
  
      <!-- 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 soria">
          <!-- This menu will use the soria theme instead of tundra, but needs to have it explicitly
         assigned since none of its ancestors have the soria class applied -->
          ...
      </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 the portal:

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

• See Troubleshooting Web 2.0 issues for other debugging tips.

Parent topic:

Designing a portal site

Related tasks

Creating a new theme
WebSphere Portal Family wiki:   http://www-10.lotus.com/ldd/portalwiki.nsf
Using and migrating Dojo versions with WebSphere Portal themes