Sunday, December 23, 2018

Mobile Support - Cordova

Now that we have a stable client / server framework configured in our development environment, it is time to add mobile support. Cordova (or Phonegap as it was previously called) is a perfect choice for this. It provides a collection of hardware interfaces for most devices as well as all the required build scripts for Android, IOS and Windows. I will be focusing on Android and IOS but you could certainly add others if your needs require them.

Cordova

First we will install the Cordova CLI.

  1. Open a command prompt in the root of our project folder.
  2. Run command 'nvm use 10.14.0'
  3. Run command 'npm install cordova -g'

Just like the Aurelia CLI, we want to install the Cordova CLI as a global package. This is necessary to manage the project structure.

Now it is time to create our skeleton Cordova project.

NOTE: For the remainder of this blog I will assume you already have a command prompt open in the root project directory and have run the 'nvm use' command.

  1. Run command 'cordova create  applewood com.your_name_here.applewood  Applewood'

The parameters for the create command are discussed in detail here. The parameters are not critical to the project success. They are saved in a configuration file and may be edited in the future. The create command builds a skeleton cordova project in a sub directory named in the first parameter. If you have a look at the root director of our project you will see the new applewood folder.

Next, we want to merge our skeleton cordova project into our master project.
  1. Open the root project in a file explorer.
  2. Open the new applewood directory in a second file explorer.
  3. Copy all sub directories from the applewood directory to the root directory
  4. Copy .npmignore from the applewood directory to the root directory.
  5. Copy config.xml from the applewood directory to the root directory.
  6. DO NOT COPY package.json file! This would overwrite your existing package.json file and that would be catastrophic because you would lose all the root project package information. 
  7. Delete the applewood folder from our project.
Our root project folder should look like this:


Platforms

Next we need to add our required cordova platforms to our project.
  1. Run command 'cordova platform add browser' 

  2. Run command 'cordova platform add android'

  3. Run command 'cordova platform add ios'

Note: It is important to include the browser platform. This platform creates a shim file that we will use to simulate a mobile environment during the development process. This is useful to test our code as well as avoid the pesky and annoying browser errors that are typically associated with developing mobile code in the browser on your desktop. A little more about this later. 

Plugins

Next we need to add a couple of cordova plugins for basic device support and a splash screen.
  1. Run command 'cordova plugin add cordova-plugin-whitelist'
  2. Run command 'cordova plugin add cordova-plugin-device'
  3. Run command 'cordova plugin add cordova-plugin-splashscreen'
If you desire any other plugins you could add them now. You can always add plugins at any time during the development cycle.

Test Project in Browser

We should be able to test run the cordova project now.
  1. Run command 'cordova run browser'

A new browser should open displaying the default cordova project


You should also open the Dev Tools (right click / Inspect or press F12) and make sure there are no errors reported in the console.

Now that we have a running cordova project we need to do a little housekeeping.

Source Control

When you add or remove platforms or plugins to the project, the configuration information is saved in a file called config.xml in the root of your project. Just like the NODE packages that are saved in the node_modules folder, we are not concerned about including the Cordova platform or Plugin packages in our projects source control. These are files required by the build scripts to support the various platforms and hardware we are targeting during deployment.

NOTE: The platforms and plugins folders contain content that intentionally is not included in the source code repository. This means that when you clone a project from the repository into your working folder you must populate these folders before you can use the project. This is done by opening a command prompt in the working folder and running a command to fetch and populate the folder with the required packages. For our project do the following:
  1. Open command prompt in root of the project folder
  2. Run command 'nvm use 10.14.0'
  3. Run command 'cordova prepare'
You must do this every time you clone a project from the repository to a working directory!

We need to modify the .gitignore file to exclude these folders from our source control. We also want to exclude the www folder from our source control. The www folder contains a copy of the client code for our project and is dynamic in nature, which means it gets rebuilt after every change to the client code. A little more about this later.
  1. Add a new file called README.md to the www folder. (You can copy this file from the Smoke House Project www folder if you wish)
  2. Open .gitignore file in your code editor.
  3. Add a line to exclude the platforms directory.
  4. Add a line to exclude the plugins directory.
  5. Add a line to exclude the www directory contents.
  6. Add a line to include www/README.md file.


NOTE: We use the README.md file as a placeholder in the www folder. It tells GIT to save the www folder as part of our project. If we do not add this placeholder, GIT automatically will remove the www folder from our source control. Cordova checks to see if the www folder exists to determine if this project is a valid cordova project. If the folder is missing the Cordova CLI will report that this is NOT a cordova project and you will not be able to execute and Cordova CLI commands from the command prompt.

Android Project

One of the nice features of the Cordova CLI is that it creates an Android project. You can open that project in Android Studio (assuming you have it installed).

If you do not have Android Studio installed I highly recommend you install it and get a starter project configured and running on your computer before trying to run this project. You can do this on either a Windows or MAC computer.
  1. Open Android Studio.

  2. Select 'Open an existing Android Studio Project'

  3. Select '\platforms\android' from your working project root.

  4. If you see the Android Gradle Plugin Update - DO NOT UPDATE! - Select 'Don't remind me again for this project'. The cordova CLI build scripts use a specific gradle version and upgrading will cause multiple build failures! 
  5. Run the application. Click the green arrow in the toolbar. You may have to configure and select a device on the next screen depending on your project settings.

  6. The Android emulator should start and present our project.

If you have all of the above configured and working we should be able to build and launch the Android project from our command prompt.
  1. Run command 'cordova run android'
The project will build and the same emulator should launch!

IOS Project

Now it is time to switch gears. Unfortunately you cannot build or run an IOS application on a Windows machine. So I have swiveled my chair and have picked up this blog on my MAC.

The Cordova CLI also builds a valid XCODE project. Pretty slick!

If you do not have XCODE installed I highly recommend that you install it now and go through the process of configuring and running a sample project before attempting to run this project.

NOTE: You will need to set up code signing. Please read this.

The first thing we need to do is GIT the project from our source repository and install all of the required packages from Node and Cordova. We also need to ensure we have our development environment installed and configured.

  1. Clone your local repository to a working folder.
  2. Open a terminal window (command prompt) in the root of the working folder.
  3. Run command 'nvm use 10.14.0'

  4. Run command 'npm install aurelia-cli -g'

  5. Run command 'npm install cordova -g'

  6. Run command 'npm install'

  7. CD into the server folder
  8. Run command 'npm install'

  9. CD back to the root
  10. Run command 'cordova prepare'

NOTE: You may see different content in the screens when preforming some of these instructions. The installers add packages based on existing content, updated content and other factors. This is normal. Remember, I may have previously installed packages before writing this blog ....

This is the exact same process we used on our Windows machine ... pretty sweet. Note that NVM automatically elevates the users permissions in the active terminal so that the SUDO command is not required!

We will be adding some custom scripts a little later to automate some of this process to simplify our efforts.

At this point in time we should have an exact replica of our project from our Windows machine with the exception of the installed packages. The NPM installer and Cordova CLI install packages specific to the environment or machine where the project resides. So all of the platform specific 'stuff' is encapsulated and we don't have to worry about it. Again, pretty sweet ....

We should test the project to ensure it runs. 

NOTE:  At this point in time we actually have two separate projects installed even though they both reside in the root directory.  We have an Aurelia skeleton project and a Cordova skeleton project. We will merge these projects in my next blog.

Before we can start up the Aurelia project we must make one small adjustment in the server/config/config.dev.js file. The config.host must be set to the IP of this computer. This setting is used by the Express server that hosts the WEB API for our project.
  1. Open server/config/config.dev.js in your code editor.
  2. Change config.host = your_ip

  3. Save your changes
  4. Go back to command prompt
  5. Run command 'au run --watch --server'
    Add caption
  6. Open a browser to 'localhost:9000'

So far so good. We have the Aurelia project running in a browser. Lets see if the Cordova project runs. Don't forget to terminate the currently running host servers in the command prompt.
  1. Press [CONTROL][C] to terminate host processes.
  2. Run command 'cordova run browser'

  3. A browser should open showing the Cordova app

Now its time to open our project in XCODE.
  1. Open XCODE

  2. Select "Open another project ..."

  3. Select platforms/ios from the root of your working directory
  4. Select the RUN button

  5. The cordova skeleton project should open in an IOS Simulator 

Now we can test the build from the command prompt.
  1. Run command 'cordova run ios'

  2. Followed by pages of command output ....

  3. The cordova skeleton project should open in a simulator.

Now we have a skeleton Aurelia project and a skeleton Cordova project co-existing in a common project that is saved in our local GIT repository and can be cloned to both a Windows machine and a MAC. Both projects can be launched from a command line on both machines as well as edited using a common code editor on both machines. The cordova mobile projects can also be opened and edited in both Android Studio and XCode.

I think it's time for a beer! My next blog will be dealing with merging these two projects together. We are well on our way to having a simple yet flexible code base that can be deployed to multiple environments.

1 comment:

  1. This is interesting. You are covering a lot of areas that must taken lots of trial and error. Thank you for documenting this process in such detail.

    ReplyDelete