Before we go any further, let's describe the demonstration app we'll be building through the course of this book.

I've called it Logology. If you're familiar with any Greek words, you might have already guessed what the app will be: a dictionary. Now, I understand that this is not necessarily the most amazing app, but it is sufficient for our purposes. It will help you learn how advanced mobile development is done.

By the end of the book, the app will have the following features:

Although the app sounds relatively simple, it's complex enough to benefit from task automation. Since it is useful to have task automation in place from the very beginning, in this chapter we'll install Gulp and verify that it is working with some simple files first. As such, the app in the code package for this first chapter is very simple; it exists solely to verify that our tasks are working correctly.

You may think that working through configuring task automation is very time-consuming, but it will pay off in the long run. Once you have a workflow that you like, you can take the workflow and apply it to any other apps you may build in the future. This means that future apps can be started almost immediately (just copy the configuration from the previous app). Even if you don't write other apps, the time you save from having a task runner will outweigh the initial setup time.

Gulp (http://gulpjs.com) is a task automation utility using the Node.js platform. Unlike some other task runners, one configures Gulp by writing a JavaScript code. The configuration for Gulp is just like any other JavaScript file, which means that if you know JavaScript, you can start defining the automation tasks quickly.

Gulp also uses the concept of streams (again, from Node.js). Although you can think of a stream as a file, streams are actually more powerful. Plugins can be inserted within steam processing to perform many different transformations, including beautification or uglification, transpilation (for example, ECMAScript 6 to ECMAScript 2015), concatenation, packaging, and much more.

Gulp also tries to run as many dependent tasks in parallel as possible. Ideally, this makes it possible to run Gulp tasks faster, although this really depends on how your tasks are structured. Other task runners such as Grunt perform their task steps in a sequence that may result in a slower output, although it may be easier to follow the steps from input to output when they're performed sequentially.

That's not to say that Gulp is the best task runner—there are many that are quite good, and you may find that you prefer one of them over Gulp. The skills you will learn in this book can easily be transferred to other task automation utilities.

Here are some other task runners that are useful:

Before we install Gulp, we should create the directory structure for our app. Keep in mind that there's no single correct way to structure your application, and your opinion on how apps should be structured is likely to change as you gain more experience. That said, this section will show you how I like to structure my projects.

My typical structure starts with the project's root directory. If you look at the code bundle for this book, you'll notice that the project's root directory is called logology-v01/.

Within the project's root directory are some additional directories:

Within the src/ directory lives our app's source code. I like to structure the code and assets as follows:

project-root/
  src/
    config.xml            # Template file for our Cordova app's
                          # configuration
    res/                  # Icons & splash screens (covered in
                          # Chapter 11)
    www/                  # HTML, JavaScript, and CSS, and other
                          # web assets
      index.html          # Initial HTML file (as specified in
                          # config.xml)
      html/               # Additional HTML files, if any
      img/                # Image files, if we need them
      scss/               # Sassy CSS files (see Chapter 3)
        lib/              # Utility functions
        themes/           # Themes (appearance of the app)
        views/            # Styles specific to views in our app
      js/                 # JavaScript
        lib/              # Third-party library code and support
                          # code
        app/              # Our application code
          index.js        # The entry point for our app
          controllers/    # View controllers live here
          lib/            # App-specific utility files
          localization/   # Language translations
          models/         # Data models go here
          views/          # Views and templates live here

If you look at the directory structure of this chapter in the code bundle, you will notice that a lot of it is missing. This is because it's not necessary at this point; we'll fill it out in the future chapters.

If you're wondering where the Cordova files are, you're paying attention. There aren't any. Yet. This is because they are considered to be build artifacts. Build artifacts are files that are created when you compile your app. If this feels both a little strange and a little familiar at the same time, there's a good reason behind it: the Cordova projects already have portions that are considered to be build artifacts. The strange part is that you're probably used to editing the www/ folder within the Cordova project, and executing cordova build to create the remaining build artifacts (namely, the native wrappers around your code, typically in platforms/).

In this book, however, we're going to take a higher level approach and consider the entire Cordova project as a build artifact. Why? Because Cordova has been extended by several other projects (such as Steroids: http://www.appgyver.com/steroids) and they usually have their own project formats and build steps. If you ever want to target these platforms, you can readily do so since your code doesn't live within a Cordova project. Furthermore, you might find that you want to target other technologies entirely, such as Electron (http://electron.atom.io) which encapsulates your code with a Chromium webview suitable for desktop execution. The build steps and project structure for Electron are different than what you might expect for a Cordova project. In short, it's a way to avoid tying yourself down.

All said, when we're done with the chapter, you'll have a Cordova app filled with your source code. That project will be present in the build/ directory.

A crucial part of our workflow is going to be our project's package.json file. This file will contain the app's version information, Cordova configuration, and more. If you're starting from scratch, you will need to create this file yourself by changing to the project's root directory and executing npm init:

# (in your project's root directory)
$ npm init [ENTER]
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sane
defaults.
…

name: (logology-v01) Logology [ENTER]
version: (1.0.0) [ENTER]
description: Logology and PhoneGap demonstration app [ENTER]
entry point: (index.js) [ENTER]
test command: [ENTER]
git repository: [ENTER]
keywords: dictionary word study phonegapcordova html5 javascript
css [ENTER]
author: Kerri Shotts<kerrishotts@gmail.com> [ENTER]
license: (ISC) MIT [ENTER]
About to write to .../logology-v01/package.json:

Is this ok? (yes) [ENTER]

At this point, you have the package.json file is created, but it will need a few more edits. Open the package.json file in your favorite editor and remove the scripts section. Then, add the following (for the full contents of this file you can refer to the code package):

{ ...,
"cordova": {
  "name": "Logology",
  "id": "com.packtpub.logologyv1",
  "description": "Dictionary application",
  "author": {
    "name": "Kerri Shotts",
    "email": "kerrishotts@gmail.com",
    "site": "http://www.photokandy.com"
  },
  "template": "../blank",
  "platforms": [ "ios", "android" ],
  "preferences": {
    "permissions": "none",
    "fullscreen": "false",
    "orientation": "default",
    "stay-in-webview": "false",
    "ShowSplashScreenSpinner": "false",
    "AutoHideSplashScreen": "false",
    "disable-cursor": "false",
    "KeyboardDisplayRequiresUserAction": "false",
    "target-device": "universal",
    "prerendered-icon": "true",
    "webviewbounce": "false",
    "DisallowOverscroll": "true",
    "exit-on-suspend": "false",
    "deployment-target": "7.0",
    "detect-data-types": "false",
    "SupressesIncrementalRendering": "true",
    "android-minSdkVersion": "14",
    "android-installLocation": "auto",
    "android-windowSoftInputMode": "adjustResize",
  },
  "plugins": [
    "cordova-plugin-device@1.1.0",
    "cordova-plugin-network-information@1.1.0",
    "cordova-plugin-globalization@1.0.2",
    "cordova-plugin-whitelist@1.1.0",
    "ionic-plugin-keyboard@1.0.8",
    "cordova-plugin-inappbrowser@1.0.1"
    ]
  }
}

The preceding code should be fairly self-explanatory. With it, we are essentially duplicating the contents of Cordova's config.xml file. Because the Cordova project itself is considered to be a build artifact, it makes sense to manage plugins, platforms, and preferences somewhere else and, because package.json handles the other configuration aspects of our project, it makes sense to include these configuration settings here.

At this point, we're ready to install Gulp and any other dependencies our project might need.

Installing Gulp is easy, but is actually a two-step process. The first step is to install Gulp globally. This installs the command-line utility; but Gulp won't work without also being installed locally within our project. If you aren't familiar with Node.js, the packages can be installed locally and/or globally. A locally installed package is local to the project's root directory, while a globally installed package is specific to the developer's machine. Project dependencies are tracked in package.json, which makes it easy to replicate your development environment on another machine.

Assuming you have Node.js installed and package.json created in your project directory, the installation of Gulp will be very easy. Be sure you are positioned in your project's root directory and then execute the following:

$ npm install -g gulp@3.9.0
$ npm install --save-dev gulp@3.9.0

That's it! Gulp itself is very easy to install, but most workflows require additional plugins that work with Gulp. In addition, we'll also install the Cordova dependencies for this project.

First, let's install the Cordova dependencies:

$ npm install --save-dev cordova-lib@5.4.1 cordova-ios@3.9.2 cordova-android@4.1.1

cordova-lib allows us to programmatically interact with Cordova. We can create projects, build them, and emulate them—everything we do with the Cordova command line can be done with cordova-lib. cordova-ios and cordova-android refer to the iOS and Android platforms that cordova platform add ios android would add. We've made them dependencies for our project, so we can easily control which version we will build it with.

Next, let's install the Gulp plugins we'll need:

$ npm install --save-dev babel-eslint@4.1.1 cordova-tasks@0.2.0 gulp-babel@5.2.1 gulp-bump@0.3.1 gulp-concat@2.6.0 gulp-eslint@1.0.0 gulp-jscs@3.0.2 gulp-notify@2.2.0 gulp-rename@1.2.0 gulp-replace-task@0.10.1 gulp-sourcemaps@1.3.0 gulp-uglify@1.4.0 gulp-util@3.0.6 merge-stream@1.0.0 require-all@1.1.0 rimraf@2.4.3

These will take a few moments to install; but when you're done, take a look at package.json. Notice that all the dependencies we added are also added to the devDependencies section in the file. This makes it easy to install all the project's dependencies at a later date (say, on a new machine) simply by executing npm install.

Before we go on, let's quickly go over what each of the earlier mentioned utilities do. We'll go over them in more detail as we progress through the remainder of this chapter:

Gulp tasks are defined by the contents of the project's gulpfile.js file. This is a JavaScript program, so the same skills you have with JavaScript will apply here. Furthermore, it's executed by Node.js, so if you have any Node.js knowledge, you can use it to your advantage.

The first few lines of your Gulp configuration file will require the Gulp plugins you'll need to complete the tasks. The following lines will then specify how the various tasks need to be performed. For example, a very simple configuration might look as follows:

var gulp = require("gulp");
gulp.task("copy-files", function () {
  gulp.src(["./src/**/*"])
      .pipe(gulp.dest("./build"));
});

This configuration only performs one task: it moves all the files contained within src/ to build/. In many ways, this is the simplest form of a build workflow, but it's a bit too simple for our purposes.

To execute the task, you can execute gulp copy-files. Gulp would then execute the task and copy all the files from src/ to build/.

What makes Gulp so powerful is the concept of task composition. Tasks can depend on any number of other tasks and those tasks can depend on yet more tasks. This makes it easy to create complex workflows out of simpler pieces. Furthermore, each task is asynchronous, so it is possible for many tasks with no shared dependencies to operate in parallel.

Each task, as you can see in the prior code, is comprised of a selection of a series of source files (src()), optionally performing some additional processing on each file (via pipe()) and then writing those files to a destination path (dest()). If no additional processing is specified (as in the prior example), Gulp will simply copy the files that match the wildcard pattern. The beauty of streams, however, is that one can execute any number of transformations before the final data is saved. So, the workflows can become very complex.

Now that you've seen a simple task, let's get into some more complicated tasks in the next section.