Before we start...

This is going to be a quite long post, however if you follow it, you'll be able to transform your web app into a hybrid app!
Special Kudos to Pedro Cardoso and Pedro Sencio which helped me to write this post!

In attachment you may find a zip containing:
  • Index.html - example file of how your web app could be launched.
  • CordovaIntegration eSpace - with the Cordova version 2.4.0

OutSystems & Androida love made (easy and) possible
The Agile platform is great for both building and changing fast, while the Android OS transformed our daily life, by providing us the means to have more tools to help us.
In this "How-To", I'll try to bring together the best of the two worlds! Allowing you to bring your (web) app to the next level functionality and client satisfaction!
As you know, building up and OutSystems mobile app is (plain) easy, however through a web app we (so far) are not able to access to certain functionalities (camera, contacts, etc). With your Web App transformed into a hybrid App, you’ll have the opportunity to access the native capabilities of the mobile device like the camera and many others. Besides the access to these capabilities you can download plugins that can be used to enhance your application with different and innovative capabilities. And note that although your users will be installing a local application in their devices, you will still be running your OutSystems application in a Platform Server, with all the goodies you’re used to: service center, reporting, logging, etc. 
Building your OutSystems Mobile App
Let the Agile Platform help you do your magic.
Introducing Apache Cordova
Apache Cordova is a platform for building native mobile applications using HTML, CSS and JavaScript.
Read & learn more in the official website.

Transforming your web app into a Hybrid app
In order to facilitate the building of a hybrid application, and for you to be able to include native functionality in your app, I'm sharing wiht you the CordovaIntegration eSpace, that presents some shortcuts in the first step of this process: the inclusion of the needed JavaScript and the linkage with the available Cordova plugins. This is a producer eSpace that has some public actions and Web Blocks that you’ll be using in your own app.

SetupCordova Action: You will need to call this action if you’re to use the Web Blocks from CordovaIntegration eSpace. This action will set some session variables that enable you to know the type of device the client is using, either Android based or iOS based. Besides the device type, this action also sets a variable that indicating the access as being made from a Cordova enabled app. It’s recommend that you use this action in the system event Session Start.

IncludeCordova webblock: The IncludeCordova Web Block job is to include the correct Cordova JavaScript library for your device.

IsCordova Action: If your application is to be accessed from a mobile web browser and as Hybrid application, we advise you to make use this action to control the layout of your screens.

And that’s it for the integration eSpace! By now you should have your application ready to be used from a web browser and to take advantage of the native functions when running in Cordova. Before your application can call itself a hybrid application there’s a few more steps to take. 

Wrapping in Cordova to Android

To wrap your application in Cordova to use in Android, you’ll need to install some tools that will be used to build and test your app. After this step, you’ll have your application ready to submit to Google Play Store.

Java Runtime Environment: For the next steps, it’s required that you have installed the Java Runtime Environment (JRE) or the Java Development Kit (JDK). If you neither installed, it’s recommended that you install the JRE.

Android SDK: The first step is to download and install the Android SDK. This will give you access to APIs and others. Notice that a version of the Eclipse came along with Android SDK. The other important part is the access to the virtual devices where we will debug our hybrid app.

In the end of the installation you will have an option to run the SDK Manager. Go with it. In the SDK Manager, besides the items selected by default, you may choose a given API.
If it is not select, you must select the Android SDK Platform-tools inside tools. Then click “Install 8 Packages…”
When finished, move to the next step.
If you now try to create a new project, you will see that you have Android projects.

If you open now the eclipse, you'll specific projects for Android:

Cordova Installation: This is not an installation. It’s more a project template. Download the latest version of Cordova and unzip it. We will use it to start a new project. 

Creating a new project: So now you have a native application static HTML app (just image you do…), but what you really want is your great OutSystems mobile app running as a hybrid app. Let’s move on.
In the root directory of your eclipse project create two folders: libs and assets/www.
Unzip the Cordova file you’ve downloaded and copy cordova-x.x.x.js to assets/www and cordova-x.x.x.jar to libs. Since we’re working for Android you must copy the files from <unzipped folder>/lib/android.

You will end up with something like this:

The file cordova-x.x.x.jar must appear in your Java Build Path. If it’s not, make sure it does:

Copy the xml folder from the Cordova download to the folder /res of your project.

Now you need to change the activity of your project. An activity is a Java Class that extends Activity. You must change that super class to be DroidGap. Next we will change the line setContentView inside the onCreate method to call super.loadURL. You will get something like this:

The index.html file we have in www is as simple as it follows:

           Simple Example

If you now run your project you will get the following in your Android virtual device.

So now we have an index.html running inside Cordova. Very important: notice the usage of the previous tip we’ve gave you. This is actually running as native, but it’s an HTML file. Great! But… what we want is to have our OutSystems Mobile App running in there so!
First of all, since we will be accessing our app over the network, you will have to change the AndroidManifex.xml that’s in the root of your project. You will be including the support-screens and uses-permissions section that you can see in the image below:

Then let’s add some muscle to our simple HTML file and load our sales app.
First include the Cordova JavaScript file:

     <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>

Add an event to the body element that adds a Cordova event that fires when the device is ready. Then add a function to hook on that event. This function checks for connectivity and redirect whenever possible:

If you run your project now you can see that our mobile app is loaded, but e careful, it’s running inside a browser! You will not have access to the native functionality from the device:

To be able to run it as native, you will have to change a configuration file that controls some security settings. Find the file cordova.xml that’s inside the folder res/xml in your Eclipse Project. Find a line like the one below and change it to whatever feels right to you.

    <access origin="*"/> <!-- allow local pages -->

After changing the access rights run your application. You will then see your application running as Hybrid. This way, you will have access to the native functions of the Mobile Device

Notice that we’re always checking if we’re running in native mode. Don’t take it for granted!

Hope that this post helps to deliver awesome hybrid apps!

Next Steps

---> I'll tell you how to use plugins! [c'mon, give me some time to write it!]
---> "Wait... this way too much work...", I'll tell how to use the awesome PhoneGap Builder!

Excelent!!!!!! Good job Ruben!
You guys are awesome :-)
thanks Ruben,great post.
Very good post!!
A video for the same will really help.
Thanks. Good Post
This would be really useful if updated to use Android Studio.  I appreciate it was written originally in 2013
Is there an equivalent of this post for iPhone?  
Hi Curt, Yes there is: Hope this helps! ;)
Is there any post/tutorial like this, to create and use from scratch a new Cordova plugin like the ones we have on forge, using a customized version of OutSystems Now - Now Plugin Email Composer, Now Plugin InAppBrowser, etc...
And also one about how to customize and use my own version of OutSystems Now, beside the tutorial present on OutSystems Now that is not so clear in some steps.