This guide sets out some of the technical steps required to take advantage of the IDX toolkit and the One UI mobile theme in a web page or mobile hybrid app.
Controlling how your app is rendered
Your HTML will be rendered by the web browser or HTML rendering engine on the mobile device on which it is run. There are several important declarations you need to include in your page in order for the web browser or HTML rendering engine to make the right choices.
DOCTYPE declaration
The IDX One UI toolkit is intended to be used with HTML 5 and each page should therefore begin with an HTML 5 DOCTYPE declaration:
<!DOCTYPE html>
The "viewport" <meta> tag
The "viewport" <meta> tag is recognised by mobile browsers on several platforms including mobile Safari on iOS and Google Chrome on Android. Further details about the "viewport" <meta> tag can be found on the Apple developer site. The following aspects are important for complying with the One UI standard:
- Setting the initial "scale" to "1.0" ensures that the CSS-to-device-pixel ratio is set in line with the CSS reference pixel definition. The default scale if this setting is omitted can vary widely from one browser to another. This setting also means that the page does not rescale on orientation change, but rather remains at the same scale and changes the available dimensions, and this is important for building appropriately responsive app UIs.
- Enabling user scaling (typically supported on the mobile devices by a pinch-to-zoom gesture and touch-initiated panning while zoomed) is important to comply with the One UI accessibility guidance.
The following "viewport" <meta> tag should be placed in the <head> section of each page to apply the above settings:
<meta name="viewport" content="initial-scale=1.0, user-scalable=yes" />
Other <meta> tag
There are also some <meta> tags recognised by mobile Safari on iOS, that enable a web page loaded into the browser to declare that it can run 'full-screen' and to control the appearance of the status bar (the narrow bar containing various status icons such as battery charge and network connectivity that runs along the top of the screen in iOS). The following tags declare that a page is a web app (can be loaded standalone, with no browser chrome), and request a black status bar:
<meta name="apple-mobile-web-app-capable" content="yes" /> <meta name="apple-mobile-web-app-status-bar-style" content="black" />
Loading the One UI mobile theme
The One UI mobile theme comes in two varieties, one designed for iOS (iPhone/iPad) and the other for Android devices. These varieties enable certain parts of the theme to adapt to device-specific rendering conventions and interaction models, so it is important to ensure that the correct variety is loaded in the appropriate circumstances. The One UI standard also specifies that on other devices (i.e. that are neither iOS nor Android) the iOS variety should be used.
Loading the One UI mobile theme using idx/mobile/deviceTheme
To support responsive app design a module idx/mobile/deviceTheme is provided that detects the platform on which the page is being loaded and loads the appropriate theme variety automatically. This is the recommended way to load the One UI mobile theme. The idx/mobile/deviceTheme module is designed to be exactly compatible with the dojox/mobile/deviceTheme module provided by Dojo, but it loads the appropriate variety of the One UI mobile theme in place of the default dojox/mobile themes.
It is possible to require() the idx/mobile/deviceTheme module, but it is important to load the theme files as early as possible in order to ensure that the theme definitions are in place when the dojox.mobile widgets initialise and so the recommended way to use the idx/mobile/deviceTheme module is to load it directly before loading dojo.js. This can be done with a simple <script&rt; tag as follows:
<script src="...path-to-idx.../ibmjs/idx/mobile/deviceTheme.js"&rt;</script&rt;
No further steps are required when using this module: the necessary CSS files will be loaded automatically and the appropriate classes set onto the <body&rt; tag.
It is possible to configure the loading of theme files with various config variables that can be set up before loading the idx/mobile/deviceTheme module or passed to the module on the <script&rt; tag. The idx/mobile/deviceTheme module supports all the configuration variables that the dojox/mobile/deviceTheme module supports, and in exactly the same way.
Loading the One UI mobile theme directly
A page or app can load each theme variety directly if required by loading the following CSS files:
- for the iOS variety: /idx/mobile/themes/oneui_ios/oneui_ios.css. The CSS class "oneui_ios_theme" should also be added to the <body&rt; tag.
- for the Android variety: /idx/mobile/themes/oneui_android/oneui_android.css. The CSS class "oneui_android_theme" should also be added to the <body&rt; tag.
Loading Dojo
The "dojo.js" entry point to Dojo should be loaded via a <script&rt; tag in the usual way. In order to use dojox/mobile features you should include "dojox/mobile" in your list of require()s.
Registering IDX as a Dojo package
In order to be able to use the additional widgets provided by IDX to support the One UI standards, "idx" needs to be registered as a package to Dojo. This can be done by setting the 'packages' structure in the dojo config in the following way:
packages: [ {name: "dojo", location: "./" }, // standard definition {name: "dijit", location: "../dijit" }, // standard definition {name: "dojox", location: "../dojox" }, // standard definition {name: "gridx", location: "../gridx" }, {name: "idx", location: "...path-from-dojo-to-idx.../ibmjs/idx" }, ... any other package definitions required ... ]
Parsers
If your page will include declarative (HTML) definitions of widgets, either from the dojox/mobile package or from idx/mobile (additional widgets provided by IDX to support the One UI standards) or a mixture of both, you will need to load a parser and ask it to parse the page content. There is a choice of two parsers available in Dojo:
- dojox/mobile/Parser, a lightweight parser with a small download footprint but also reduced functionality, suitable if your page only contains simply widget declarations.
- dijit/Parser, the full-function parser that includes support for <script&rt; tag declarations of methods and handlers and similar advanced features.
Page initialisation
It is not generally desirable for your page content to be seen by the app user before Dojo has been initialised, the parser has run, etc, as the layout and styling will look very odd and a disturbing reformatting flash will occur as the widgets become initialised. To avoid this, make your page <body&rt; tag initially invisible. The <body&rt; tag will be automatically shown by dojox/mobile during initialisation.
<body style="visibility: hidden;"&rt;
The idx/mobile/Launch widget provides support for the One UI Launch standard, and this widget too will automatically show the <body&rt; tag as soon as the launch pane is in ready to be displayed to the user.
Responsive app design
Although many aspects of One UI apply to all mobile platforms, there are certain platform-specific differences that mean that there are likely to be circumstances in which an app needs to provide different styling, or a different JavaScript code path, according to whether the app is using the iOS variety or the Android variety of the One UI theme.
Even more importantly, there may well be circumstances in which an app needs to provide different styling, or a different JavaScript code path, according to whether the app is on a "phone"-type device (small format screen) or a "tablet"-type device (larger format screen), or according to whether the device is in "portrait" orientation (height greater than width) or "landscape" orientation (width greater than height).
These forms of adaptation by an app are termed "responsive design".