Two-Minute Tutorial 3

TMT3 Add the PhoneGap Barcode Scanner Plugin to a Project, Write an App using Barcode Scanner Technology

This tutorial demonstrates installation of the
PhoneGap Barcode Scanner Plugin, and creates a simple app that uses the plugin to scan and encode (i.e. create your own) barcodes with an Android device.

PhoneGap Plugins (wiki docs here) expose additional access to phone functionality, beyond what PhoneGap JavaScript APIs offer. PhoneGap plugin development is "hybrid development", i.e. native Android (Java) and web app development (JavaScript). The MDS AppLaud plugin enables hybrid development from a single environment.

Prerequisites
  • Installation of the latest MDS AppLaud plugin, see Get Started
  • Complete TMT0 or equivalent (create project, edit files, run app on device or AVD)
  • Android Device (to scan and encode)
  • OR AVD with SD Card Emulation (to encode only, need camera to scan)
  • Basic knowledge of bar codes (QR Code, Data Matrix, UPC, etc.)
Note: The newest version of the barcode scanner plugin does not require a separate installation of ZXing (pronounced "zebra crossing") barcode scanner app. The PhoneGap Barcode Scanner plugin now includes ZXing as a library. Instructions on creating a Library Project in Eclipse are included in this tutorial.

Prep
  • Download and unzip the attached file tmt3.zip
    • index.html - defines page and buttons to run app
    • main.js - all javascript code for scan / encode
    • main.css
  • To learn more about PhoneGap Plugins in general:
  • Download the corresponding version of PhoneGap Plugins from github:
    • PhoneGap 1.4.1 and lower:
    • PhoneGap / Cordova 1.5.0 - 1.8.1:
    • PhoneGap / Cordova 1.9.0: Not Supported
    • PhoneGap / Cordova 2.0+ (e.g. your downloaded version):
A Word on PhoneGap Plugins

The repository phoneGap / phonegap-plugins on github is the canonical place to look for PhoneGap Plugins, and, being on github, collaborations, extensions and contributions are welcomed and easily managed. Android (vs. iPhone or ?) plugins are simple to install, usually consisting of Java and JavaScript files. Plugin APIs and changes to AndroidManifest.xml or res/xml/plugins.xml are described in the plugin's README.md file.

AVD Configuration

A verified AVD configuration (to encode, not scan):
  • Android 2.1+
  • AVD configured with SD Card with 100 MB
Add the Barcode Scanner Plugin to an AppLaud Project

1. Download the Barcode Scanner plugin

Download the plugin from github (IMPORTANT: Select corresponding version as described in Prep step above). The main Download button (labeled ZIP) on github offers the entire plugin bundle. Unpack and locate the Android/BarcodeScanner/ directory to access the plugin files. The top level of the barcode scanner plugin directory looks similar to:
  • assets/ - contains barcode scanner plugin javascript code
  • LibraryProject/ - code for ZXing Barcode Scanner Library project
  • README.md
  • src/ - contains barcode scanner plugin java code
General instructions for using the plugin are in README.md. This tutorial is based on those instructions, but is specific to MDS AppLaud Eclipse projects.

2. Create a new AppLaud project for the App

As demonstrated in the Getting Started tutorial, create a new AppLaud project using the project creation wizard. In the first page of the wizard, Create a PhoneGap for Android Project, select Use Built-In PhoneGap and no UI frameworks. For Project Contents, select Create project from specified source directory, and browse to the directory where the three source files from tmt3.zip are located (index.html, main.js, main.css). These files will be copied into <projectname>/assets/www/ during project creation.

IMPORTANT: AppLaud v1.2.91 offers a choice of PhoneGap / Cordova versions: 1.4.1, 1.5.0, 1.6.1 (don't use 1.9.0 with plugins) or the ability to point the wizard to your own separately downloaded version of Cordova. Select the version you want in this step and make sure to use the corresponding version of the plugin (see Prep step).

Proceed to the next window, Create Android Project, fill in the project name, and proceed to the third window. Select any target in the Select Build Target window, we will be returning to it shortly! In the fourth window, Application Info, fill in your package name and select 7 (Android 2.1) for the Minimum SDK value as shown below.

This may generate a warning about mismatch of the target and SDK versions. Ignore the warning, and return to the previous window (use Back button), Select Build Target. Re-select the build target, selecting the highest API Level offered in your environment. The example below is at API Level 13, yours may be higher.
Select Finish to complete project creation. The new project will have 4 files in /assets/www/:
index.html, main.js, main.css and phonegap-1.4.1.js (or whichever version of PhoneGap you are using).

Refer to TMT0, Section 3a SDK Tools 14 and Above or 3b SDK Tools 13 and Earlier for more details regarding Target vs. Minimum SDK selection.

3. Add the plugin Java code to the App Project 

In the new project, right click on the top level /src directory and select New -> Package to bring up the New Java Package creation window. In the example below, the project name is mytmt3 so the Source folder is
mytmt3/src. Enter the package name: com.phonegap.plugins.barcodescanner as shown below. This package name was specified in the plugin's README.md and must be exactly as below. Click Finish.
Eclipse's Java support
 creates the directory structure needed to support java packages, based on the package name entered here.
The last step is to add the java file to the project. Open the /src directory in the project and right click on the new java package com.phonegap.plugins.barcodescanner. Select Import... and navigate to the directory on your host where src/com/phonegap/plugins/barcodescanner/BarcodeScanner.java is located. Select only
BarcodeScanner.java to be imported, as shown below.
Note: To edit or extend java code, just edit file. Now you can take advantage of
AppLaud's hybrid Java/JavaScript capabilities to extend the API, change messages, or make any other changes to the Java file. The new java code will be automatically built into your project.

When the java file has been successfully added to the project, the src/ directory for project and new package will appear as below.

4. Add the Barcode Scanner and PhoneGap Plugin Javascript to the App Project

Important: By default the project wizard does not assume that PhoneGap JavaScript APIs are needed by an app, therefore the reference to phonegap-1.4.1.js (or whichever version of PhoneGap you are using) is initially commented (out). For this app, it must be included. Remove the commenting around this line in index.html

   <!-- <script type="text/javascript" charset="utf-8" src="phonegap-1.4.1.js"></script> -->

To add the plugin javascript, right click on /assets/www/ directory and Import... the file barcodescanner.js from the directory where the plugin was unpacked. The file barcodescanner.js should now appear in the Project Explorer in the /assets/www/ directory.

Include
barcodescanner.js in index.html with the following line:
    <script type="text/javascript" src="barcodescanner.js"></script>

The final list of included files in index.html should look like this (order of files is important):
    <script type="text/javascript" charset="utf-8" src="phonegap-1.4.1.js"></script>
    <script type="text/javascript" src="barcodescanner.js"></script>
    <script type="text/javascript" src="main.js"></script>

5. Edit the App Project's plugins.xml file

Add this line to res/xml/plugins.xml before the closing plugins tag:
    <plugin name="BarcodeScanner" value="com.phonegap.plugins.barcodescanner.BarcodeScanner"/>
</plugins>
Important: Note that this line must be added before the closing </plugins> tag.

6. Create the Barcode Scanner Library Project

ADT 20 only: In Eclipse, select File -> New -> Android Project From Existing Code.
For Root Directory, Browse to the location of the LibraryProject directory in the Barcode Scanner plugin source code. Select Copy projects into Workspace if you wish. Finish creating the new project. A new library project created this way will be named com.google.zxing.client.android.CaptureActivity.

Older versions of ADT only:  Use File -> New -> Create Android Project as shown below. This example has named the project libBarcodeScanner
Select Next and choose the highest API Level available. At this point you can select Finish to complete project creation, because the library source was already partially configured. This will create the new Android Library Project (not an AppLaud PhoneGap Project) in its current location, and not in your current Eclipse workspace.

 If the project shows an error, you may need to right click on the project to select Properties -> Android and select the highest level API available for your install (see below).

See the Is Library box (above) to verify the new project is a library. If the check box Is Library is not selected, check it now.

This will make the new project available to other projects as a library. No files within the library project
, including AndroidManifest.xml, will be edited. 

7. Add a Reference to the Barcode Scanner Library Project to the App Project

Important: The following two steps refer to the app project (mytmt3 in the example shown) and not the library project (libBarcodeScanner or CaptureActivity in the previous steps).

The next step is to include the new library in the app. Right click on the tmt3 app project (
mytmt3, not the new library project) and select Properties, then Android from the left panel. Select the Add... button to bring up the Project Selection window. The new library project (libBarcodeScanner or CaptureActivity) should appear in the list. Select it and make sure it appears in the properties window. The example below has included the library libBarcodeScanner:

8. Edit the App Project's AndroidManifest.xml file

Add the following to the app project's AndroidManifest.xml file before the closing application tag:
    <!-- ZXing activities -->
    <activity android:name="com.google.zxing.client.android.CaptureActivity" android:screenOrientation="landscape" android:configChanges="orientation|keyboardHidden" android:theme="@android:style/Theme.NoTitleBar.Fullscreen" android:windowSoftInputMode="stateAlwaysHidden">
        <intent-filter>
        <action android:name="com.phonegap.plugins.barcodescanner.SCAN"/>
        <category android:name="android.intent.category.DEFAULT"/>
        </intent-filter>
    </activity>
    <activity android:name="com.google.zxing.client.android.encode.EncodeActivity" android:label="@string/share_name">
        <intent-filter>
        <action android:name="com.phonegap.plugins.barcodescanner.ENCODE"/>
        <category android:name="android.intent.category.DEFAULT"/>
        </intent-filter>           
    </activity>
</application>
Important: Note that the two sections describing the barcode scanner activities are added before the closing </application> tag.

9. Review of App using the Barcode Scanner Plugin API

The sample app simply defines 5 buttons for scanning or encoding
in index.html.
    <a href="#" class="btn" onclick="scanCode();">Scan Code</a>   
    <a href="#" class="btn enc" onclick="encodeText();">Encode Text</a>
    <a href="#" class="btn enc" onclick="encodeEmail();">Encode Email</a>  
    <a href="#" class="btn enc" onclick="encodePhone();">Encode Phone</a>  
    <a href="#" class="btn enc" onclick="encodeSMS();">Encode SMS</a>  

From the plugin's README.md file, we see the plugin provides two methods: scan() and encode() and example javascript for each. The attached main.js file defines the functions for the scan
and encode buttons.


The barcode scan function takes two parameters: success and error handlers.
Upon successful scan, the example app alerts with the scan data as text, scan format (QR, barcode, etc), and cancel status:
var scanCode = function() {
    window.plugins.barcodeScanner.scan(
        function(result) {
        alert("Scanned Code: " + result.text
                + ". Format: " + result.format
                + ". Cancelled: " + result.cancelled);
    }, function(error) {
        alert("Scan failed: " + error);
    });
}
A successful scan will show the scan region and red scanning line as shown at left. Hold the device over the image to be scanned until it locates and focuses on the image. To scan vertical bar codes, hold the device so the red line is horizontal across the bars.

To customize your app, replace the alert call above with your own code. For example, after scanning a UPC barcode, check result.text for the correct number of digits, then send it to your processing function. Another example is to check result.text for the string "http://", then open a browser at that location.

The barcode encode function takes four parameters. The first two are the encoding type and the data to be encoded. The last two are
the success and error handlers.

The first encode example specifies encode type TEXT_TYPE and provides url text in the data field. The encoded text is shown at right:
var encodeText = function() {
    window.plugins.barcodeScanner.encode(
            BarcodeScanner.Encode.TEXT_TYPE,
            "http://www.mobiledevelopersolutions.com",
            function(success) {
                alert("Encode success: " + success);
            }, function(fail) {
                alert("Encoding failed: " + fail);
            });
}
The other three encode buttons show examples of encoding email, phone and sms. Refer to the barcode scanner plugin README.md for a complete list of supported types.

After encoding, tap the device's menu button for options on sharing the encoded data (email, facebook, etc).

Troubleshooting

  • Is phonegap-1.4.1.js included (not commented) in index.html?
  • Is phonegap-1.4.1.js included BEFORE main.js and barcodescanner.js in index.html?
  • Did BarcodeScanner.java get imported into /src/com/phonegap/plugins/barcodescanner/?
  • Did barcodescanner.js get imported into /assets/www/?
  • Is barcodescanner.js included in index.html?
  • Have changes to res/xml/plugins.xml and AndroidManifest.xml been done?
Test the app
  • Sample QR Code
  • Sample Data Matrix Code
  • Encode something, mail it to yourself
  • Scan book or other product's UPC code
  • Lookup UPC databases (some are free) to use with your app

10. Check out TMT3 Part 2 - Add ChildBrowser Plugin and Handler Barcode Scanner Results

January 2012: TMT3 Part 2 builds on this tutorial by adding the child browser and further handling of the scan result.

Looking for an app template that scans and does a whole lot more?

June 2012: PowerApp is a demo app that pulls several technologies into one app.
 
Visit the PowerApp Page for links to source code, demo video and details.

Had trouble with the above or have comments? Let us know on the mailing list or create an issue.

Return to the main tutorial page.

Č
ċ
ď
Elizabeth Baldwin,
Mar 29, 2012, 8:14 AM
Comments