How-To: build a hybrid app using PhoneGap Builder

Ruben Goncalves

Discussion

Before we start...

Probably you read (or not) my 2 previous posts on How-To: build a hybrid Android app and How-To: build a hybrid iOS app and if you thought "C'mon this way too complex, for the time that I have", this article is for you!
Remember IntelliWarp, let's try to accelerate the creation hybrid apps as well! (Jump to PhoneGap things!)

In attachment you may find a zip containing:

www.zip - example zip to create your hybrid apps
PhoneGapIntegration eSpace - with the PhoneGap version 2.4.0

Build PhoneGap where magic happens

The Agile platform is great for both building and changing fast, while the mobile 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!

Introduction

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 Build PhoneGap

I think that there's no better description for Build PhoneGap than the one on their homepage:
"Take the pain out of developing mobile apps.

Simply upload your HTML5, CSS, and JavaScript assets to the Adobe® PhoneGap™ Build cloud service and we do the work of compiling for you."

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 with you the PhoneGapIntegration 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.

SetupPhoneGap Action: You will need to call this action if you’re to use the Web Blocks from PhoneGapIntegration 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 PhoneGap enabled app. It’s recommend that you use this action in the system event Session Start.

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

IsPhoneGap 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 PhoneGap. Before your application can call itself a hybrid application there’s a few more steps to take.

Note: currently this helper eSpace is only has the PhoneGap scripts to iOS and Android.

Building up your hybrid App

The first step to use Build PhoneGap is to register. If you go free you can only generate (and keep generating one app at a time:
After going for the free, you can login (or create an account) on either Adobe or Github
After login, you can start to transform your app, you're entitle to either connect to your github account, where you have the html, js, css stored or you can upload a zip file:
Apparently, not exactly what we wanted... but it is!
Choose to upload a zip file. This zip will contain the following files: a. index.html: this html file will be the entry point for our application
b. config.xml: this xml is crucial, in this file we are going to indicate the name of the application, it's description, version, author name, icons, splash screens and plugins to use!
c. icon.png
d. other folders and files
After uploading you just say Build app:

Now comes the gooooood part!
Once the build is done, it may take a few minutes, you end up with:
You endup with 6 native apps: iOS, Android, Windows8 Mobile, Blackberry, webos (HP) and Symbian. All that in one click....

Notice, that you still need to sign your code! (iOS apps don't compile without it).

Finally, this post from the Build PhoneGap team, might help you. I've also prepared a sample project, with everything that you need (simple configurations, etc) for you to start building up hybrid apps, find it in attachment! (Just change the URL to load your OutSystems application!)

Note: the PhoneGap version presented in the PhoneGapIntegration eSpace is 2.4.0, which currently is still not supported in Build PhoneGap. Please change the scripts accordingly to the version that you choose.

Next Steps

---> I'll tell you how to use plugins! [c'mon, give me some time to write it!]

OutSystems&BuildPhoneGap.zip

22 Feb 2013

Hans Bruins

Is it possible to enhance the resolution of the pictures? It is a little bit hard to read. TIA.

29 Mar 2013

Alexandre Costa

Congratulations, very good post.. now I will try to transform my first mobile app in outsystems in PhoneGap.

25 Jun 2013

Victor Salvalagio Pereira

Hi.

Is it possible to access the camera through outsystems application? And why do u need the PhoneGap.js file?

Thanks.

22 Oct 2013

Hans Bruins

@Victor
Yes, you can access the camera in Outsystems through the phonegap/cordova layer.

23 Oct 2013

Victor Salvalagio Pereira

I tryied to do the example on phonegap documentation but the funcions are never called:

var pictureSource; // picture source

var destinationType; // sets the format of returned value

// Wait for PhoneGap to connect with the device

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

// PhoneGap is ready to be used!

function onDeviceReady() {

pictureSource=navigator.camera.PictureSourceType;

destinationType=navigator.camera.DestinationType;

}

The onDeviceReady is never called. Do I need to add some other library?

23 Oct 2013

Elísio Simão

Staff

Victor,

Answering to the question "Why do u need the PhoneGap.js file?" the PhoneGap.js is used to make the bridge between the JS that your putting into your Outsystems app and the native code that is needed to run.

On an OutSystems app, you don't need to add the EventListener JavaScript, you can check if you are in "PhoneGap mode" by passing a parameter like ?IsPhoneGap=True, in the URL on the html file loader you add to PhoneGap zip, and then just load PhoneGap.JS when you need to use it.

To trigger the the camera, use a button or a link (with the onclick extended propertie, if you don't want to submit don't forget to end with a "return false;") to call the java script function that gets the picture and then you can associate the picture URL(Binary Data) to an element or pass it to ServerSide, by using an intermidiary element (like an input).

On attachement you can find and example that is using the CameraCapture plugin, and an implementation of the plugin in the PhoneGapIntegration. Let me know if it helps.

Regards,

Elísio

CameraCapture.zip

23 Oct 2013

Victor Salvalagio Pereira

Hi Elísio,

I'll take a look at the example.

Thanks

23 Oct 2013

David Farinha

Staff

Hi Rúben,

This was an amazing post and a great help to me.
Thanks.

Best Regards,
David Farinha

23 Apr 2014

Julius Dickens

Hi All,

I follow the tutorial and and having an issue getting the android app to engage my webapp on a Galaxy Note 4. Ive changed the index.html file to the following:

	<!DOCTYPE html>

	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<meta name="format-detection" content="telephone=no" />
	<meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" />

	<title>Hybrid App made easy</title>
	<script type="text/javascript" charset="utf-8">
	var serverName = "www.oasischicago.com";
	var appName = "chicago/home.aspx";
	var targetLink = "https://" + serverName + "/" + appName + '?isCordova=True';

	/* When this function is called, PhoneGap has been initialized and is ready to roll */
	function onDeviceReady() {
	var networkState = navigator.network.connection.type;

	if((networkState == Connection.NONE) \|\| (networkState == Connection.UNKNOWN)){
	navigator.notification.activityStop();
	navigator.notification.confirm(
	'Please turn on 3G or Wifi and retry.', // message
	onDeviceReady, // callback to invoke when retry is pressed
	'Network Unavailable!', // title
	'Retry' // button Label
	);
	} else {
	window.location = targetLink;
	}
	}

	function onBodyLoad() {
	document.addEventListener("deviceready", onDeviceReady, false);
	}

	</script>
	</head>
	<body onload="onBodyLoad()">
	<div>Loading application....</div>
	<script type="text/javascript" src="phonegap.js"></script>
	</body>
	</html>

Any obvious mistakes here?

Julius

27 Jul 2016

Community GuidelinesBe kind and respectful, give credit to the original source of content, and search for duplicates before posting.

See the full guidelines