Usage is quite simple. All you need to do is just to require dojox.mobile.deviceTheme with either dojo.require() or the require() API. While it is being evaluated, deviceTheme embeds the <link> tags into the <head> section. By default, it tries to load an all-in-one theme file, such as themes/iphone/iphone.css.
One important thing you should be aware of here is that loading of the css files is performed asynchronously by the browser after deviceTheme embeds the <link> tags. In most cases, it is done after loading of dojo module files (*.js). That means, dojo widget initialization may be performed without necessary css files applied, and after the initialization, finally styles are applied to the constructed widget dom tree. This won't be a problem as long as the layout calculation of the widget is performed by the browser. However, if the initialization logic accesses dom node dimensions to programmatically calculate the layout based on them like the following example, you get wrong layout because you can't get expected node dimensions without styles applied.
var h = node.offsetHeight; // offsetHeight may be wrong w/o styles
anotherNode.style.marginTop = Math.round(h / 2) + "px";
One idea is to require deviceTheme first just like the sample code above. You may get a better result with it, but only when you are lucky. Unfortunately, this can't be a general solution. A better workaround would be to have a separate <script> block as below.
As far as I tested, this brings much better result. If you have a layout problem that comes from deviceTheme, I think it's worth trying this technique.
However, we still can't guarantee that all the theme css files are loaded prior to dojo module initialization. So, a new enhancement that has been added recently to the dojo-1.8 trunk is to be able to load without dojo. That means you can load deviceTheme.js with a <scrip> tag BEFORE loading of dojo.js as below.
This way all the theme css files are loaded before loading dojo modules. With this technique, hopefully you can avoid layout problems you may have encountered with the dojo-1.7 deviceTheme.
If you would like to choose which css files of the theme to load, rather than loading the default all-in-one theme file, you can specify them with the mblThemeFiles property as below.
In this case, if the detected device is iPhone for example, these files will be loaded by deviceTheme.
One drawback, however, is that deviceTheme.js cannot be included in a build, if you load it with a script tag.
Incidentally, now the updated deviceTheme.js can be loaded without dojo, but it can still be used as a dojo module, and can be loaded with dojo.require() or require() as before.
One more important thing I would like to add is easier customization. Sometimes you may want to override the given styles in your html file like this:
With dojo-1.7 deviceTheme, unfortunately this is ignored and has no effects because <link> tags are appended as last children of the <head> element, and thus they win your custom styles. The new deviceTheme prepends <link> tags to the <head> to solve this issue.
Note that this is about what is in the dojotoolkit trunk for dojo-1.8, there's no guarantee that it will be in the final release.