Getting Started with PhoneGap

Chariot Day 3/2/13

Don Coleman
Chariot Solutions
@doncoleman

PhoneGap is an open source solution for building cross-platform mobile apps with standards-based Web technologies like HTML, JavaScript, CSS.

Cordova

vs

PhoneGap

PhoneGap Supports Many Platforms

iOS, Android

Windows Phone, Blackberry

Symbian, Bada, WebOS

Tizen, FirefoxOS

PhoneGap embeds a web view in a native app

JavaScript API

Access Device Features

Accelerometer
Camera
Capture
Compass
Connection
Contacts
Device

Events
File
Geolocation
Globalization
Media
Notification
Storage

http://docs.phonegap.com/en/2.5.0/index.html
http://phonegap.com/about/feature

Your app is a native app

PhoneGap does not provide a UI

Can I wrap any website in PhoneGap and magically have a mobile app?

NO!

Single Page App

How do I get started?

Download

http://phonegap.com/download

Unzip archive

move somewhere like /usr/local/phonegap-2.5.0

Do you have platform tools installed?

Xcode

Android SDK

Visual Studio

BlackBerry Webworks SDK

Demo

iOS


$ cd /usr/local/phonegap-2.5.0
$ cd lib/ios/bin
$ ./create ~/foo com.example.foo Foo 
$ cd ~/foo
$ ./cordova/emulate

Android


$ cd /usr/local/phonegap-2.5.0
$ cd lib/android/bin
$ ./create ~/foo com.example.foo Foo 
$ cd ~/foo
$ ./cordova/run

PhoneGap Getting Started Guides

http://docs.phonegap.com/en/2.5.0/guide_getting-started_index.md.html

So we created a project, now what?

The www directory is just a web project

How does it work?

index.html


<!DOCTYPE html>
<html>
    ...
        <script src="cordova-2.5.0.js"></script>
        <script src="js/index.js"></script>
        <script type="text/javascript">
            app.initialize();
        </script>
    </body>
</html>

index.js


var app = {
    initialize: function() {
        this.bindEvents();
    },
    bindEvents: function() {
        document.addEventListener(
            'deviceready', this.onDeviceReady, false);
    },
    onDeviceReady: function() {
        // your code here
    }
};

Camera


navigator.camera.getPicture( 
    cameraSuccess, cameraError, [ cameraOptions ] );

http://docs.phonegap.com/en/2.5.0/cordova_camera_camera.md.html

API Call


navigator.camera.getPicture(
    onSuccess, 
    onFailure, 
    { 
        quality: 50, 
        destinationType: Camera.DestinationType.FILE_URI 
    }
);

Callbacks


function onSuccess(imageURI) {
    image.src = imageURI;
}

function onFailure(message) {
    alert('Failed because: ' + message);
}

Permissions


<uses-permission 
    android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

index.html


<div>
    <div>
        <img id="image"></img>
    <div>
    <div>
        <h1 id="cameraLabel">Camera</h1>
    <div>            
</div>

index.js


var app = {
    initialize: function() {
        this.bindEvents();
    },
    bindEvents: function() {
        document.addEventListener(
            'deviceready', this.onDeviceReady, false);
    },
    onDeviceReady: function() {
        cameraLabel.addEventListener(
            'touchstart', app.takePicture, false);
    },
    takePicture: function() {
        // ...
    }
};

index.js


takePicture: function() {
    navigator.camera.getPicture(
        function(imageURI) { // success
            image.src = imageURI;
        }, 
        function(error) { // failure
            console.log("error");
        }, 
        { // options
            quality: 50,
            destinationType: DestinationType.FILE_URI,
            targetWidth: 320,
            targetHeight: 320,
            allowEdit: true,
            saveToPhotoAlbum: false
        }
    );
}

Demo

Lots of other APIs

http://docs.phonegap.com/en/2.5.0/index.html

But PhoneGap doesn't do
[insert your feature here]

Plugins

Extend PhoneGap

https://github.com/phonegap/phonegap-plugins

Plugins aren't a Hack

PhoneGap is built out of plugins

PhoneGap NFC

https://github.com/chariotsolutions/phonegap-nfc

Android, BlackBerry 7, BlackBerry 10, Windows Phone 8

Installing a Plugin

Clone git repo

Copy Java files to project

Copy JavaScript files to project

Edit config.xml

Edit AndroidManifest.xml

Edit index.html

Plugin Specification

https://github.com/alunny/cordova-plugin-spec

plugman

A command line tool to distribute and package plugins for use with Apache Cordova

https://github.com/imhotep/plugman


$ plugman
Usage
---------
Add a plugin:
	plugman --platform  --project  --plugin 

Remove a plugin:
	plugman --remove --platform  --project  --plugin 

List plugins:
	plugman --list


$ plugman --list
BarcodeScanner - Cross-platform BarcodeScanner
ChildBrowser - ChildBrowser plugin
Facebook-Connect - Official plugin for Facebook Connect 
GAPlugin - Google Analytics Plugin
KeychainPlugin - Keychain Plugin for Apache Cordova
NFC - Near Field Communication Plugin
PushPlugin - Push Notification Plugin for iOS & Android
TestflightPlugin - TestFlight Plugin for Apache Cordova

    
plugman --platform android --project . --plugin NFC

Demo

Create a project


$ cd /usr/local/phonegap-2.5.0/lib/android/bin
$ ./create /tmp/nfc com.example.nfc Nfc

Install PhoneGap NFC


$ cd /tmp/nfc 
$ plugman --platform android --project . --plugin NFC

index.html


<script type="text/javascript" src="js/phonegap-nfc.js">
</script>

index.js


deviceready: function () {
    nfc.addNdefListener(app.onNfc);             
}

index.js


onNfc: function(nfcEvent) {
    var tag = nfcEvent.tag,
        records = tag.ndefMessage,
        payload,
        message;
    
    if (records[0]) {
        payload = records[0].payload;
        message = nfc.bytesToString(payload);
        navigator.notification.alert(message, null, "NFC");            
    }
}

Troubleshooting

read the log output

ensure code is valid with jshint

Web Inspector

Ripple

http://emulate.phonegap.com

Weinre

http://debug.phonegap.com

Other ways to debug

Managing code

across multiple platforms

and other cool stuff

cordova-cli

npm install cordova -g

fruitstrap

Install and debug iPhone apps without using Xcode

https://github.com/filmaj/fruitstrap

medic

Continuous integration setup for Apache Cordova

https://github.com/filmaj/medic

Fil Maj will be speaking about
cordova-cli and medic at ETE

http://goo.gl/0uYwX

PhoneGap Build

http://build.phonegap.com/

Questions?

Thank You

Don Coleman

@doncoleman

http://don.github.com/slides/2013-03-02-chariot-day