Dojo FAQ: Is there a way to extend a widget’s template (e.g. Dialog)?

By on May 15, 2013 3:02 pm

There are indeed ways of doing so, but while Dijit strives to provide extensible modules that can serve as a basis for your own custom modules, templates are a tricky thing to deal with.

A brief review of some of the best practices for maintenance & longevity when building applications with Dojo:

  • Use a separate package for your custom modules rather than dojo, dijit, or dojox – this makes it very clear which modules come from the Dojo distribution and which modules were created for your application or organization
  • Never edit Dojo modules directly – Dojo provides dojo/_base/declare for inheritance and provides many modules that were designed to be extended or used as mixins

With a clear separation in your codebase between Dojo modules and custom modules created for your application you have a much greater chance of a simple & successful upgrade to a new release of Dojo.

If you find yourself wanting to edit a Dijit’s template, you should first see if you can meet your needs using CSS or the widget’s content area. By inspecting the DOM of Dijits rendered in a page, you can see the element structure and CSS rules applied. You can override the CSS rules using the same selectors simply by including your custom CSS after Dijit’s CSS has been loaded. Dialog, layout, and container Dijits are explicitly designed to display arbitrary content, so see if you can place your custom elements in the content area.

If you have really exhausted other possibilities and feel a need to significantly modify a Dijit’s DOM, it’s best to leave the existing template intact – the code for the widget is expecting a certain DOM structure and may fail if you remove or rearrange elements. One approach is to copy the Dijit’s template, edit it to meet your needs, and use it in your own custom widget that extends the original Dijit. If you feel OK with keeping your modified template up-to-date with the base template as you update the release of Dojo you use, this approach may work for you.

A somewhat complicated, but more resilient approach would be to programmatically add your elements to the DOM in your custom widget’s buildRendering method. Don’t remove existing elements – you may be able to get away with hiding them, but removing them may lead to code errors. Since the DOM structure has potential to change with new releases of Dojo, you should locate an element that has an attach point, as these are less prone to change. Insert your custom DOM nodes, or even other widgets, into the Dijit’s DOM with an attach point node as the reference for positioning. With this approach, your custom widget is more likely to continue working unmodified as you upgrade your application to use new releases of Dojo.