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, 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.
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.
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
<script>
dojo.addOnLoad( function () { dojo.parser.parse( "<%=namespace%>portletWidgetContainer" ); } );
</script>
<div id="<%=namespace%>portletWidgetContainer">
<div dojoType="some.Widget"></div>
</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
dijitDropDownButton">
...
</button>
</div>
</div>
...
<!-- Portlet B -->
<div class="wpsPortletBody">
<!-- Any Dijits created here will use the xyzClass 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 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 -->
...
</table>
</body>
- 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.
No comments:
Post a Comment