Monday, 25 November 2013

Oracle APEX - Native Mobile Applications With Access to OS Functionality

A lot of you will have at some point created a mobile application using Oracle APEX. Like all APEX development it is intuitive and easy to produce working results. However, the applications sometimes fall short in terms of functionality compared to native mobile applications, which are able to easily access the phone's native operating system functionality.

To install your APEX applications natively on your mobile and gain access to your phone's features you can use PhoneGap, an application container technology that allows you to create natively-installed applications for mobile devices using HTML, CSS, and JavaScript. Its core engine is also 100% open source, under the Apache Cordova project.

PhoneGap provides an application programming interface (API) that enables you to access native operating system functionality using JavaScript. You build your application logic using JavaScript, and then its API handles communication with the native operating system. In short, it allows you to install your APEX application on your mobile and access functionality such as the camera, the contact book, the accelerometer and a range of other features which are listed here.

In order for an APEX application to be able to access these features there a few steps you must follow. By far the easiest method is to use build.phonegap.com, a cloud based service that allows you to quickly build mobile applications and easily compile them without SDKs, compilers or hardware.

Archive an Index.html file to a zip containing the following code:

<!DOCTYPE html>
<html>
  <head>
  <title>APEX DEMO</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no;" />
<meta charset="utf-8">
  </head>
  <body onload="window.location.href='http://apex.oracle.com/pls/apex/f?p=INSERT_APP_ALIAS_HERE';">
    </body>
</html>

After signing up for an account or logging in with your GitHub account you can then upload this file and it will build your application, injecting the necessary files in the process.

You then choose which platform you would like, we chose android. The app that has been created does nothing apart from open your APEX application in a "chrome-less" web browser window and bridge the gap between your phone's features and the web application you created in APEX.

Download the app in the relevant format (ie .apk) and then use your preferred software to unzip this file in order to retrieve its contents. Specifically you are looking for a file named "phonegap.js".  You will need to include this file in your APEX application.  Click here to see our guide to including JavaScript files in APEX.

We referenced the file in the JavaScript | File URLs field of our application's page template:


Before you can begin using PhoneGap to access features on your phone you must add an event listener for the "deviceready" event that fires when PhoneGap is ready. This is to avoid your application calling a PhoneGap function before the JavaScript has loaded. See the documentation for more information.

document.addEventListener("deviceready",onDeviceReady,false);

When PhoneGap is finished initialising, it calls the "onDeviceReady" function. This could be called anything you like and do anything you like. It is simply a callback function to handle the event, but it needs to be defined somewhere on your page or application i.e:

function onDeviceReady(){
     alert('Ready')
}

This will pop an alert up to let you know that it has initialised and you are now ready to safely make calls to PhoneGap function.

There is a lot you can do with PhoneGap and they are constantly updating their features and support for various devices. If you want to know what to do now that you have handled the "deviceready" event, you can browse through their API documentation which contains some very clear instructions for each feature.

Oracle Apex - Including JavaScript on Multiple Pages

We recently came across the need to include some JavaScript in every page of an APEX application. We were implementing a JQuery accordion style menu as seen here.

After the menu was in place, we decided it would be good to have the relevant panel remain open when navigating to a page in the application. One method this can be achieved is with some JavaScript like such:

                                                                   Click here for the JavaScript code used above.

The issue here is, despite the many uses of the global page (zero), you cannot use it to have some JavaScript code on every page.

There are a few solutions. One is to save the necessary JavaScript as a “.js” file on your computer and then upload it directly to your application workspace. This is done by navigating to shared components > static files and then clicking upload. Now you can either navigate to Application properties > User Interface or to your page template, and under JavaScript you can link your file as “#WORKSPACE_IMAGES#YOURFILE.js”.

Using the page template is recommended as you have more control over where the JavaScript will be present in your application.

Alternatively, as of Apex 4.2.2 you can specify which pages have the JavaScript file present on them manually rather than it being present on every page in your application. To do this, on the page(s) you want the JavaScript file included, go to Edit Page Attributes and under JavaScript there is a "File URLs" field. Link your file here with the relevant URL.

The next step is to check that the JavaScript is present in your application. If you have a browser with a built in console, or if you have software like firebug, you can open the console on a page in your application and go to resources > (f) > Scripts > wwv_flow_file_mgr.get_file and this should now display the JavaScript you previously uploaded.

 If it does not show your JavaScript, try re-uploading with a different file name and changing the link to match (#workspace_images#yourfile.js)