Pixel Perfect UIs with Oracle MAF : CSS and JavaScript debugging on iOS

Introduction

Skinning the UI of an Oracle Mobile Application Framework (MAF) used to be very time consuming, since the process would usually involve first modifying the skin (CSS) file and then running the simulator to see the results.  When developing web applications that are to be visualized in a browser, the task is not so difficult. There are many tools that are available.  For example, most browsers come with some sort of a debugging plugin (e.g. Firebug), which will enable you to dynamically modify or add CSS styles to the HTML elements.  In addition, there are also other plugins available from other sources that deal specifically with CSS.  With the simulator, however, these is nothing really built in.  Fortunately, there is a way to achieve the same dynamic runtime debugging behavior like the browser tools. Since there are a few caveats to this process for each of the mobile platforms, this blog will be divided into two parts: iOS and Android (Pixel Perfect UIs with Oracle MAF : CSS and JavaScript debugging on Android).

Main Article

To enable the debugging the first step is to configure the Safari to display the Develop menu options:

1. Open Safari and select the Preferences menu option

2. Next, select the Advanced tab. From here select the check-box, which will enable Show Develop menu in menu bar.

mafcssdebug_8

3. Next on the mobile device (or simulator) select Settings and Safari.

4. Next, select Advanced, and ensure that the Web Inspector is set to ON.

Once these steps are completed, the process of inspecting the MAF application can begin. The following is the sample MAF application running within the iOS simulator:

mafcssdebug_11

Next, in Safari, select the Develop menu option and under iPhoneSimulator (an option iPhone will be shown for a real device) choose the appropriate .html option.

The names of the HTML files provided are usually the same (bootstrap.html), so to choose the desired bootstrap.html for the viewed page:  hover the mouse between the given menu choices and then choose the bootstrap.html option, which also highlights the simulator view:

mafcssdebug_9a

The Safari Web Inspector Console will display with the given page loaded. Complete details on how to use the Web Inspector is beyond the scope of this blog.  However, these details can be found in the Web Inspector guide located here: For now, here are the basics on using the Web Inspector.  The following image describes the individual panes and functions within the Web Inspector:

mafcssdebug_14

The Web Inspector Console displays a vast array of useful information; such as inspecting the structure of the Document Object Model (DOM) and the possibility to review all of the external resources – such as scripts, style sheets (CSS), and offline storage that are part of the page.

For this blog, the focus will be on how we can use the Web Inspector to inspect and modify a MAF button component.

mafcssdebug_5

The button component make use of a great resource: Font Awesome (http://fortawesome.github.io/Font-Awesome/). Basically, Font Awesome gives the ability to add scalable vector icons, which can also be customized (e.g. size, color, almost anything that can be done through CSS). Since these icons are not images, it enables MAF pages to be leaner. The following is the cheat-sheet (http://fortawesome.github.io/Font-Awesome/cheatsheet/) that provides an example on how many icons are available and shows the icon that was chosen to provide the camera picture:

mafcssdebug_10

To configure MAF to be able use font awesome, please follow these steps:

1. Download the complete zip package (current version as of this post: font-awesome-4.1.0) from the here

2. Unzip the entire content into the MAF Web Content resources directory.

3. For each MAF feature that you want to enable, add the font-awesome.css to the Includes section of the feature Content:

mafcssdebug_4

This example uses a technique, which designates a specific style for an application feature implemented as MAF AMX. Basically, the technique will override the default skin styles set at the application-level within the maf-config.xml and maf-skins.xml files. If the custom styles are also going to be included in other features, the recommended approach is to define these styles at the application-level. Moreover, extending and/or creating a custom skin at the application-level is better suited to support multiple versions of the OS (e.g. iOS, Android), devices (iPhone, iPad, Nexus, .etc) and versions of the devices (e.g. iPhone 5, 4, .etc). For more information on how to work with skins in MAF, refer to section 4.12 (Skinning Mobile Applications) the MAF documentation located here.

In the Web Inspector in the Content Browser, while traversing through the DOM tree the simulator will also highlight based on the code selected.  For example, selecting the code line for the button:

mafcssdebug_16

The simulator will also highlight the button:

mafcssdebug_12

The Web Inspector provides the information that this particular amx-commandButton has two additional style classes (fa_defaultProps and fa_photo) that is for implementing the font awesome camera picture. This can be confirmed by reviewing the MAF source code:

mafcssdebug_3

From within the Web Inspector, the Navigation Sidebar enables the quick access to the external sources, for example the custom CSS file. Once a resource is selected, the source is loaded within the Content Browser.  Notice that the fa_photo style selector declares a content attribute, which has been set to the font awesome camera CSS class identifier (e.g. \f083 – see cheat-sheet above for reference).

mafcssdebug_6

In the Navigation Browser, re-select the HTML file. The Content Browser will again display the DOM source. However, note the Details Side bar.  Here there is additional information (Rules) about the select amx-commandButton item. The Web Inspector supports dynamic modifications to any of the items in this section (as well as the code in the Content Browser).  For example, as mentioned previously – all font awesome icons are customizable through CSS – so if the requirement was to change the icons color, this can be quickly done by adding in a new property (color:red) to the existing style class (fa_photo::before):

mafcssdebug_17a

As the modification is being executed, the resultant will be displayed dynamically in the simulator – no refresh necessary!

mafcssdebug_13

This is an easy, yet powerful way to develop skins for MAF. Another powerful feature available in the Safari Web Inspector is the ability to debug JavaScript errors. This feature can be accessed using the Debugger Navigation Sidebar. To exemplify this process, the code has been altered a bit in the sample application, so the Refresh button will also invoke a custom JavaScript function . The JavaScript function itself is very trivial, since the primary focus is using the debugger.  The following is the code snippet for the Refresh button:

<amx:commandButton actionListener="#{pageFlowScope.pictureUtils.invokeRefreshAction}" ...

The actionListener calls a method in a managed bean:

 public void invokeRefreshAction(ActionEvent actionEvent) {
      AdfmfJavaUtilities.evaluateELExpression("#{bindings.findAllFileRemote.execute}");
      AdfmfContainerUtilities.invokeContainerJavaScriptFunction("ateam.maf-wcc", "doAlert", new Object[] {"arg1", "arg2"});
}

Notice that the code make use of the AdfmfContainerUtilities API to invoke a JavaScript function.  The parameters used by this method are : featureId, java script method called, and an array of arguments. Refer to the documentation for more information on the Application Container APIs.

Once the MAF application is executing in the iOS simulator, launch the Safari Web Inspector. In the Navigation Inspector, under the Extra Scripts, the MAF application’s custom JavaScript file can be located. Once the file is selected, the Web Inspector pretty-prints (expands) the contents of the JavaScript; enabling the setting of break points. Break points can also be set to be conditional and all break points are identified by a blue flag in the code line gutter:

mafcssdebug_20

Once the Refresh button is selected, the Web Inspector stops at the break point:

mafcssdebug_18

In the Debugger View, the Navigation Pane will show all break points and also the call stack. In the right pane (details) sidebar, the Scope Chain displays all variables and their values at the time when the script is paused.  All variables are organized by scope. Hovering over a variable in the code displays it’s value:

mafcssdebug_19

In summary, using the Safari Web Inspector can make finding solutions for both UI and JavaScript issues easier in applications developed with MAF.

Add Your Comment