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
- Starts browserSync on port 3000.
- Starts Feathers.js API server on port 3030.
- 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);
$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) {
$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