Customizing the Dojo Tree Widget

This is a followup article to the introduction to the dojo tree widget and the adding nodes with AJAX article.

Jaga sent a post requesting more information about using folder icons that change with the expand and collapse events. So, I'm going to show how to do it with both the HTML and programatic methods. Although not really documented, it is fairly easy to customize the dojo tree widget by changing the CSS for the tree, and the icons for its various states. If anything is unclear please, feel free to leave some feedback.

Changing the Icons

First off, we need to get some icons to use in the demonstration. A quick google finds the Tango Icon Gallery. According to the license, it should be ok to use the images.

Custom Icons for the HTML Tree

To customize the icons for the tree, we need simply add a few extra properties. expandIconSrcPlus should be set to the URL of the image to show (instead of the 'plus' sign) when the tree nodes are closed. expandIconSrcMinus canbe set to the URL of the icon to show when a node is opened. In addition to these, iconWidth and iconHeight can be set to specify the width and height of the icns. If they are not set, the default value of 18 pixels is used.

  1. <div class="dojo-Tree"
  2.   expandIconSrcPlus="http://i.willcode4beer.com/other/icons/folder16.png"
  3.   expandIconSrcMinus="http://i.willcode4beer.com/other/icons/foldero16.png"
  4.   iconWidth="16"
  5.   iconHeight="16"
  6.   >
  7.   <div class="dojo-TreeNode" title="World"></div>
  8.   <div class="dojo-TreeNode" title="Business">
  9.     <div class="dojo-TreeNode" title="News">
  10.       <div class="dojo-TreeNode" title="Main"></div>
  11.       <div class="dojo-TreeNode" title="Company News"></div>
  12.       <div class="dojo-TreeNode" title="Economy"></div>
  13.     </div>
  14.     <div class="dojo-TreeNode" title="Markets"></div>
  15.     <div class="dojo-TreeNode" title="Technology"></div>
  16.     <div class="dojo-TreeNode" title="Jobs and Economy"></div>
  17.   </div>
  18.   <div class="dojo-TreeNode" title="Sports"></div>
  19. </div>

This is the same code as used on the dojo introduction with the addition of the extra attributes (lines 49-52). I have a demo available.

Custom Icons for the Programmatic Tree

Customizign the tree icons on a programmatically built tree follows the same convention. Only, instead of custom attributes, we just add initialization parameters to the tree.

  1. <script type="text/javascript">
  2. var TreeBuilder = {
  3.   buildTreeNodes:function (dataObjs, treeParentNode){
  4.     for(var i=0; i<dataObjs.length;i++){
  5.       var node = dojo.widget.createWidget("TreeNode",{
  6.         title:dataObjs[i].title
  7.       });
  8.       treeParentNode.addChild(node);
  9.       treeParentNode.registerChild(node,i);
  10.       if(dataObjs[i].children){
  11.         this.buildTreeNodes(dataObjs[i].children, node);
  12.       }
  13.     }
  14.   },
  15.   buildTree:function (){
  16.     myTreeWidget = dojo.widget.createWidget("Tree",{
  17.       widgetId:"myNewTreeWidget",
  18.       expandIconSrcPlus:"http://i.willcode4beer.com/other/icons/folder16.png",
  19.       expandIconSrcMinus:"http://i.willcode4beer.com/other/icons/foldero16.png",
  20.       iconWidth:16,
  21.       iconHeight:16
  22.     });
  23.     this.buildTreeNodes(treeDat.treeNodes,myTreeWidget);
  24.     var treeContainer = document.getElementById("myWidgetContainer");
  25.     var placeHolder = document.getElementById("treePlaceHolder");
  26.     treeContainer.replaceChild(myTreeWidget.domNode,placeHolder);
  27.   }
  28. }
  29. dojo.addOnLoad(function(){
  30.   TreeBuilder.buildTree()
  31.   });
  32. </script>

So, from the programmatic example we just add the attributes (lines 64-67) and the generated tree will have the new icons. I have also provided an example to download.

The Properties

All of the properties can all be found in the source for the dojo tree. Or, in your downloaded code: /src/widget/Tree.js (use the other slash on windows). Another one that will probably be used alot in customization is the expandIconSrcLoading. This is the url for the icon to show while the child nodes are being downloaded (for your AJAX/RPC tree). There are also icons for all of the little grid lines.

CSS

Besides icons, the Tree widget can be customized through the use of a custom stylesheet. The property templateCssPath is used to specify the URL of the stylesheet. It is set just like the image url properties. I recommend starting with the default stylesheet which can be found in your source tree at: widget\templates\images\Tree (again, use the other slash on windows). This stylesheet defines the classes used in the tree. By using it as a foundation, you can tweak and adjust until your tree has the look you want.

Resources

Conclusion

In many respects, customization of the Dojo Tree Widget is much simpler than programming and developing it. I hope this information proves to be useful, and as always, feel free to contact me or leave a post on the blog.

-- Paul



Sponsors:

About willCode4Beer