Over the past couple weeks, I've updated the Drupal Dojo Toolkit module to support the new AMD module layout and asynchronous loading.
This page shows a Dojo tab container in practice, with a simple declarative markup. Inside the tab container, find some hints for what you need to know to load Dojo on a page.
Why would you want to use Dojo?
Lots of reasons.
- Extensive, cohesive widgets
- Browser offline storage -- take your web-based application offline, and sync back up when your connection returns
- Mobile toolset
- Charts, graphics toolkits
- Ajax, Node.js push updates
- Tree widgets, grids, menus
Dojo Toolkit has a strong presence in high-end and Enterprise web applications. But since Drupal 6 standardized on jQuery, use of Dojo on Drupal has dwindled to practically nothing -- the Dojo developers who used Drupal have moved on to Rails, Zend Framework, or Node. Meanwhile, Drupal has never been a real hotbed for Javascript development.
By making it easy to include and bootstrap Dojo applications in Drupal, we hope to change that.
To get going, you'll need to take the following steps:
- Download and install the Dojo Toolkit module and the Libraries module.
- (optional) If you want to run a copy of Dojo locally, there is a convenient "dtk-dl" drush command which will download the most current stable release of Dojo (currently 1.7.2). Use "drush dtk-dl 1.7.2 release" to download the minimal release tarball and extract in your library path. If you do not want to run locally, you can load Dojo from a CDN -- Google is selected by default.
- Go to Site Configuration -> Dojo Toolkit and set options as desired.
If you want to use declarative widgets on particular content pages (like this one) the easiest thing to do is add the widget classes you want to use to the page requires, and set which pages you want to load Dojo. Then on those pages, simply adding a "data-dojo-type" attribute is all that's necessary to make those widgets active.
For example, to do a tab container like this, you simply create a div for the container with a data-dojo-type of "dijit.layout.TabContainer", and another div with the content to show for each tab with type "dijit.layout.ContentPane" and a title set to what you want to appear on the tab. You might also want to include a data-dojo-props="doLayout:false" on the parent container to get it to allocate enough vertical space in the page. That's it!
The first purpose of the Dojo Toolkit module is to make it easy to bootstrap a Dojo application, which generally means your own code. While the API is not yet completely stable, we have just revamped it to support AMD-style development.
So here's basically what you need to do to add your own Dojo scripts to your module:
| Function | Purpose | Notes |
|---|---|---|
| dojo_toolkit_load_dojo() | Call this anytime you want to be sure Dojo is bootstrapped on a page. | We generally call this in Menu Callback functions that load something heavily dependent on Dojo, such as a Graphics (dojox/gfx) object. |
| hook_dojoconfig() | Implement this hook to set some dojoConfig value. |
All return values from any hook implementations get merged into a global dojoConfig. Main use for this is to register a module path, so that you can use AMD to require your code as a module. For example:
return array(
'packages'=> array(
'mymodule' => array(
'name'=>'mymodule',
'location'=>'/'.
drupal_get_path('module','mymodule')
.'js',
),
),
);
With that return in a mymodule_dojoconfig() function, you'll then be able to load any js file inside your js directory with a require() call in the browser. For example, if you create a js/coolwidget.js file inside your module directory, this call will load it: require(['mymodule/coolwidget']); |
|
dojo_toolkit_require( 'mymodule/coolwidget' , 'coolwidget'); |
Call this to have a module loaded before the page is parsed. |
Much of Dojo can be automatically started simply by adding data-dojo-type and data-dojo-props attributes on regular HTML. Generally after the DOM is loaded and ready, you call dojo.parser.parse() to turn all of the HTML elements with Dojo properties into Dijit widgets. Before doing so, the corresponding classes must be loaded. You can specify all the Dojo modules (including your own registered through dojoConfig) that need to be loaded right at the start here. If you have any processing/bootstrapping to do after requiring these modules, the second optional parameter will become the Javascript variable that refers to this module. |
| dojo_toolkit_addonload($js) | Raw Javascript to get executed after the DOM is ready, and any requires are loaded. |
With the new AMD style of loading modules, you add any modules you want to use to a require, and assign it to a local variable. This function works with dojo_toolkit_require -- any module you load in dojo_toolkit_require and assign to a variable (the second parameter of that function) becomes available in code you add here. |
There are some known issues:
- jQuery Update, jQuery UI modules can interfere with the loading of Dojo. This is because the Drupal-standard way of loading Javascript files (drupal_add_js) does not work with Dojo or AMD, and especially not with loading from another domain (CDN). So this module attempts to add its scripts by manipulating the $variables array in a preprocess_page function. Some modules wipe out these manipulations and replace it with a fresh copy of Drupal-added scripts. If this affects you, you might be able to work around by adjusting module weights.
- Drupal 6 only, so far. Drupal 7 coming soon.
- Some themes don't work -- in addition to mangling $variables['scripts'], we also need to set a body class. If your theme strips out the Dojo theme class, most widgets won't have appropriate CSS and will fail miserably.
- These examples are based on Dojo Toolkit development release -- to be incorporated into 6.x-1.0-alpha2 or later. If it doesn't work for you today, either get the latest code from git or wait a day for a new development snapshot.
Like it? Hate it? Got any suggestions for handy configuration settings or API functions that would help? Leave us a comment below.
Dojo Drupal doubt
Hello,
I just installed the dojo toolkit for drupal. I am using CKEditor for editing pages in drupal. My drupal installation is on a local server ( my computer). I am new to both Drupal and Dojo.
Where must I type the above commands (dojo_toolkit_load_dojo) etc? Within .. in my html page?
Shreyas
Hi,
Hi,
The Dojo Toolkit module is an API module -- it is meant to make it easier to use Dojo within other modules. So in general, this code should be put into a custom module.
You could make use of it in content that uses the PHP filter -- these functions are PHP after all. So you could define an input format with the PHP filter and then drop this code into a block or node.
Bad practice, but will work for playing around...
Cheers, John
Dojo simple example
I'm using Drupal 6 with dojo toolkit,but can't make it work.
Can you cast send me simple example I can copy to PHP page showing 1 widget.
Thanks
Add new comment