Wednesday, October 31, 2012

ADF Mobile : Your First Navigation and Device Interaction

Now ADF Mobile is generally availble, it is now time to create your first ADF Mobile application. In this post I will show you how to create a simple application that contains of two pages with navigation. A bonus for this post is that you will see how to get a picture from the filesystem (or by using the device camera) from within your ADF mobile application Getting started To work with ADF mobile you need to download the JDeveloper 11.1.2.3 and the ADF mobile extension and install both. After installing JDeveloper and adding the ADF Mobile extension, you will be able to create a new ADF Mobile Application. In the new gallery you wil find the ‘Mobile Application’ under the applications node.
Accept all the defaults and the JDeveloper application is created for you. What you see are two projects. One called the application controller, and a second one, the viewController. JDeveloper also adds application-level and project-level artifacts.
The applicationController contains several artefacts such as the Datacontrol definition, files for skinning, and a class called LifeCycleListenerImpl. This class can be used to add your own functionality during the different stages of the application life cycle. In the viewController you only see a file called adfmf-feature.xml. This file is used to add, remove, or edit the application features embedded within the mobile application. At an application level, the adfmf-application.xml file is created, which enables you to configure the mobile application. You will also find application level files that are created for you such as platform specific images for splashscreens and application icons. These can be customized.
That is all you need to get started, and luckily, it is all created for you. Your first simple ADF Mobile Application Lets create a two simple java classes to be our data provider.
and ...
Now create a datacontrol based on the Contacts class.
With the datacontrol in place, it is now time to create the page that will use the Contact collection. Creating features, taskflows and pages Go to the adfmf-feature.xml file in order to add a new feature. This can be done by clicking the plus icon. For now, lets call this feature ‘contacts’.
This only adds an entry in the xml file, but the actual page or taskflow implementing the feature is not created. This is also an action that can be done from within the adfmf-feature.xml file. By clicking the plus icon (you must be on the content tab for the feature) you can pick either AMX page or taskflow. Choose taskflow and continue.
The taskflow editor now appears with the empty newly created taskflow. Now it is time to add view activities to the taskflow. If you are familiar with ADF development, this the exact same approach as if you were building a ‘regular’ ADF application. Just drag the viewactivities from the component pallet onto the taskflow diagram and add navigation between them. In this case I created two viewactivities. One to show the list, and a second on create a picture of the selected contact.
Creating the pages The next step is creating the actual pages. This can be done by doubleclicking the view activities on the taskflow diagram. Start with the list page. In the create page wizard, uncheck ‘both’ action checkboxes. There is no need got these now.
On the list page it makes sense to show the content in a ‘List’ layout. With ADF Mobile and JDeveloper you can create this exactly the way you want. Drag and drop the contact collection from the datacontrol onto the page and select ‘ADF Mobile List View’ from the context menu.
In the ListView gallery you can pick from a lot of different Lists, but for now, just stick with the default. For the list view only display the last name. No need for the firstname, however, if you really want to….. just add it. The result should look somewhat like this:
This page will work if all went according to plan. The next step is to add navigation to the second page. Adding navigation In order to navigate to the second page, and to see the selected trainee on this second page you need to do two things. The page needs to know when to navigate. For that, we can use the action property of the component. Change the action property to “add” which corresponds to the navigation case defined in the taskflow. Either type it, or select it from the dropdown.
Next make sure that the selected row is made available on the second page. For this a setPropertyListener can be used (Hey, you already knew that from your ADF experience). Set the from property to #{row}, and the to property to #{pageFlowScope.row}.
Now create the second page by doubleclicking on the viewactivity in the taskflow editor, or via invocing the new gallery and pick create new ADF Mobile Page (AMX). In the header facet the #{pageFlowScope.row} reference can be used to display the whole name of the selected contact. Now create the second page by doubleclicking on the viewactivity in the taskflow editor, or via invocing the new gallery and pick create new ADF Mobile Page (AMX). In the header facet the #{pageFlowScope.row} reference can be used to display the whole name of the selected contact.
 <amx:facet name="header"/>  
 <amx:outputText value="Take picture of #{pageFlowScope.row.firstname} #{pageFlowScope.row.lastname}" id="ot1"/>  
 <;/amx:facet>;  
Creating the picture This page will be used to take a picture of the contact. This looks pretty complicated but as a matter of fact, it is very straightforward. ADF Mobile ships with a deviceFeature datacontrol. On of the operations in here is the ‘getPicture’. Drag this operation from the datacontrol onto your page, and drop it as a ADF Mobile Button.
In the Edit Action Binding set destinationType to 1 so the image is returned as a fileName, and specify width and height for the image.
You might want to play with the sourcetype. On a simulator this makes no sense, but on an actual device you can invoke the camera by setting sourceType = 1. An action binding is added to the corresponding pagedefinition file. Again, you already know this from regular ADF development.
 <methodAction id="getPicture" RequiresUpdateModel="true" Action="invokeMethod" MethodName="getPicture"  
 IsViewObjectMethod="false" DataControl="DeviceFeatures"  
 InstanceName="data.DeviceFeatures.dataProvider"  
 ReturnName="data.DeviceFeatures.methodResults.getPicture_DeviceFeatures_dataProvider_getPicture_result">  
 <NamedData NDName="quality" NDType="int"/>  
 <NamedData NDName="destinationType" NDValue="1" NDType="int"/>  
 <NamedData NDName="sourceType" NDType="int"/>  
 <NamedData NDName="allowEdit" NDType="boolean"/>  
 <NamedData NDName="encodingType" NDType="int"/>  
 <NamedData NDName="targetWidth" NDValue="150" NDType="int"/>  
 <NamedData NDName="targetHeight" NDValue="200" NDType="int"/>  
 </methodAction>  
Now drop the returnvalue of the getPicture from the datacontrol on your page as an outputtext. Remove that textfield immediately. The Dnd action was only nessecary in order to create a binding for this returnvalue. It can now be used as the source for an component.
 <amx:image id="file" source="#{bindings.Return.inputValue}"/>  
Finally add a button to navigate back to the list page. The page would look like this:
 <?xml version="1.0" encoding="UTF-8" ?>  
 <amx:view xmlns:xsi="<a href="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</a>" xmlns:amx="<a href="http://xmlns.oracle.com/adf/mf/amx">http://xmlns.oracle.com/adf/mf/amx</a>"  
 xmlns:dvtm="<a href="http://xmlns.oracle.com/adf/mf/amx/dvt">http://xmlns.oracle.com/adf/mf/amx/dvt</a>">  
 <amx:panelPage id="pp1">  
  <amx:facet name="header">  
    <amx:outputText value="Take picture of #{pageFlowScope.row.firstname} #{pageFlowScope.row.lastname}" id="ot1"/>  
  </amx:facet>  
  <amx:commandButton actionListener="#{bindings.getPicture.execute}" text="getPicture" disabled="#{!bindings.getPicture.enabled}" id="cb1"/>  
  <amx:image id="file" source="#{bindings.Return.inputValue}"/>  
  <amx:commandButton action="return" text="List" id="cb2"/>  
 </amx:panelPage>  
 </amx:view>  
Deploying and testing Before being able to test the application you need to create a deployment profile. Go to your application properties and select “new deployment profile” and create one for ADF Mobile for iOS. Accept the defaults for now.
Now you can deploy the application to an iOS simulator or device. After deploying to an iOS simulator the application works. Click on the application icon to start the application. The app starts and you will see the list view. Click (or tab on a real device) on one of the names in the list view. The Picture view opens empty with the name of the selected contact in the header. Now you can invoke the getPicture button. .
On a real device the camera can be invoked if you would set sourcetype = camera (or 1), on the simulator, you get to pick an image from the gallery. After taking the picture (or selecting it), the image displays in the application, right where we want it.
I created this application on a Macbook so I can use the iOS simulator to run the application. However, the exact same application will run on an iPhone, iPad if you deploy it to the device instead of deploying it to the simulator. And it will also run on Android devices. The only thing you need to do is create a deployment profile for Android and deploy to the actual device. Footnote This blogpost (originally posted on the amis technology blog) is created under the assumption that you have already installed all SDK’s for Android Development, and the xCode for iOS development. Also all settings for Android and iOS development in JDeveloper need to be set and point to the android SDK and xCode locations. Running on Android Simulators is extemely slow, so you will probably need to connect your device and deploy to it in order to test your application. I will propbably write more on these topics in the near future.

ADF Mobile : Finally released and ready to use

After extensive beta testing oracle announced last week that ADF Mobile is now generally available and can be used to build multi platform on device apps. I finally am allowed to share my knowledge in blogposts and other kinds of publications. Using JDeveloper and the ADF Mobile extension, it is very easy to create apps for both the iOS and Android platform. If you only want to create apps for Android, you don’t need a mac, however if you want to create apps voor iOS you really do need a mac to compile the ADF mobile app for iOS.
ADF Mobile provides a natural extension of enterprise/internet applications to mobile clients by providing tools, services, and infrastructure to protect against technology shifts. An application built with ADF Mobile framework installs on a smart device, renders user interface via HTML5, and has access to device services. This means the programming model is primarily web-based, which offers consistency with other enterprise applications as well as easier migration to new platforms. But the application has access to device services, enabling a richer experience for users than a browser alone can offer. The architecture of ADF Mobile.
A short explanation of the components on the image: The Device Native Container represents an application container or template compiled as device native application binary which provides the run-time environment for an ADF Mobile application to run as an on-device, native application in the mobile device’s operation system (for example, Apple iOS). The Web View is a part of the device native container that uses a mobile device’s web engine to display and process web-based content. In an ADF Mobile application, the web view is the primary mechanism to render and deliver the application user interface. Server HTML represents a web-based user interface that is generated on the server (ADF Mobile browser and Oracle ADF Faces rich client-based pages) and delivered as a Web page to the ADF Mobile application. The Local HTML represents web pages developed using JDeveloper or third-party tools that are directly embedded within an ADF Mobile application. ADF Mobile AMX Views are based on the ADF Mobile AMX technology that delivers a JSF-like development experience to working with an HTML5-based user interface. ADF Mobile AMX views are defined using UI and code editors provided by JDeveloper. These views are embedded into an ADF Mobile application and deployed to a mobile device. At run time, the JavaScript engine in the web view renders ADF Mobile AMX view definitions into HTML5 components. ADF Mobile AMX components are built to deliver a mobile optimized user experience out of box. These components support the device native user experience through extensive animation and gesture support. The ADF Controller is represented by a mobile version of Oracle ADF controller that supports a subset of Oracle ADF task flow components available to a server-based Oracle ADF application. Java provides a Java run-time environment for an ADF Mobile application. This Java Virtual Machine (JVM) is implemented in device-native code, and is embedded (or compiled) into each instance of the ADF Mobile application as part of the native application binary. Managed Beans are Java classes that can be created to extend the capabilities of ADF Mobile, such as provide additional business logic for processing data returned from the server. The ADF Model in an ADF Mobile application supports a subset of business logic components available to a server-based Oracle ADF application. ADF model contains the binding layer that provides an interface between the business logic components and user interface, as well as the execution logic to invoke REST or SOAP-based web services. PhoneGap is an open-source code library that provides a common JavaScript API to access various mobile device services, such as the camera. PhoneGap provides a majority of the device services integration for an ADF Mobile application. Local Data refers to data stores that reside on the device. In ADF Mobile, these are implemented as encrypted SQLite databases. ADF mobile enables you to interact with mobile device services such as the camera, the email client, contacts and more. There is no need for you to know how to interact with the device because ADF mobile uses phonegap to abstract these device specific api’s. On top of that ADF mobile uses a device datacontrol to even abstract phonegap. The device datacontrol can be used in the exact same way as any other datacontrol. You can drag and drop operations from the data control onto your page. In ADF Mobile, data controls behave similarly to the way they work in Oracle ADF. Device data controls appear within the Data Controls panel in JDeveloper, allowing you to drag and drop the primary data attributes of data controls to your application as (text) fields, and the operations of data controls as command objects (buttons). Performing such drag and drop actions will generate standard EL bindings in your application in the appropriate properties for the controls that are created. The normal ADF bindings for those actions (represented by a general DataControls.dcx file, to point at the data control source, and the page bindings, to link the specific page’s reference to the data control) will be present, allowing the runtime to process the bindings when your application executes.