Using Apache Cordova™ for Mobile Apps

Apache Cordova™ is a set of tools and APIs that allow you to target multiple platforms using a single code base. Normally you would write your application in JavaScript, but with FlexJS you can write your application in ActionScript and use Cordova to deploy your application onto many different types of mobile devices. Further, you can use many Cordova plug-ins to enhance your application.

Using ActionScript enables you to write code with less errors than with JavaScript because ActionScript is a strongly typed language with true classes and inheritance. Further, the compiler can detect syntactical and type errors before the code even runs. And, if you are using a FlexJS compatible IDE, code hinting and completion can speed up development.

The first step is become familiar with Cordova is using a simple application which is found in the Cordova documentation, the "Hello, World" sample. Follow this link to get started.

http://cordova.apache.org/#getstarted

The key with Cordova and FlexJS is the www directory that the cordova command creates in the application folder. The www directory contains the actual program that gets run on the device or browser. Since FlexJS creates HTML and JavaScript, you simply replace the contents of the www directory with your FlexJS application. 

Requirements

1. Install Cordova according to the instructions in the Apache Cordova web site.
2. Install the latest FlexJS SDK and kit
3. Set your path to include the ${FLEXJS_INSTALLDIR}/js/bin directory.

Creating the Application

To make things easier, FlexJS comes with an ANT build script called cordova-build.xml located in the FlexJS install directory. This script assumes a particular structure for your files to make it easier to build everything. Follow these instructions to create a FlexJS application to works with Cordova.

1. Create a directory called Demo. The name is important and it should match the name of your application. 
2. Inside the Demo directory, create a directory called src. 
3. Inside the src directory place your FlexJS source files. In this case, copy the lines below into a file called Demo.mxml. Note that this file is named the same as the outer directory.

<mjs:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
                   xmlns:js="library://ns.apache.org/flexjs/basic"
                   xmlns:mjs="library://ns.apache.org/flexjs/cordova"
                   applicationComplete="onDeviceReady()">
    <js:valuesImpl>
        <js:SimpleCSSValuesImpl />
    </js:valuesImpl>
    <fx:Script>
    	<![CDATA[
    		private function onDeviceReady():void {
    			label.text = "The device and application are ready";
    		}
    	]]>
    </fx:Script>
    <js:initialView>
        <js:ViewBase>
			<js:Label id="label" text="Hello, World" width="200" />
			<js:Circle x="300" y="300" radius="50">
				<js:fill>
					<js:SolidColor color="#0000FF" />
				</js:fill>
			</js:Circle>
			<js:Rect x="400" y="10" width="100" height="300">
				<js:fill>
					<js:SolidColor color="#88FF00" />
				</js:fill>
			</js:Rect>
        </js:ViewBase>
    </js:initialView>
</mjs:Application>

For FlexJS Cordova application, the root Application tag's namespace is "mjs" - the Cordova Application element which injects HTML into the resulting index.html file to bootstrap Cordova.

4. Once you've saved the, move one directory back to Demo and run the following command:

ant -f ${FLEXJS_INSTALLDIR}/cordova-build.xml

where FLEXJS_INSTALLDIR is the name of the directory containing the cordova-build.xml file.

IMPORTANT: You must have ${FLEXJS_INSTALLDIR}/js/bin in your path. In that directory is the mxmlc command that will build the JavaScript version of your FlexJS application; the mxmlc command in the ${FLEXJS_INSTALLDIR}/bin directory will not do this.

When this ANT script runs, it will create a Cordova application called Demo (the name of the outer directory) in a sub-directory called app (app/Demo) and automatically include the Android platform.  Once the Cordova application has been made, the ANT script then builds your FlexJS app into JavaScript and deposits it into a sub-directory called bin (bin/js-debug) and automatically replaces the Cordova app's www directory (app/Demo/www) with the JavaScript version of your FlexJS application.

When finished, your Demo directory will look like this:

Demo/
    src/Demo.mxml (your MXML source)
    bin/js-debug (the Javascript result of compiling Demo.mxml)
    app/Demo (the Cordova application with Android platform installed)
    app/Demo/www  (copy of bin/js-debug, runnable via Cordova on an Android device or simulator).

Running the Application

At this point you can run the Cordova application using the ANT script with the run target:

ant -f ${FLEXJS_INSTALL}/cordova-build.xml run

You can also run the application using the cordova command line by going into the application directory (app/Demo) and running cordova run.

In the example Demo.mxml application, the Label component displays the initial text, "Hello, World". Shortly after starting up, the Label's text is replaced with "The device and application are ready". Most Cordova applications are written to wait for a Cordova event, "deviceReady". FlexJS receives this event internally and dispatches "applicationComplete" at that point so you know the application is ready to go.

ANT Options and Target

The cordova-build ANT script has a couple of other targets and options:

Tips

If you need to change your FlexJS application code source (MXML or ActionScript files), simply re-run the ANT command with the cordova-build.xml file.

Debug vs. Release

As stated earlier, you can use the js-release code for your Cordova application. The advantage is that it is much smaller than the js-debug version, but it will not be debuggable. If you are using the js-debug version, you can attach to it using the Google Chrome browser and debug it reasonably well.

https://developer.chrome.com/devtools/docs/remote-debugging

Using Android Studio

This section covers using Android Studio as part of your development process. If you deploy to an iOS device you will want to use Xcode.

The platforms/android directory of the Cordova project (step 2) can be opened from Android Studio as an Android project. Android Studio will analyze it and make some IDE-specific files to track it. When you do make a change to your FlexJS application, copy it (step 4) and rebuild it (step 6), Android Studio will detect that change and ask you to re-sync. After that you can re-deploy the changed app to the device or emulator.