User's Guide
PhoneGap
Getting Started with Mobile Apps

Getting Started with Mobile Apps

IN THIS PAGE

Overview
An Overview Of The Development Process with Cordova and Alpha Anywhere
Choosing a Build Platform
Building your first app with Alpha Anywhere
iOS Provisioning
- Generating Certificates for Ionic Appflow
- Generating Certificates for Cordova CLI
More Functionality, Using 3rd Party
Ajax Callbacks
Videos

Description

Building native mobile applications with Alpha Anywhere

Overview

Alpha Anywhere is a comprehensive HTML5 development framework that on it's own can build powerful mobile HTML5 web applications that look and feel like native apps. Once created, a web application on a mobile device is launched within the web browser that is supplied with the device. iOS devices typically use Mobile Safari, while Android devices can use a variety of browsers with Chrome or some derivative of Chrome typically being the native browser. Since the app is running within the browser, it is limited to the capabilities that the browser exposes.

But suppose you want to access some of the native features of the phone or tablet. For example, let's say you want to allow your users to access a bar code scanner, which incorporates the devices camera and some special image processing software, that sits locally on the device, that can decipher a QR Code or a barcode and send that encoded information back to your web application for a possible database lookup or submission to a web service to lookup specifics on a book or an inventory part. You can do that with Cordova and that is just the tip of the iceberg.

Cordova allows you to access ALL of the functionality of the mobile device. You are really only limited by your imagination and skills.

Cordova includes a large set of core and third party plugins that expose all sorts of native functionality. A variety of the plugins support iOS and Android so that you can target a wide range of mobile phones and tablets.

And best of all, Cordova allows you to build true native apps for iOS and Android devices, apps that you can easily distribute through the numerous app stores.

An Overview Of The Development Process with Cordova and Alpha Anywhere

You will use the Alpha Anywhere IDE to develop a base UX component that may contain all of the code and data that is required for your Cordova application, or you may choose to create a base UX component that loads data and additional components from a remote server (assuming the phone or tablet has Internet access).

When you are ready to convert your base UX component into a Cordova app, the integrated Cordova App Builder is used from within the Alpha Anywhere IDE to:

Generate the Cordova app
Generate all required Cordova configuration options, including the addition of required Cordova plugins
Convert the UX Component into a set of files that contain all of the standalone HTML, CSS, JavaScript and additional assets (images, etc.) required to build a single page Cordova app that is installed and loaded locally from the device. This ensures that the initial page can provide a fast, workable and pleasant user experience, even when the device is offline.
Package the content so that it can be uploaded to the Ionic Appflow build service or built using Cordova CLI.

Once the app is built, you can:

Install the native app for testing on iOS and Android devices

Choosing a Build Platform

Alpha Anywhere offers several solutions for building and distributing native mobile apps.

Build Option

Description

Ionic Appflow

Ionic Appflow is a cloud-based service that allows you to build Cordova apps for iOS or Android. Ionic Appflow is easy to use and does not require any extra hardware (i.e., a Mac.)

To build iOS or Android apps, developers publish application updates to a GitHub project connected to Ionic Appflow. Ionic Appflow automatically creates a new version of your application when a change is detected. When your app is ready to ship, you can publish directly to the Google Play and Apple App stores.

Alpha Anywhere works with Ionic Appflow by generating the application build files to publish GitHub. You will need a GitHub account and, at a minimum, a paid Ionic Appflow Launch account.

See Ionic Appflow for more information.

Cordova CLI

Cordova CLI provides a command-line interface for creating iOS and Android applications. It is supported on Mac and Windows and requires installing Cordova CLI and the native app development tools for your target platform(s).

Alpha Anywhere works with Cordova CLI to create an Xcode or Android Studio project used to build a native mobile application for iOS or Android, respectively. Alpha Anywhere packages your application files and a script that describes the required plugins and resources needed to build the mobile app. The script is run with Cordova CLI to create the Xcode or Android Studio project. The generated project can then be opened in Xcode or Android Studio to build, test, and deploy your application to the iOS or Android app stores.

Cordova CLI offers the most flexibility for building cross-platform mobile iOS and Android applications. While Ionic Appflow is built on Apache Cordova, the service only allow you to test your app on a phone or tablet. When created with Cordova CLI, you gain access to device emulators and a wide range of tools for testing your iOS and Android applications before deploying them to physical devices. It takes a little time to become familiar with the Cordova CLI process, but it's worth the effort.

See Cordova CLI for more information.

Alpha Launch

If building native apps seems daunting, consider starting with Alpha Launch. Alpha Launch is a free application available in both the App Store and Google Play that you can use to distribute your apps. Apps distributed using Alpha Launch run as native mobile apps without the need for extra accounts or tools like Android Studio and Xcode.

See Alpha Launch to get started with Alpha Launch.

Building your first app with Alpha Anywhere

It is assumed that you are familiar with Alpha Anywhere and know how to build a UX component for a mobile device. You should already be familiar with the concepts of a Panel Navigator, Panels, Buttons controls, etc. If you are not familiar with these terms, it would be best for you to work through a number of the tutorials available prior to attempting to build Cordova apps with Alpha Anywhere.

Building a Simple Test App
To verify you've got everything setup and working properly, we're going to build a very simple Cordova app that contains a Panel and a button that when tapped, initiates a native beep tone. This will work on both Android and iOS devices. We will build the test UX component, generate a Cordova app from that component, and finally, install the app on an Android device (or Android emulator).
Installation on an iOS device requires that you setup an Apple iOS Developer Account.
Building the Test UX Component
In Alpha Anywhere, from the Web Projects Control Panel, click New > Web Component > UX > Global Templates > Panel Card With Header, Title & Buttons.
On the Controls pane, delete the Panel Header Buttons and Tab Stop Controls, leave the Static Text control, and change the static text property to Cordova Test.
Delete Panel Header Buttons and Tab Stops
Set the Panel Header Alignment to Center.
Add a Container below the Panel Header.
Set the Container alignment to Center.
Set the Container width to 100%.
From Other Controls, select a Button and insert the button into the Container.
Set the Button Text property to Native Beep.
Set the Button Width to 150px.
Click on Live Preview. Your UX component should look like the image below.
Switch back to design mode and select the button control. In the property grid, find the JavaScript Touch event for click and select. Next add new action to assign an Action JavaScript to the button.
Pick the PhoneGap category on the left column and the PhoneGap - Notification Action on the right column.
Alpha Anywhere previously integrated with PhoneGap Build, which Adobe shut down on October 1, 2020. PhoneGap was built on top of Apache Cordova, and all features named for the now defunct build service work with Cordova apps.
Select the Beep Notification Type from the combo box. Leave the beep count parameter at 1. (Note: this parameter is ignored on iOS devices.)
Once you click OK you can view the JavaScript generated by the Action JavaScript builder.
If you open the Cordova documentation site at https://cordova.apache.org/docs under the Reference > Plugin APIs > Dialogs, navigator.notification.beep you will see the sample code is quite similar to the Action JavaScript generated code. If you are comfortable with JavaScript, you can look through the Cordova documentation and use the samples to add your own JavaScript to any button or event in your own UX components.
Save the component and name it Cordova1. We will use this component within the Alpha Anywhere integrated Cordova App Builder as the basis for the native app which will be installed on the phone or tablet.
You can now close the UX component builder and we will move on to generate the Cordova application within your web projects folder.
Using The Cordova App Builder
On the Web Projects Toolbar, click the Cordova button, this will launch the Cordova App Builder.
The Cordova App Builder contains a large number of options and properties for Cordova app customization. Within the Cordova App Builder, you select the App Build Target, target platform(s) to build, numerous properties for the app name, app description, app version, author, etc. You also select the Cordova plugins to include in the project and many other options. In this simple application, we are only going to be using a few of the many options available.
Notice the Project Type property is New, indicating that there are no pre-existing Cordova assets in the Web Projects Directory. If a previous project existed, the Project Type would indicate Existing and the builder would skip the step of generating the Cordova scaffold application, which is created in a PhoneGapProjects folder in the Web Project Directory.
In the Cordova Project Type, choose your desired App Build Target: CLI (Cordova CLI) or Ionic Appflow.
In the Cordova Project Platforms section, check the Android box. This triggers an Android project build. It also enables a set of Android specific options within the Cordova App Builder. This guide will demonstrate configuring and building an Android project since Android does not require the submission of developer credentials to install the app on a device.
Under the Alpha Cordova Project Build Options, select the Initial UX Component that was previously built, Cordova1(UX). Once selected, the Generate Cordova Asset Files checkbox will be automatically checked. Leave it checked because we want to generate the Cordova app from the Cordova1 UX component.
App Icon and Splash Screens
Check Generate Image Resource Files and select the Alpha app-icon-1024x1024.png for the Master Icon from the PhoneGap/appIcons folder, included in the Alpha Anywhere executable directory.
The Cordova App Builder will generate all of the required app icons for the targeted platforms at all required sizes and resolutions for each. The app icon is the icon that is installed and displayed on the devices home screen.
When building your own app icons, you should build the largest size that is required by all of the targeted devices. A 1024px x 1024px icon is the largest size required for iOS and Android devices. If you were building for Windows Phone 8, a 173px x 173px icon would be best.
Since Alpha Anywhere is generating all of the required icons from the one icon selected, it's best to generate images that are smaller in size from a larger icon as this preserves the image resolution, eliminating pixelation of the smaller image. The same is true when generating the app splash screens, which you can leave blank for this test application.
In the App Options section, set the Application ID to the reverse domain name of your app.
In this test app we've used com.alphasoftware.myApp but you can use whatever you would like. If you plan to distribute your app through an app store, the App Id must match the bundle identifier of your application.
In this example, the Allow Access Origin property is set to * which will allow your app to access all other URL's on the Internet. The app doesn't actually require setting the Allow Access Origin property, however it is a common requirement to load data from other web services, the Alpha Anywhere Application Server, or possibly to load a web page in the inApp Web Browser. If the URL is not specified in the Allowed Access Origin Property, the request will be blocked. This is a common point of failure so you need to be aware of this setting from the first app you publish.
Android Only Section
In the Android Only section, check the Enable Notification Features. When the App is installed on an Android device, the user will be made aware of the features the app requires and they may choose to allow or abort the app installation.
Required Core Plugins Section
All native functionality is handled through plugins, even the core Cordova functions. Our app only uses the Notification plugin (it beeps), so make sure the Notification plugin is checked.
Build your App
At this point, enough information has been provided to build the Cordova application. Click Save & Launch Cordova CLI Builder (if Cordova CLI is selected) or Save & Build for Ionic Appflow Builder (if Ionic Appflow is selected) and the Cordova App Builder will create the application (if it did not previously exist), generate the required build scripts, and package up all application resources so it can be build using the desired build platform.
Follow the instructions in Cordova CLI or Ionic Appflow for building your app.
Save & Launch Cordova CLI Builder
Save & Build for Ionic Appflow

Testing your App

Here we see the test app successfully loaded on a

Tap the Native Beep button and you should hear a beep tone.

Congratulations, you've just successfully built and installed a native mobile app!

iOS Provisioning

If you want to build apps for the iPhone or iPad, you will need an Apple Developer Certificate and a Provisioning Profile to install the signed IPA file on an iOS device. You need 3 things:

A Developer Certificate with private key (*.p12)
A provisioning profile (*.mobileprovision)
The password for the private key

The Developer Certificate is added to the Mac's keychain using Keychain Access. It is used to digitally sign your code.

The Provisioning Profile is a file that will exist on the development device(s) and the Mac. It will reference a Developer Certificate, an App ID (a development profile can use a wildcard) and a list of device ID's that the app can be installed on for testing.

Generating Certificates for Ionic Appflow
We recommend using the Cordova Builder iOS Certificate Genie to generate the required certificates if you are using Ionic Appflow. The genie does not require owning a Mac. It does require, however, that you have an Apple iOS Developer Account.
If you need to setup an Apple iOS Developer Account, visit http://developer.apple.com.
Generating Certificates for Cordova CLI
If you want to build your iOS app using Cordova CLI, you must have a Mac running OSX and have an iOS developer account.
If you do not have a Mac, you can setup a virtual Mac at http://www.macincloud.com.
If you need to setup an Apple iOS Developer Account, visit http://developer.apple.com.
To install an app on your development device you need to get a valid developer certificate from Apple.
Apple has extensive documentation on setting up all of the resources required to get a valid developer certificate at http://developer.apple.com.
The interface to the developer site is constantly changing, so we recommend referring to Apple's documentation on creating certificates.

More Functionality, Using 3rd Party

This example app incorporates native notifications, device information, inAppBrowser, bar code scanner, and the flashlight plugin. It also demonstrates a technique to call Apple's Search API web service, parse the JSON results and format the results in a HTML template within a Panel Card. No Application Server is required.

We will use these app files to build a more advanced Cordova app in this section.

Download the zip, appExample1.zip, and extract the files. Copy the files, appExample1.a5wcmp and background.png, into an existing or new Web Project within Alpha Anywhere.

Open the appExample1 UX component and click on Working Preview.

appExample1 UX Component, Working Preview

This application includes seven (7) buttons on the first Panel Card that call native Cordova functions. Since these buttons are calling native Cordova functions, they will not work in Working or Live Preview on a desktop browser. The app needs to be installed on an actual device (or one of the emulators) to work.

Beep calls the native Cordova navigator.notification.beep function, which will cause your device to generate a beep sound.

Vibrate calls the native Cordova navigator.notification.vibrate function. Not all devices support vibrate. You will need to make sure your phone/tablet is set to vibrate on ring in order for this function to work on your device.

Native Alert calls the Cordova navigator.notification.alert function, which displays a native alert dialog as opposed to a browser "alert" dialog. On iOS devices you will notice the dialog title does not contain the referencing page (which in this case will be index.html). A callback function is supported and is called when the user closes the alert dialog. In this case, the callback function displays a standard javaScript alert dialog. You will most certainly notice a difference between the native alert dialog and the JavaScript alert dialog on an iOS device. On an Android device, there is little difference.

Native Confirm calls the Cordova navigator.notification.confirm function, which displays a native confirm dialog. Similar to an Alert in many ways, the confirm dialog adds the ability to display two (2) buttons and passes the one based index number (1 or 2, instead of a typical zero based array, which passes 0 and 1) in the callback when a button is pressed.

Native Prompt calls the native Cordova navigator.notification.prompt function, which displays a native prompt dialog. The native prompt dialog can be used to prompt the user to enter any information required and can capture a user entered string. Two (2) buttons can be used to display

Flashlight calls the Cordova third party plugin flashlight function. This function will turn on the camera light on the back of a phone for three seconds. If the device does not include a camera light, a callback will display a native alert dialog to indicate that a light is not available on the device.

Scan and Search iTunes calls the Cordova barcodescanner third party plugin which calls the cordova.plugins.barcodescanner.Scan function. This function will bring up a barcode scanner which uses the devices camera and some very clever image processing software to allow you to scan the barcode on a book and return the results to a success (or fail) callback function.

ISBN Barcode for Programming in Objective-C 2.0, 2/e

In the example component, the success callback function makes a client side call to Apple's iTunes Search API where the text result of the barcode scan is submitted to iTunes Search for an ISBN lookup. If the ISBN from the book is available within iTunes, the descriptive and pricing information will be displayed on a second PanelCard that will perform a slide transition into view.

Panel Footer

iTunes Info Button will navigate to the second PanelCard that contains a freeform HTML control that will display iTunes related information after a books ISBN has been scanned.

Help Button navigates to a third panel that will display application help. The help content is contained within a freeform HTML control, that initially contains an empty div. When the app is fired up, the client side onInitializeComplete event is used to populate the div with the help HTML, which is defined in the JavaScript Functions of the component. This technique allows the definition of the components HTML content to be centralized and not tied to a specific control.

There's a lot going on here!

Many techniques were used to create this component. There are many ways to accomplish something in Alpha Anywhere. We hope you learn a few tricks from tearing this component apart.

Let's take a look at how this component was built.

Click on the Design tab.

appExample1 UX Component, Design

The component includes a programmatic Panel Navigator that includes a static Panel Header. The Panel Header container alignment is set to centered and it's width by convention is 100%. That will center the text.

The first Panel Card includes a Container (for centering the buttons) and a series of buttons (with a width defined of 150px) and a Panel Footer with two (2) buttons that navigate to the other panels. It also includes a a background image, which I've tailored to an iPhone 5 in portrait orientation.

Let's take a look at the click event handler on the Beep button.

A PhoneGap Action JavaScript Notifications function has been assigned.

Click on Edit Action

Notice the notification type selected is Beep and the Beep Count is 1.

Per the Cordova documentation, the beep count is ignored on iOS devices.

Click OK and let's take a look at the JavaScript that the Action JavaScript builder generated.

This is the JavaScript that runs when the click event on the button fires.

As you will see later on, I've written the JavaScript to interact with the third party plugins for the Flashlight and the Bar Code Scanner used by this component. Keep in mind that by referring to the Cordova documentation, and writing a little bit of JavaScript, you can do anything with Alpha Anywhere and Cordova today.

Close the JavaScript Preview Dialog and take a look at the abstract click handler on the Flashlight button.

Notice the dialog is set to Text Mode, which allows you to enter the JavaScript directly. The fireFlash() function is called will be called when the click event fires. The fireFlash function is defined in the component's JavaScript functions.

Cancel out of Edit Click Event Dialog and open the JavaScript Functions panel.

Scroll down to the fireFlash function definition.

The fireFlash function is called when the Flashlight button is clicked

First a check is made for the existence of the window.plugins object (which the Flashlight plugin JavaScript files create) and if the object is not defined, an alert is displayed and the function returns. This will prevent an error in the app and allows you to test the component in Working Preview. This technique is used throughout the button event handlers.

Next a test is done to determine if the mobile device physically includes a photo flash and if so, the flashlight is turned on for 3 seconds.

Remember, the Cordova functions are not going to work on a Desktop Browser. They are ONLY designed for use on a mobile device.

If the device does not include a photo flash, a native notification alert dialog is displayed to let the user know the plugin is working, but a flash is not available on the device.

If you take a look at the third party plugin documentation for the Flashlight plugin, you will see the sample code which looks quite similar.

See https://www.npmjs.com/package/cordova-plugin-flashlight and look at Usage.

Next, take a look at the click event handler for the Scanner button. Here the scanBarCode function is called. This function is also defined in the component's JavaScript Functions.

The scanBarCode function does a quick check for the cordova object. If this object does not exist then either we are not running within Cordova on a mobile device or the bar code scanner third party plugin is not installed. Since either condition will cause a JavaScript error, an alert dialog is displayed and the function exits gracefully.

Next the cordova.plugins.barcodeScanner.scan function is called. Below is a snippet from the Bar Code Scanner plugins documentation page on GitHub. As is common with many Cordova plugins, the call to the scan function is asynchronous and requires two callback functions, one for success and one for fail.

As in the example code, the success and fail functions are anonymously defined within the scanBarCode function. This technique is very common for asynchronous JavaScript functions and is used throughout the Cordova example code. You can choose to define independent external functions and simply call those functions if you wish.

The Scan Success Function

Our anonymous success function includes a result parameter which will contain a result object if the bar code scanner is able to read a bar code. From the Cordova example code it is easy to see the result object contains:

result.text: contains the string encoded within the barcode or the QRCode
result.format: contains a string with the barcode format
result.cancelled: contains true if barcode scan is cancelled

A Note on JavaScript Style
In this component, we've used a style for writing JavaScript following these basic rules:
- All globals are assigned to the {dialog.object}.appVars object.
- All function parameters are defined in lowercase, no leading characters.
- All variables that are local to a function are defined with a leading underscore example: _result.
There is no right or wrong technique, just guidelines. Google has a decent JavaScript Style Guidelines available at https://google.github.io/styleguide/javascriptguide.xml. Whatever style you or your team develop, try to be consistent.

Notice the result object is stored to an instance variable (previously defined) called {dialog.object}.appVars.scannerResult. This is required because the iTunesCallback function requires access to this information after a call is made to the Apple Search API. If the ISBN is NOT found in the iTunes store, the callback will display an alert that will reference the scanned ISBN and the barcode type. This information is in the result object.

In this example component, all of the globals are defined as part of the {dialog.object}.appVars object. This is referred to as an instance variable since the variables are assigned to a child object (appVars) of the UX component instance {dialog.object}. They are in fact global variables to the object instance.
This technique keeps the components global variables contained within the object designated by the template placeholder {dialog.object} and keeps the global namespace clean, an important consideration in JavaScript programming.
You may wonder why the placeholder {dialog.object} is used instead of a placeholder named {ux.object}. {dialog.object} comes from a legacy naming convention, used in previous versions of Alpha Anywhere. The UX was was derived from the legacy dialog component.

At the top of the function, if result.cancelled is true the user cancelled the scan and a Cordova native alert dialog is presented.

If a result is returned, the scanned text is submitted to Apple's Search API for a lookup in the iTunes store.

There are a number of ways to do this but in this case the new {dialog.object}.ajaxCallbackCrossDomain method is used to make the request.

The iTunesCallback function using the new template method of Alpha Anywhere

The callback function that will process the returned result is called iTunesCallback.

Since the result from iTunes may or may not contain user ratings, a test is made to see if the data returned contains a variable named data.results[0].userRatingCount. If the data.results[0].userRatingCount variable exists, a template that includes ratings is used, otherwise, a template that excludes ratings is used.

The templates are defined as instance variables and are part of the {dialog.object}.appVars object. This is done for efficiency. You could define the templates within the iTunesCallback function but it's more efficient to define the templates once as a global and reference them when needed.

Performance and efficient memory use on mobile devices is important.

Panel Card 2 has a freeform HTML container that contains a single div, <div id="iTunesInfo"></div>. Once the HTML is derived from the template, the iTunesInfo div is populated with this HTML and Panel Card 2 is transitioned into view.

The Scan Fail Function

The scan fail function is another anonymous function that accepts an error parameter. If the scan fails for any reason, this function will display a native alert dialog, indicating the error.

The UX Component onInitializeComplete Event

Looking at the Client Side onInitializeComplete event, the initial html is loaded into the iTunesInfo div from a call to the loadDefault_iTunesInfo() function. The same technique is used to load the appHelp div which is defined in a free form HTML container on Panel Card 3 by calling the loadAppHelp() function.

This is a technique that allows you to define all of the HTML within the JavaScript functions. It provides a central location for all of the HTML, rather than defining the HTML within each container, which makes it harder to manage and edit the HTML used within your app. All you need to define within the HTML freeform container control is the div with an id that you will later populate with what may be dynamic content as in the case of the HTML we derive from the templates used within the barcode scan function.

Local CSS Styles

This component's styling was derived from the standard iOS style, although it looks quite different.

A few local style CSS classes have been defined to change the look quite significantly.

From Properties, scroll down to the CSS section and click on the button to edit the local CSS definitions.

Five custom CSS classes have been defined. These classes are assigned to the specific elements in the CSS Class property of numerous controls within the UX component property grid.

These include:

.blueBtn: defines the CSS style for all of the buttons used in the component
.infoText: defines the CSS style for the information in PanelCard 2
.bluePanelHeader: defines the CSS style for all of the Panel Card Headers
.bluePanelBody: defines the CSS style for the Panel Card body in Panel Card 2 and Panel Card

The .blueBtn CSS was built using one of the many CSS button generators that are freely available on the web. Google "CSS Button Generator" and you will see many options.

After generating your style, copy it into the CSS Editor Code Panel. Class names can be added to various controls in the UX using the control's class name property.

bluePanelBody class assigned to PANELCARD_2

Launching the inAppBrowser

The inAppBrowser plugin allows an app to load an external web page within the app without having to exit the app and load a mobile browser. Think of it as a browser within your app. Typically an Action Sheet appears from the bottom of the screen that contains the browser.

The help panel HTML includes a button with a link to https://www.alphasoftware.com. The ontouchend event is used on mobile devices to eliminate a 300ms delay that mobile browsers add to the onclick event.

The ontouchend event calls the launchInAppBrowser function defined in JavaScript functions

launchInAppBrowser(url) function

The inAppBrowser displaying www.alphasoftware.com within the app. The Done button in the lower left corner will close the inAppBrowser.

The HTML templates that are used to present the data returned from the Apple Search API also contain a button that links to the Apple iTunes Info.

While the button is configured to launch the inAppBrowser, the iTunes App on iOS devices has registered a Custom URL Scheme which launches the iTunes App (if it is not already running) and displays the link in iTunes, instead of launching the inAppBrowser.

On Android devices, the inAppBrowser is used. As such, the label on the button needs to be dynamically assigned. This is handled in the iTunesCallback function.

If the app is running on an iOS device, the button label is assigned "View in iTunes App". If the App is running on an Android device, the button label is assigned "View on iTunes Site".

Notice the addition of a new variable, .btnLabel to the data.results[0] object. You will see this variable in use within the templates that process the JSON results from the Apple Search API.

It is this level of detail that helps your app stand out.

For more info on iOS Custom URL Schemes see https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Introduction/Introduction.html#//apple_ref/doc/uid/TP40007072-CH7-SW50.

Programmatically Calling JavaScript Actions and Using a Function to Generate a Dynamic Message

The component contains one JavaScript Action that is called from the myConfirmCallback function. This callback is fired when the 'Yes' or 'No' button is selected from the native.notification.confirm function which is tied to the Native Confirm button.

The confirmationAlert Action calls the Action JavaScript PhoneGap Notifications and displays a native alert. The Dialog Message is populated from an instance variable.

Since this JavaScript Action is going to be called programmatically from a callback function, the message to display needs to be stored in an instance variable. This should be clear from the code below which is tied to the confirmationCallback. Notice how {dialog.object}.appVars.msg is set to either Yes or No, depending upon which button the user clicks in response to the Cordova navigator.notification.confirm dialog. Also notice the use of the {dialog.object}.runAction method to run the confirmationAlert JavaScript action.

Let's take a look at the Native Confirm button click event.

This Action JavaScript uses a number of advanced techniques that are worth understanding.

The JavaScript callback function name is myConfirmCallback. That is the function we just looked at. It is passed a btnIndex which indicates the button the user clicked. Since the myConfirmCallback calls another JavaScript Action (confirmationAlert), the result of the button selected is stored in an instance variable allowing reference to it from the confirmationAlert JavaScript.

Using a JavaScript function to return a dynamic message

The Dialog Message is populated from a JavaScript function called getConfirmMessage(). This allows the message to be tailored to the mobile platform that the app is running on.

As you can see in the getConfirmMessage() function, the message content will vary for iOS and Android devices.

The getConfirmMessage function returns a dynamic message, based on the mobile platform at runtime

The deviceready event

In Javascript functions, you will see an event listener added for the deviceready event. This event is fired after Cordova initialization is complete. It can be helpful to use this event to enable Cordova related controls within your app. In this case, the onDeviceReady function uses a Cordova native.notification.alert to display device related information in a native dialog.

Ajax Callbacks

Ajax callbacks are essential to create, edit, and update the data stored within a UX component. In this section, we modify the Demo Mobile App included with Alpha Anywhere to run as a Cordova app that communicates with an Alpha Anywhere Application Server, storing and retrieving photos from a backend database.

Up until this point, the UX components we have used have been communicating with outside web services, like the Apple Search API.

Alpha Anywhere makes it easy to tie a UX component to a wide variety of backend databases through the Alpha Anywhere Server. Some popular SQL database engines include MySQL, SQL Server, PostgreSQL, Oracle, DB2, etc.

In order to communicate with an Alpha Server, you MUST publish the initial UX component to an Alpha Anywhere Server and you MUST provide a proper URL to locate the server from within the Cordova app installed on the mobile device.

In this section, we will modify the image upload capability of the sample mobile application supplied with Alpha Anywhere to use a native camera/image control and the image will be uploaded from the device to an Alpha Anywhere Server. This is done with an Ajax callback.

Click on Recent Workspaces | Sample and Tutorial Workspaces and select the Demo Mobile Application.

Once the files are copied, select Chapter 16 from the project list and right click on the component named Lesson16_Start.a5wcmp and Select Duplicate. Enter Lesson16_Start_pg.a5wcmp to create a duplicate copy of the component that will be used for the Cordova modifications.

Open the Lesson16_Start_pg UX component. If prompted, enable prerendering of the component.

Select the button labeled Photo in the UX Builder.

We are going to modify the Action JavaScript associated with the virtual click event on this button.

Select Click Button To Edit the Image Upload Action JavaScript.

Make sure Mobile Settings are configured to use Cordova. Ensure Using Cordova is also checked.

The picture source should be Camera. Click OK and save the component. You have just made all of the changes required to this component to use the native camera controls within a Cordova app.

In order for a Cordova App, installed on a mobile phone or tablet to communicate with an Alpha Anywhere server, there are a number of considerations:

What is the IP address of the server?
What protocol and port are being used by the server?
What is the name of the directory within the webroot (if any) on your Alpha Anywhere Server that the component is published?
What is the name of the component that the Cordova app is based?
Is the Same-site cookie policy set to "Unset" on the Application Server?
Did you publish the component and resources for the Cordova app to the Alpha Anywhere Application Server?

We'll look at each of these questions in detail.

Determining IP address of the server

For Cordova apps, it's best to use the IP address of your server rather than relying on DNS name resolution simply because it is faster. Your mobile users will never see this IP address when running your app.

Your testing will initially be done using Live Test. Live Test runs the app locally on the Development Server, a server that runs on your machine and is perfect for testing and debugging Cordova apps on your mobile devices.

To determine the IP address in use on your machine, open a command prompt at enter ipconfig <enter>. Your screen will look similar to the image below:

Here we can see the IPv4 Address assigned to this machine is 192.168.1.251. Your machine's IP address will vary. Make a note of this value. For initial testing on a mobile device, it is important that the mobile device be on this same network/sub-net as the development server. You want to make sure your phone or tablet is tied in to the same wireless router as your development server.

Determining the protocol and port of your development server

Click on Web | Development Server from within the IDE to display the Development Server Settings.

Make a note of the Server Port, and the status of the Enable SSL checkbox. In this example, the port in use is 81 and SSL is not being used. When SSL is not in use, the protocol used is HTTP. When Enable SSL is checked, the protocol used is HTTPS.

Determining the server publishing directory

The UX component that serves as the basis for the Cordova application (as specified within the Cordova App Builder Genie) must be published to the Alpha Anywhere Application Server in order for the Cordova application installed on the mobile device to make callbacks to the Alpha Anywhere Server. To determine the publishing location, from within the Web Projects Control Panel, open the Publish settings dialog.

In the example below, the component is being published to a directory named test. Make a note of this directory.

If the Target Folder is left blank, the component will be published to the document root, identified in the previously discussed Server Settings dialog.

Verify the web project properties

Before publishing the component or generating the Cordova App, it is a good idea to take a look at your Web Project Properties to ensure that you are only loading the JavaScript Libraries that you actually need for your component. In our case, we don't need any additional libraries. The idea is to keep the client side payload as small as possible. From the Web Projects Control Panel select Project Properties. The Run-time Properties should match the dialog shown below.

Specifying the name of the component

We will use the Cordova App Builder to enter the name of the component and the application server details.

Launch the Cordova App Builder from Web Projects Control Panel | Cordova.

Under the Alpha Cordova Project Build Options select the Initial UX component, Lesson16_Start_pg. Make sure the Generate Cordova Asset Files checkbox is checked.

You need to specify the URL to communicate with the Alpha Anywhere server in the URL For All Ajax Callbacks property. You must specify the protocol, IP Address, port number (if you are using anything other than the default, port 80) and if publishing to a directory within the A5Webroot, the name of that directory.

In the image shown below, the protocol in use is http, the IP address is 192.168.10.21, the port in use is 81 and the component was published to the test directory within the A5Webroot. It is designated as [http:// 192.168.10.21:81/test].

Adjust Cordova App Builder Properties for Android Features and Required Plugins

You will not need to select all of the required plugins required for native camera access and image uploads (but feel free to verify the plugins are in fact selected) because the plugins have been automatically selected for you. This occurs when you use Action JavaScript to include this native functionality in your component.

For Android apps, make sure to enable the Camera and Notification features.

Build the App with Cordova CLI or Ionic Appflow

Assuming you have setup the Cordova CLI or Ionic Appflow for building mobile apps, you can save and build your application. However, the app will not run properly (callbacks will fail) on your mobile device unless you publish the component designated in the initial UX Component property to the Application Server.

Publishing the component to the Application Server

From within the Web Projects Control Panel, right click on the component named Lesson16_Start_pg.a5wcmp and select Publish (Local Webroot).

Install and Test

The app is now ready for testing. You should be able to install the app on your mobile device, take a picture and save the image to the Alpha Development Server.

Videos

To learn more about building mobile apps with Alpha Anywhere, check out these videos.

Many videos in this section show using PhoneGap Build to build mobile apps. PhoneGap Build is no longer available. Use Ionic Appflow, Cordova CLI, or Alpha Launch.

Using Ionic Appflow with Alpha Anywhere To Build Cordova Apps

Ionic AppFlow is a service offered by Ionic for building iOS and Android applications. It is tightly integrated in the Alpha Anywhere Cordova Genie.

In this video, we'll walk you through the process of building Alpha Anywhere applications with Ionic Appflow.

Watch Video