Using Cordova Plugins: Difference between revisions

From NSB App Studio
Jump to navigation Jump to search
Line 252: Line 252:


You can access the Back and Menu buttons on Android devices which have them. (contributed by Fabio Pontel)
You can access the Back and Menu buttons on Android devices which have them. (contributed by Fabio Pontel)
Add this to PhoneGap config.xml
Add this to PhoneGap config.xml
<pre>
<pre>

Revision as of 18:51, 3 February 2014

This Technote explains how to use the PhoneGap API with AppStudio apps. PhoneGap provides some function calls which are not available from AppStudio. In this tech note, we'll demonstrate some of the PhoneGap Plugins with provide these functions. The full list is here.

The sample code is based on PhoneGap 3.1 or higher.

The code for this sample is installed with AppStudio in the 'Libraries' sample folder.

Overview

Depending on platform, the plugins can include:

  • Accelerometer
  • Camera
  • Capture
  • Compass
  • Connection
  • Contacts
  • Device
  • Events
  • File
  • Geolocation
  • Globalization
  • Media
  • Notification
  • Splashscreen
  • Storage


  • Barcode Scanner
  • ChildBrowser
  • Generic Push
  • Google Analytics

Some of these (such as Accelerometer, Camera and Geolocation) can also be done using AppStudio without PhoneGap.

The easiest way to compile your app using PhoneGap is to use the Build Native App on the Run menu. For more information on installing and compiling with PhoneGap, see these two tutorials:

In this Technote, we'll look at sample code for 4 of these areas. That should be enough to get you started on the others. You can only do limited testing on the desktop for these API functions since they are are not available on the deaktop. Use "Start in Desktop Browser" to check the layout of your form, but do not expect any of the PhoneGap API functions to work.

You can use this function to test if you are running as a compiled PhoneGap app:

If typeof(cordova)<>"undefined" Then
   MsgBox "Running in PhoneGap"
Else
  MsgBox "Running in browser"
End if

Device Information

PhoneGap adds a new runtime object called device which holds useful information about the device. The elements of it are:

device.name The name of the device, i.e. "Bob's iPhone".
device.phonegap The version of PhoneGap.
device.platform The type of device, i.e. "iPhone"
device.uuid The unique number of the device.
device.Version The version of the OS that is running.

Here is some sample code:

Function butGetInfo_onclick()
  s="Device Name:" & device.name & vbCRLF
  s=s & "PhoneGap Version:" & device.cordova & vbCRLF
  s=s & "Platform:" & device.platform & vbCRLF
  s=s & "UUID:" & device.uuid & vbCRLF
  s=s & "OS Version:" & device.version
  Textarea1.value=s
End Function

To use this plugin, you need to add this line into the PhoneGap Configxml in Project Properties:

<gap:plugin name="org.apache.cordova.device" />

PhoneGap has additional documentation here. Be sure to read what quirks each device has.

Camera

The Camera API will return a picture from the camera, the photolibrary, or a saved photo album. It can return the picture as a file URI or as a base64 encoded string. Start by setting the options:

quality Integer from 0 to 100.
destinationType 0: base64 encoded string, 1: file URI
sourceType 0: Photo Library, 1: camera, 2: Photo Album
allowEdit Allow simple editing. true or false.

You will also need to define a function to be called when the operation is complete, as well as a function in case the call fails. In the following sample, we set up the options, then call navigator.camera.getPicture. Following that, we have the functions for successful and unsuccessful returns.

Function butTakePicture_onclick()
  options={quality : 75, _
    destinationType : 1, _
    sourceType : 1, _
    allowEdit: true}
  navigator.camera.getPicture(onPictureReturned, onPictureError, options)
End Function

Function onPictureReturned(ImageURI)
  Image1.firstChild.src=ImageURI
End Function

Function onPictureError(message)
  MsgBox "Failed because " & message
End Function

To use this plugin, you need to add these lines into the PhoneGap Configxml in Project Properties:

<gap:plugin name="org.apache.cordova.camera" />
<feature name="http://api.phonegap.com/1.0/camera"/>

PhoneGap has additional documentation here. Be sure to read what quirks each device has.

Contacts

With PhoneGap, you can find or create contacts. This sample will look up everyone in the Contacts list named "Bob". First, we need to set up our options. We'll create a ContactFindOptions object, then set its filter property to "bob". Next, we specify which fields we want to look for in the fields variable. The list of fields is here.

You will also need to define a function to be called when the operation is complete, as well as a function in case the call fails. We can then call navigator.contacts.find.

The call to .find will return an array with 1 element for each name that matched. You can see how many matches there were in contacts.length. Here is how the code looks:

Function butContacts_onclick()
  options = new ContactFindOptions()
  options.filter="bob"  'nothing will return if you don't have a bob.
  options.multiple=True
  fields = ["displayName", "name"]
  navigator.contacts.find(fields, onContactsFound, onContactsError, options)
End Function

Function onContactsFound(contacts)
  s=""
  For i = 0 To contacts.length -1
    s=s & contacts[i].name.formatted & vbCRLF
  Next
  Textarea1.value=s
End Function

Function onContactsError(message)
  MsgBox "Failed because " & message
End Function

To use this plugin, you need to add these lines into the PhoneGap Configxml in Project Properties:

<gap:plugin name="org.apache.cordova.contacts" />
<feature name="http://api.phonegap.com/1.0/contacts"/>

PhoneGap has additional documentation here. Be sure to read what quirks each device has.

Barcode Scanner

In PhoneGap configxml, add the following line:

<gap:plugin name="com.phonegap.plugins.barcodescanner" />
<feature name="http://api.phonegap.com/1.0/camera"/>

Your configxml property will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<widget 
xmlns = "http://www.w3.org/ns/widgets"
xmlns:gap = "http://phonegap.com/ns/1.0"
id = "com.nsbasic.{id}"
version = "{version}">

<name>{title}</name>
<description>{description}</description>

<preference name="phonegap-version" value="3.1.0" />
<gap:plugin name="org.apache.cordova.camera" />
<gap:plugin name="org.apache.cordova.device" />
<gap:plugin name="org.apache.cordova.contacts" />
<gap:plugin name="com.phonegap.plugins.barcodescanner" />

<feature name="http://api.phonegap.com/1.0/camera"/>
<feature name="http://api.phonegap.com/1.0/contacts"/>

(etc)

Finally, here's how the BASIC code to call the scanner will look:

Dim scanner
Sub Main()
  scanner = cordova.require("cordova/plugin/BarcodeScanner")
End Sub

Function butBarcode_onclick()
  scanner.scan(BarCodeSuccess, BarCodeFail)
End Function

Function BarCodeSuccess(result) 
  Textarea1.value = "We got a barcode" & vbCRLF & _
    "Result: " & result.text & vbCRLF & _
    "Format: " & result.format & vbCRLF & _
    "Cancelled: " & result.cancelled
End Function

Function BarCodeFail(Error) 
  Textarea1.value = "Scanning failed: " & Error
End Function

File API

Function uploadFiles(fileURI)
  Dim options, ft
  options = new FileUploadOptions()
  options.fileKey="file";
  options.fileName=Mid(fileURI(1, InStrRev(fileURI.lastIndexOf('/')+1))
  options.mimeType="text/plain"
  options.chunkedMode = false
  var params = new Object()
  options.params = params
  ft = new FileTransfer()
  ft.upload(fileURI, "http://UrILink", win, failUpload, options)
End Function
'win and failUpload must also be defined

Android Back and Menu Buttons

You can access the Back and Menu buttons on Android devices which have them. (contributed by Fabio Pontel)

Add this to PhoneGap config.xml

<gap:plugin name="org.apache.cordova.device" />
Sub Main()
  document.addEventListener("backbutton", onBackButton, False)
  document.addEventListener("menubutton", onMenuButton, False)
End Sub
 
Function onBackButton()
    MsgBox ("Back Button pressed")
 End Function
 
Function onMenuButton()   
  MsgBox ("Menu Button pressed")
End Function

Converting AppStudio Apps to PhoneGap 3

PhoneGap 3 is a major update to PhoneGap. The integration of 3rd party plugins has been greatly improved: now it is easy to use them in PhoneGap Build projects. The PhoneGap API file has been converted into a number of separate plugins, reducing memory requirements. Finally, support for BlackBerry, WebOS and Symbian has been dropped.

1. Add the following line into PhoneGap Configxml in Project Properties:

<preference name="phonegap-version" value="3.1.0" />

At some point, this will not be needed: PhoneGap Build should default to the current version.

2. Add the plugins you are need into PhoneGap Configxml. Before, all the PhoneGap API functions were contained in a single file. Now, by declaring the ones you need, only the required ones are loaded:

<gap:plugin name="org.apache.cordova.camera" />

3. Third party plugins are much easier to use now: they work very much like the PhoneGap Plugins:

<gap:plugin name="com.phonegap.plugins.barcodescanner" />

You no longer need to include JavaScript files (like barcodescanner.js) in your app. This is done automatically.

4. Make sure the features you use are identified so the user can give permission before first launching the app:

<feature name="http://api.phonegap.com/1.0/camera"/>

5. If your app does not require any permissions, put this line into configxml:

<preference name="permissions" value="none"/>

6. Review your PhoneGap Configxml and make sure it has everything you need. Look at the current sample in Submitting to the iOS App Store and Submitting to the Google Play and Amazon Stores. The format of the configxml will not update automatically to the new format.