Skip to content

pakaKoni/big-top

BranchesTags

Repository files navigation

The Big Top App

Table of Contents

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:

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:

Logging

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

References:

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:

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

Style Guides

Electron Resources:

Electron Boilerplates:

electron-builder:

Ionic Resources:

Ionic Boilerplates that use the Ionic CLI

Ionic Boilerplate generator that use the Angular CLI

TypeScript Library Boilerplates

About

No description, website, or topics provided.

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages