Introduction

Oracle Mobile Application Framework, MAF, uses a unique paradigm of hybrid application development on mobile platforms. This brings fine grained control over the look & feel and the behavior of the app to the mobile app development world, helping web developers make a seamless transition to the world of mobile application development without sacrificing productivity or control. The user interface for MAF applications can be based on AMX or local HTML. Regardless of which approach you use to build your user interface in MAF, you can leverage CSS and JavaScript to finely control the user experience and functionality. The framework ultimately renders HTML markup using native WebViews on the device. This presents us with a unique opportunity in debugging the MAF user interfaces through browser based remote debugging capabilities on iOS and Android. Using this feature, you can debug JavaScript by setting breakpoints and stepping through the execution and debug and change CSS styling on the generated HTML on the fly to quickly design pixel perfect UIs.

Main Article

This article walks through the process of setting up your development environment for remote debugging MAF applications' DOM, CSS and JavaScript on the Android platform. The approach is similar in the case of the iOS platform which is described in detail here. Please note that this article discusses CSS and JavaScript debugging and not how to debug your Java code. For information on debugging the Java code, please visit the Oracle documentation here

Prerequisites

The basic prerequisites for remote debugging MAF applications on the Android platform is to use :

Chrome browser version 32 or above on your workstation.

Android device or Emulator based on Android version 4.4 or above

If using a hardware device, the device should be connected to the workstation with a USB cable and USB debugging should be enabled on the device. To enable USB debugging on your Android device, go to Settings > Developer options. On Android 4.2 and newer, the developer options are hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Then, return to the previous screen to find Developer options. The Android documentation can be found here.

Debugging your MAF application

To create pixel perfect UIs using MAF, you can, in real-time, debug and alter CSS, DOM and JavaScript for your application in a live device or emulator and tweak the code until its perfect. The first step is to deploy your MAF application to your device or emulator and open the app.

If you are running on a device, then you need to set the the property javascript.debug.enabled to true in your cvm.properties file for your MAF application.



On your Chrome browser on your workstation, go to the location about://inspect or chrome://inspect to open the device inspector page. Here you should see the WebView instances on the emulator or the connected device. Alternatively you can open the page by navigating to Menu > Tools > Inspect devices This opens up the device inspector page shown below. The page lists all emulators and connected devices that have debuggable browser windows or webViews opened. The list refreshes automatically when devices or WebViews/Browser windows are opened or closed.

If the application's web view does not show up on this page, then try the following :

Make sure that ADB is running by executing adb start-server from a command line

Make sure that USB debugging is enabled on the device and make sure that you accept the RSA fingerprint of the computer.

Make sure that the checkbox for Discover USB devices is enabled on the Chrome inspect page on your workstation.

If you are using a device, ensure that the javascript.debug.enabled is set to true.

Clicking inspect on the webView displaying bootstrap.html opens up the Chrome dev tools. Bootstrap.html is like a container which wraps the HTML markup generated from the AMX views. If you are a web developer, you should be familiar with the Chrome dev-tools. Its a powerful suite of tools to analyze, debug and instrument page markup, CSS and JavaScript. The default view displays the DOM and the CSS Styles. These are fully editable, letting you change the markup or styles on the Chrome tools window and see the changes in your device or emulator in real time. In the following screen shot, I am hovering my mouse over a part of the page's DOM, and on my device, the corresponding part of the view is highlighted.

Editing the Markup on the fly

I can directly edit the HTML and the Styles and get real time feedback on how my my UI design would look and behave on a device to achieve pixel perfect styling on my MAF application. To demonstrate the versatility and power of this approach, I pick the DOM element representing my Title in the app, and edit the HTML directly inside Chrome tools. I edit the Title text as 'Realtime Editing' and my device's UI immediately reflects the change. Note that the highlight on the device is due to me selecting the DOM element in Chrome tools.

Real time CSS Styling

CSS styling is something that takes a lot of refinement to get right. Using the approach you can style MAF applications easily and refine your CSS quickly and easily saving you time and effort. To demonstrate this, we can change the color of the title and the font style. In the CSS Pane, I see that the present color is coming from a class named 'appIcon'. I could change this and change the color for everything that uses this class, but thats not really what I need. I need to create a new class that I can reuse for title text across my AMX views. Before creating the class though, I need to try out my Styling on this element to tweak it until I get it right. I add the styles directly to the element using the CSS window. I could have also done this by editing the DOM node like before, but the CSS editor pane gives me auto-completion help on CSS. Like before, the UI on my device updates in real time. Notice the red color on the title and the italic styling of the font. The next logical step would be to define this as a class so that I can reuse the style definition elsewhere. To do this, I can edit the downloaded CSS files and define new classes here. For the purposes of this article, I have defined a custom CSS style-sheet that I included in my MAF feature, and I had named it notification.css. Looking back to the earlier screenshot, you can see that the class alertIcon, we saw earlier was defined in notification.css. I switch over to the 'Sources' tab in by tools window, and locate the CSS file. This file is opened inside the tools window, which gives me a rudimentary CSS editor with syntax completion. Once I've defined the CSS class, I can go back to the source and use this class on the DOM node. Note that changes made to the CSS file are made on the file present in the deployed package. You need to copy over the CSS back to your design time, once the styles are complete.

Remote Debugging JavaScript

Using the remote debugging approach, you can also set break points, and step though the JavaScript used by the application. This can be the JavaScript that is part of the MAF framework or your own custom JavaScript. Not only can you debug the JavaScript, you can use the console provided by the tools to execute JavaScript functions on demand to test them in isolation. For example, you can open the console and make a JavaScript function call to display an alert message. And the result is the device displaying the altert message immediatly.

Similarly you can also invoke your own custom functions using the console. This comes very handy when debugging your custom JavaScript. To debug and step through JavaScript, open up the Source tab, and the JavaScript file you need to set breakpoints on. Similar to an IDE, you can setup breakpoints in the javaScript code. For the purposes of this article, I have a custom JavaScript file called openPopup.js. In the screen shot above a breakpoint has been set at line #5. When the function executes, the execution will stop at line #5 and you can step through the code. This view also lets you see the call stack, the values of the scope variables and so on. When the page is paused at a breakpoint, the Application will display a messge indicating the debugging activity. The user can resume the execution or step in to the next function call from the device.

In summary, the hybrid application development pardigm offered by Oracle Mobile Application Framework makes it easy for web developers to design pixel perfect UIs in MAF with the JavaScript and CSS debugging tools and effectively make the leap from web development to mobile application development seamlessly.