Friday, November 11, 2011

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:

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:

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.


13 comments:

  1. Hi Mark,

    Thanks for that information about the about the Switch. Good to see how mobile is getting more and more attention.

    Looking forward to see full Support of mobile in APEX.

    ReplyDelete
  2. Hi Marc

    Could you (or someone with more permission) run the statement "exec apex_040100.wwv_flow_platform.set_preference('MOBILE_DEVELOPMENT_ENABLED','Y') ;" on apex.oracle.com?
    So we can start developing mobile in the cloud.

    Roel

    ReplyDelete
  3. Hi,
    As an Apex newbie I am excited about mobile. But I have read several postings about making changes to the
    'page template' and including the required jquery libarary references in the page template. Exactly where do you do this--where do you get to the 'page template' and exactly where do you copy that code into the page template as well as the suggested code to the Header, Body and Footer.

    Sorry for such an 'elementary' question.

    Pat

    ReplyDelete
  4. Hi Marc,
    Downloaded the app but I can't seem to install it.
    Im getting
    Could not determine workspace for application (:) on application accept.
    What am I doing wrong?

    Tnx,
    Raoul

    ReplyDelete
  5. Hi Raoul,

    What version of APEX are you using? And are you trying to install through the UI or command line?

    Thanks,
    Marc

    ReplyDelete
  6. Wonderful blog & good post.Its really helpful for me, awaiting for more new post. Keep Blogging!




    Mobile Application Development

    ReplyDelete
  7. Hey Marc

    If I change application "Availability Status" property (under edit application definition) to "Available with Edit Links" and run app from developer tool then click on "Edit Page 1" at bottom it just display "Loading image" and doesn't return page 1. In fact all developer links which display at bottom don't work.

    If I change page template to any other template e.g. No Tabs then developer links work fine.

    Look like something with mobile template. Any idea how to fix this?

    RK Shah

    ReplyDelete
  8. Hi,

    I had turned off the developer toolbar for exactly this reason. It won't work with jQuery Mobile, at least not as is. That's because jQuery Mobile loads pages via AJAX by default. And for the developer toolbar to work, AJAX page load would have to be disabled. You could manually do this for the entire page, but that would affect all links. In 4.2 we're going to address this, probably by updating the links in the toolbar to turns off AJAX load. In the meantime, I recommend using one browser to run the app, and another browser for editing.

    ReplyDelete
  9. Hello Marc! When 4.2 will be realese?

    ReplyDelete
  10. Hi,

    Newbie question.
    I just installed a fresh version of XE 11g.
    Base Apex install. Application Express 4.0.2.00.09
    My question is ...
    Where is the images directory (known as '/i/')?
    I would like to try this but I have no idea where to put the jquery libs.
    I've searched everywhere and the only time it is mentioned is upgrading to Oracle APEX 4.1.1
    Where are the image files kept on the base install?
    Thanks for any input

    ReplyDelete
    Replies
    1. Hi Jack,

      have you got the answer

      Delete
  11. Well, the information above is pretty awesome I like it very much!

    mobile programming

    ReplyDelete