The Big Top App

Table of Contents

• Introduction
  • License
  • Contributing
  • Features
  • Roadmap
  • Quick Start
  • Task Automation
    • Default Tasks
  • Screen Shots
• Build Management
  • Aliases and Environment-specific Variables
  • Development
  • Production
• Unit Testing and End-to-End Testing
  • Jasmine
  • Karma
  • Protractor
  • Test Coverage
• Logging
• Theming
• Documentation
• Resources

Introduction

A sample app built using Ionic 3, Angular 5, Apache Cordova/PhoneGap and Electron that demonstrates how one codebase can be used for Mobile (iOS, Android and Windows Phone) and Desktop (masOS, Linux and Windows) platforms.

License

This work is licensed under the Creative Commons Attribution 3.0 Australia (CC BY 3.0 AU) License. To view a copy of this license, visit https://creativecommons.org/licenses/by/3.0/au/.

Contributing

See: CONTRIBUTING.md

Features

• Ionic 3
• Angular 5
• Environment specific variable support
• Angular-style Unit Testing and End-to-End Testing
• Simple Logging Service
• Dynamic Theme Support
• Documentation generation using Compodoc

Roadmap

• Continuous Integration

Quick Start

# Install Ionic globally using npm
npm install -g ionic@latest

# Clone the project's repo
git clone https://github.com/Robinyo/big-top.git

# Change directory
cd big-top

# Install the project's dependencies
npm install

# Launch the project
npm run ios:dev

Task Automation

Task automation is based on Ionic App Scripts executed from npm scripts. Scripts are configured in the project's package.json file. For example:

  "scripts": {
    ...
    "dev": "ionic-app-scripts serve",
    "ios:dev": "ionic-app-scripts serve --platform=ios",
    "build": "ionic-app-scripts build",
    "ios:build": "ionic-app-scripts build --platform=ios",
    ... 
  }

Default Tasks

Task	Description
clean	Empty the project's www/build directory.
lint	Run the linter against the project's .ts files, using the tslint.json config file located in the project's root directory.
dev	Run the dev server for the Android platform and launch the default browser.
ios:dev	Short cut for npm run dev --platform=ios
build	Create a complete build of the application. Uses the development settings by default. Use the --prod command-line flag to create an optimised build.
ios:build	Short cut for npm run build --platform=ios
test	Run unit test using the Karma test runner.
e2e	Run end-to-end (e2e) tests using Protractor.
docs	Generate project documentation.
serve-docs	Serve project documentation.

To run the build script found in the package.json 'scripts' property, execute:

npm run build

Command-line Flags

Command-line flags can be also applied to npm run commands:

npm run ios:build --prod

To serve your --prod build:

cd www
python -m SimpleHTTPServer 8080

Navigate to:

http://localhost:8080

Screen Shots

If the screen's min-width is less than 992px ('xs', 'sm', 'md'):

If the screen's min-width is 992px ('lg'):

The Big Top Desktop Edition running on macOS Sierra:

The Big Top Desktop Edition's installer running on macOS Sierra:

Build Management

Aliases and Environment-specific Variables

I followed these steps to add support for aliases and environment-specific variables.

Updated compilerOptions in tsconfig.json:

  "compilerOptions": {
  
    ...
    
    "target": "es5",
    "typeRoots": [
      "../node_modules/@types"
    ],
    "baseUrl": "./src",
    "paths": {
      "@app/*": [ "app/*" ],
      "@assets/*": [ "assets/*" ],
      "@env": [ "environments/environment" ],
      "@pages/*": [ "pages/*" ],
      "@services/*": [ "services/*" ],
      "@tests/*": [ "./*" ],
      "@theme/*": [ "theme/*" ]
    }
  }
  
  ...

Created config/webpack.config.js:

const chalk = require("chalk");
const fs = require('fs');
const path = require('path');
const useDefaultConfig = require('@ionic/app-scripts/config/webpack.config.js');

const env = process.env.IONIC_ENV;

if (env === 'prod' || env === 'dev') {

  useDefaultConfig[env].resolve.alias = {
    "@app": path.resolve('./src/app/'),
    "@assets": path.resolve('./src/assets/'),
    "@env": path.resolve(environmentPath()),
    "@pages": path.resolve('./src/pages/'),
    "@services": path.resolve('./src/services/'),
    "@tests": path.resolve('./src/'),    
    "@theme": path.resolve('./src/theme/')
  };

} else {

  // Default to dev config
  useDefaultConfig[env] = useDefaultConfig.dev;
  useDefaultConfig[env].resolve.alias = {
    "@app": path.resolve('./src/app/'),
    "@assets": path.resolve('./src/assets/'),
    "@env": path.resolve(environmentPath()),
    "@pages": path.resolve('./src/pages/'),
    "@services": path.resolve('./src/services/'),
    "@tests": path.resolve('./src/'),    
    "@theme": path.resolve('./src/theme/')
  };

}

function environmentPath() {

  let filePath = './src/environments/environment' + (env === 'prod' ? '' : '.' + env) + '.ts';

  if (!fs.existsSync(filePath)) {
    console.log(chalk.red('\n' + filePath + ' does not exist!'));
  } else {
    return filePath;
  }
}

module.exports = function () {
  return useDefaultConfig;
};

Created src/environments/environment.ts that will be used for the Production environment:

export const ENV = {
  production: true,
  isDebugMode: false
};

Created src/environments/environment.dev.ts that will be used for the Development environment:

export const ENV = {
  production: false,
  isDebugMode: true
};

Update package.json:

"config": {
  "ionic_source_map_type": "source-map",
  "ionic_webpack": "./config/webpack.config.js"
}

Import your environment variables:

import { ENV } from '@env'

Note: Remember to ignore your environment files in your .gitignore

# Environment Variables
**/environment.*
!**/environment.model.ts

References:

• Easy to use environment variables for Ionic 3
• Ionic CLI - Issue 1205 - Environment variable configuration

Development

To build the project:

ionic build

To launch the project:

ionic serve [--platform=ios | android] [--browser chrome | firefox | safari]

Some examples:

ionic serve --platform=ios
ionic serve --platform=android
ionic serve --platform=windows

ionic serve --platform=ios --browser safari
ionic serve --platform=android --browser chrome
ionic serve --platform=windows --browser firefox

You can preview all three supported Mobile platforms side by side:

ionic serve --lab

For example, the 'Sign in' page:

and the 'Events' page:

Electron

To launch the project:

In a terminal run the following command:

ionic serve --no-open

If you want to set the 'ELECTRON_START_URL' environment variable on macOS or Linux:

ELECTRON_START_URL=http://localhost:8104 ionic serve --no-open --port 8104

On Windows use:

set ELECTRON_START_URL=http://localhost:8104 ionic serve --no-open --port 8104

In another terminal run the following command:

electron .

Note: The commands must be run in separate terminal sessions as ionic serve is blocking.

Production

To build the project:

ionic build --prod

Electron

To package the application:

npm run dist

If everything works as expected electron-builder will create a /dist directory.

Unit Testing and End-to-End Testing

Updated tsconfig.ng-cli.json in compilerOptions:

"paths": {
  "@app/*": [ "app/*" ],
  "@assets/*": [ "assets/*" ],
  "@env": [ "environments/environment" ],
  "@pages/*": [ "pages/*" ],
  "@services/*": [ "services/*" ],
  "@theme/*": [ "theme/*" ]
}

Updated .angular-cli.json in apps:

"environments": {
  "dev": "environments/environment.dev.ts",
  "prod": "environments/environment.ts"
}

Updated /src/tsconfig.spec.json in compilerOptions:

"baseUrl": "../src",
"paths": {
  "@app/*": [ "app/*" ],
  "@assets/*": [ "assets/*" ],
  "@env": [ "environments/environment" ],
  "@pages/*": [ "pages/*" ],
  "@services/*": [ "services/*" ],
  "@tests/*": [ "./*" ],
  "@theme/*": [ "theme/*" ]
}

Jasmine

The Jasmine test framework provides everything needed to write basic tests.

Karma

The Karma test runner is ideal for writing and running unit tests while developing an application. It can be an integral part of the project's development and continuous integration processes.

Run:

npm run test

Protractor

Use protractor to write and run end-to-end (e2e) tests. End-to-end tests explore the application as users experience it. In e2e testing, one process runs the real application and a second process runs protractor tests that simulate user behavior and assert that the application respond in the browser as expected.

Run:

ionic serve [--platform=ios]

Then (in a second terminal session):

npm run e2e

Test Coverage

Run:

npm run test-coverage

In the ./coverage folder open index.html

References:

• Testing an Ionic project
• Testing an Angular project

Logging

Take a look at the .ts files in the src/services/log4ts directory.

References:

• A simple logging service for Angular 4

Theming

uigradients

See: https://uigradients.com and https://github.com/subinsebastian/uigradients-scss

Note: variables.scss (in the /themes directory) includes gradients.scss and gradient-mixins.scss.

References:

• Theming your Ionic 3 App

Documentation

To install Compodoc globally:

npm install -g @compodoc/compodoc

To add Compodoc to your project:

npm install --save-dev @compodoc/compodoc

Define script tasks for Compodoc in your package.json:

"scripts": {
  "docs": "./node_modules/.bin/compodoc -d ./docs/ -p ./tsconfig.json --theme vagrant",
  "serve-docs": "./node_modules/.bin/compodoc -s -d ./docs"
}

To generate documentation (using Compodoc):

npm run docs

To serve the generated documentation:

npm run serve-docs

Open your browser and navigate to:

http://localhost:8080

Note: You can exclude files from the generated documentation by using 'exclude' in tsconfig.json:

  "exclude": [
    "./node_modules",
    "./temp/**/*.ts",
    "./src/environments/*.ts",
    "./src/services/**/*.ts",
    "**/*.spec.ts"
  ]

Scaffolding

The scaffolding for this project was generated using the Ionic CLI (version 3.16.0) and the blank template:

ionic start big-top --no-cordova blank

Run ionic g page page-name to generate a new page.

You can also use ionic g [page|component|directive|pipe|provider|tabs] [element name].

Resources

Blog Posts

• Rob Ferguson's blog: Build a Desktop Application with Ionic 3 and Electron
• Rob Ferguson's blog: Build a Desktop Application with Ionic 3 and Electron - Part 2
• Rob Ferguson's blog: Theming your Ionic 3 App
• Rob Ferguson's blog: Theming your Ionic 3 App - Part 2
• Rob Ferguson's blog: Ionic 3 and Forms
• Rob Ferguson's blog: Ionic 3 and Forms - Part 2
• Rob Ferguson's blog: Working with TypeScript, webpack and Ionic 3
• Rob Ferguson's blog: Testing your Ionic 3 App

Style Guides

• Angular docs: Angular Style Guide

Electron Resources:

• Electron docs: Quick Start
• GitHub Pages: Angular on Electron, part 1
• GitHub Pages: Angular on Electron, part 2
• Medium: How to build an Electron app using create-react-app

Electron Boilerplates:

• GitHub: electron-quick-start
• GitHub: electron-react-boilerplate

electron-builder:

• GitHub: electron-builder
• Electron docs: Code Signing

Ionic Resources:

• Ionic Framework docs: Get started with the Ionic Framework
• Ionic Framework blog: Ionic 3 has arrived
• Ionic Framework blog: Build Awesome Desktop Apps with Ionic’s NEW Responsive Grid
• Ionic Framework blog: New Split Pane and more
• GitHub: Ionic App Scripts
• Ionic Framework docs: iOS - UIWebView and WKWebView

Ionic Boilerplates that use the Ionic CLI

• GitHub: Ionic Conference App
• GitHub: Ionic Conference App with JWT authentication
• GitHub: Ionic Boilerplate

Ionic Boilerplate generator that use the Angular CLI

• GitHub: generator-ngx-rocket

TypeScript Library Boilerplates

• GitHub: Starter kit with zero-config for building a library in TypeScript