abl-booking-calendar

This is the ABL core application skeleton/scaffold for developing client side Angular.js web applications.

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
abl-booking-calendar
Minified + gzip package size for abl-booking-calendar in KB

Readme

ABL-skeleton

This is the ABL core application skeleton/scaffold for developing client side Angular.js web applications.

Dependencies

Library
angular 1.5.8
angular-animate 1.5.8
angular-aria 1.5.8
angular-messages 1.5.8
angular-mocks 1.5.8
angular-material 1.1.1
angular-ui-router 0.3.1
jquery 3.1.1
socket.io 1.5.0
angular-socket-io 0.7.0
feathers-client 1.6.1
ng-feathers 1.6.1
ng-device-detector 3.0.1
moment 2.15.1

Features

  • Uses John Papa conventions
  • Live reload development web server (browserSync)
  • Babel (es2015) javascript compilation
  • SCSS (node-sass)
  • ESLint
  • Preprocessing HTML and Javascript (by using .env file)
  • node_modules & npm for front-end dependency management
  • Device, OS, and browser detection with ng-device-detector.
  • Remote client logging with Feathers.js log service.

Install

npm install -g gulp requirejs karma karma-chrome-launcher jasmine-core
npm install

Development

npm run dev
  1. Starts browserSync on port 3000.
  2. Starts Feathers.js API server on port 3030.
  3. Watches file changes and rebuilds app, then reloads browserSync and Feathers.js API server.

Distribution

npm run dist

Testing

npm run test

Unit testing with Karma, Jasmine, and generated code coverage reports with Istanbul.

Reference Guide -- airpair.com/angularjs/posts/unit-testing-angularjs-applications

Configuration with .env file

Define environment variables used to configure the build of the client-side Angular application.

MODULE_NAME=abl
FEATHERS_URL=http://localhost:3030
DEBUG=true
MD_INK=false
Variable Type Default Description
MODULE_NAME String abl Main application module name.
FEATHERS_URL String http://localhost:3030 Feathers.js API server URL.
DEBUG Boolean true Enable/disable application-wide debugging message output.
MD_INK Boolean false Enable/disable application-wide md-ink effect.

The contents of this file can be accessed in HTML / Javascript. For example:

src/index.html

<html ng-app="<!-- @echo MODULE_NAME -->">

src/components/config/config.constant.js

var config = {
  MODULE_NAME: '/* @echo MODULE_NAME */',
  FEATHERS:    '/* @echo FEATHERS_URL */',
  DEBUG:       '/* @echo DEBUG */',
  MD_INK:      '/* @echo MD_INK */'
};

src/components/main/main.config.js

function main ($locationProvider, $compileProvider, $logProvider, $mdInkRippleProvider, config) {
  $compileProvider.debugInfoEnabled(config.DEBUG);
  $logProvider.debugEnabled(config.DEBUG);

  if(config.MD_INK === 'false') {
    $mdInkRippleProvider.disableInkRipple();
  }

  $locationProvider
    .html5Mode(true)
    .hashPrefix('!');
}

src/components/main/feathers.config.js

function feathers ($feathersProvider, config) {
    $feathersProvider.setEndpoint(config.FEATHERS);
    // You can optionally provide additional opts for socket.io-client
    $feathersProvider.useSocket(true);
}

Logging / Debugging

ALWAYS use Angular's built-in $logProvider and $log.debug() for logging to console for debugging purposes. This way we can enable/disable logging application-wide for development and production simply by changing the DEBUG boolean variable in the .env file.

function MainController ($scope, $log, config) {
  // Only printed to console if debug mode is enabled.
  $log.debug('Debug mode enabled.');
}

ESLint will throw a warning for 'no-console' if you forget this principal and use console.log().

'Safe' $apply in Angular.js

To avoid triggering the $apply already in progress error (for me I find I hit most often when integrating third party plugins that trigger a lot of DOM events), you can use a 'safeApply' method that checks the current phase before executing your function. This is patched into the $scope object of topmost controller (NavController), and Angular propagates it throughout the rest of the application:

$scope.safeApply = function(fn) {
  var phase = this.$root.$$phase;
  if(phase == '$apply' || phase == '$digest') {
    if(fn && (typeof(fn) === 'function')) {
      fn();
    }
  } else {
    this.$apply(fn);
  }
};

Usage within child controllers throughout the Angular application:

$scope.safeApply();

Feathers.js API Server

  • The test/server.js file starts a local instance of the same Express/Feathers.js server environment hosted on the backend.
  • Sample data is persisted with NeDB which uses flat-file databases locally -- so no need to configure MongoDB on your development system.
  • API end-points can remain unchanged from dev to production, so all we need to change is the FEATHERS_URL in the .env file to direct the client application to use a public-facing internet accessible Feathers.js API server (e.g. https://api.adventurebucketlist.com).

Components?

Components are small, reusable parts of the application.

All component files DO NOT need angular module definitions, it happens for you.

So you don't ever have to write this:

angular.module('myApp').directive('myAwesomeDirective', myAwesomeDirective);
angular.module('myApp').controller('MyAwesomeController', MyAwesomeController);

Instead, the type is defined in the filename i.e. dashboard.directive.js, dashboard.controller.js

Why?

Too much wasted time creating files alone, and always the same code repeating. We declare the type in the filename instead.

Directives

dashboard.directive.js

function dashboard () {
  return {
    restrict: 'E',
    templateUrl: 'dashboard/dashboard.html',
    controller: 'DashboardController',
    controllerAs: 'vm',
    bindToController: true,
    scope: {}
  }
}

Controllers

dashboard.controller.js

function DashboardController () {
  var vm = this;
}

Factories / Services

users.factory.js

function users ($q, $http) {
  var getUser = function (userId) {
    return $http.get('/users/' + userId);
  }

  return {
    getUser: getUser
  }
}

More (filters, config, run, constant)

TODO: AppShell architecture

Moving towards an offline-available, cached version of the application for improved customer experience and load times.

Inspiration

App shell architecture -- Google's engineering blog post Slack's incremental boot architecture blog post

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.