Dojo FAQ: Why is my widget not displaying or behaving properly?

By on September 11, 2013 10:19 am

When working with widgets in Dojo, occasionally, things will appear to just go off the rails, and widget code that appears at first glance like it should be working properly ends up giving you a broken widget, or a half-functioning widget. There are several reasons why this might happen; here are some of the most common.

Forgetting startup

A fairly common issue for new and old Dojo users alike occurs when creating widgets directly from JavaScript. Sometimes, these widgets just don’t seem to display or function properly, even though they’ve been instantiated and added to the DOM. Fortunately, the cause is usually a simple mistake that is easy to fix: forgetting to call the startup method of a widget, or accidentally calling startup before the widget has been added to a visible part of the DOM.

Calling startup is not a concern when working with declarative widgets (i.e. widgets created from HTML) because the dojo/parser module takes care of doing it for you. Using the addChild method of a layout container widget will also cause startup to be automatically called when appropriate, so you don’t need to worry about starting up child widgets yourself in this scenario. In all other cases, you are responsible for calling startup once you know the widget is ready to be started. In most cases, being “ready to start” simply means being in the DOM, but widgets that perform additional layout and sizing calculations in startup may need to only be started after their parent elements are visible and resized appropriately. This latter case is why startup isn’t simply called automatically whenever a widget is placed in the DOM.

While not all widgets need startup to be called to appear to work properly, subtle defects can crop up if you don’t. Calling startup more than once won’t adversely affect how a widget works, so you don’t have to worry about accidentally double-starting a widget. Just make sure you do call it at least once, once the widget is ready to go, and you’ll avoid a whole range of confusing widget trouble.

Forgetting this.inherited

If you’ve using a custom widget, are calling startup, and things still aren’t working, the next thing to check is to whether or not all of your extended methods are still calling the inherited class’s methods using this.inherited(arguments). Often, users will extend one of the common widget lifecycle methods and then forget this one line of code, which means that parent code that’s necessary for the widget to set itself up is no longer being called.

Missing height on html/body elements

BorderContainers are often used as master user interface containers for an entire application. In order to make sure that the BorderContainer expands to fit the entire height of the browser window, explicit CSS heights on the <html> and <body> elements must be set—usually just html, body { height: 100%; margin: 0; }. This is because, in standards mode, these elements work like any other block-level element, which means their heights wrap to the content they contain instead of the height of the browser window by default.