Getting Started with Mobile in APEX - Part 1

With jQuery Mobile moving closer to production, I finally started working on my paper documenting how to develop mobile applications with APEX 4.1 We've put a lot of changes into APEX 4.1 that make the integration of frameworks like jQuery Mobile easier. Full mobile support, with mobile templates and components that are optimized for mobile devices, is currently planned for APEX 4.2. But that doesn't mean that you couldn't start building mobile apps with APEX today. It'll just be a bit more manual work for now. So while working on the paper, I've figured I'll start blogging about this as well, taking you step by step through the process of enabling mobile development in APEX 4.1, integrating the jQuery Mobile library and building your first mobile app.

So let's get started. The first thing you'll need to do is set a system preference in APEX that enables mobile development, to do this, logon as SYS and run the following:

exec apex_040100.wwv_flow_platform.set_preference('MOBILE_DEVELOPMENT_ENABLED','Y') ;

Don't worry, this will have no effect on any of your existing applications. What this system preference does is that in a number of places in APEX, you'll now see a select list that lets you choose between a "Desktop" and "Mobile" mode. The most important place where that's relevant is when editing a page template, i.e. you can now define that page template to be a mobile page template or a full-size / desktop page template. Once we have jQuery Mobile fully integrated, currently targeted for APEX 4.2, this will trigger the inclusion of the jQuery Mobile library, and the omission of some JavaScript and CSS references that are not needed for mobile. For the time being though, all this is doing is that it makes APEX render form elements on your mobile pages without a table grid. This gives you better control over the HTML generated by APEX, which allows the generation of HTML code that follows to jQuery Mobile syntax. Having a mobile page template in your current theme also triggers the mobile option in the create page wizards. So you can choose to build a mobile page, which hides page types from the wizard that don't yet work well on mobile, like e.g. Flash charts. And as you step through the wizard, the wizard will pick up your default mobile templates, instead of the standard templates, but only if you have actually set your mobile defaults for your theme.

Next you'll need to install or reference the jQuery Mobile libraries. These libraries are not yet bundled into APEX because jQuery Mobile is not yet production software. However you can download the libraries directly from jquerymobile.com or even easier, reference the CDN-hosted libraries in your page template. To reference the CDN, simply include the following in your page template:

<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0rc2/jquery.mobile-1.0rc2.min.css" />
<script src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0rc2/jquery.mobile-1.0rc2.min.js"></script>

If you prefer downloading and installing jQuery Mobile in your APEX instance, go to this URL and download the ZIP File from there:

http://jquerymobile.com/download/

Then extract the contents of this ZIP file and load them into your APEX images directory. When using the APEX Listener or Apache/mod_plsql, you can simply copy the files to the images directory. When using the Embedded Gateway, you will need to connect to your database via WebDAV or FTP and upload the files into XML DB. To follow the folder structure that APEX uses for other jQuery libraries, make sure to copy the files to a folder you create as \i\libraries\jquery-mobile\1.0rc2\ (that's assuming your downloading the Release Candidate 2 of jQuery Mobile). The JS and CSS files should be copied directly in this folder, the images directory one below. Once installed, you can include the following in your page template:

<link rel="stylesheet" href="#IMAGE_PREFIX#libraries/jquery-mobile/1.0rc2/jquery.mobile-1.0rc2.min.css" />
<script src="#IMAGE_PREFIX#libraries/jquery/1.6.1/jquery-1.6.1.js""></script>
<script src="#IMAGE_PREFIX#libraries/jquery-mobile/1.0rc2/jquery.mobile-1.0rc2.min.js"></script>

And then you're ready to get started with Mobile development. To create a minimalist mobile page template, use the following code samples:

Header:

<!DOCTYPE html>
 <html>
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>#TITLE#</title>
     #HEAD#
     <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0rc2/jquery.mobile-1.0rc2.min.css" />
     <script src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
     <script src="http://code.jquery.com/mobile/1.0rc2/jquery.mobile-1.0rc2.min.js"></script>
   </head>
   <body #ONLOAD#>
     #FORM_OPEN#

Body:

<div data-role="page" id="#TITLE#">

  <div data-role="header" data-theme="b" data-position="fixed">
    <h1>#TITLE#</h1>
  </div>

  <div data-role="content">
    #BOX_BODY#
  </div>

  <div data-role="footer" class="ui-bar" data-position="fixed">
    #REGION_POSITION_08#
  </div>

</div>

Footer:

#FORM_CLOSE#  
</body>
</html>

After that, create a new page, choosing the newly created mobile template, and include e.g. a HTML region with some static text, like "Hello World". Then open that page in your mobile device. You should see something like this:

http://apex.oracle.com/pls/apex/f?p=JQMDEMO38948:1

You can download this sample app here (this is an updated version, in my previous version I used an application alias that caused the app to not work if it was installed more than once on an instance like apex.oracle.com), just import into your own workspace and run:

Mobile Demo 1

Please note that this demo references the CDN, if you want to reference your locally installed jQuery Mobile files, please modify your page template as outlined above.

This concludes my first "Getting Started with Mobile" blog post. Next time I'll cover the jQuery Mobile syntax and how you would go about structuring your mobile APEX pages.