This read me outlines the setup, configuration and usage of the Angular Baboon seed project.
- Installation
- Configuration
- Usage
- Project Structure
- [Style Guide](#Style Guide)
- Testing
- Common Issues
- Contributors
- License
- nodeJS
- Python (2.7) This is required for PhantomJS
Node is used as the environment to run all of the Angular application's build tools. In general, none of your node packages should be included your final Angular application.
To get started, you'll first need to do a once off installation of gulp and bower as globally accessible packages from the command line (-g ) using node's package manager (npm):
npm install -g gulp bower
Then run the general package installation. The installer will resolve package dependencies from the package.json file.
npm install
After this, you should have a node_modules directory with all the resolved node packages. See the common issues if you're having issues.
Baboon.Angular.App
│ README.md
| package.json
│ ...
│
└───node_modules
│ bower
│ gulp
│ ...
Following this you can do a once off build and test of the app with:
npm test
And start the app with live reload by:
npm start
You can add new node dependencies in the following way:
npm install my-extra-package --save
This will save the package my-extra-package as a dependency in the package.json file with the latest possible version. Don't forget to commit changes to package.json_ to source control.
Bower is the package manager for packages that do get included in your final Angular application. Bower's installer will resolve dependencies from the bower.json file:
bower install
You can add new bower dependencies in the following way:
bower install my-extra-package --save
This will save the package my-extra-package as a dependency in the bower.json file with the latest possible version. Don't forget to commit changes to bower.json to source control.
Linting is the process of running a program that will analyze code for potential errors. Jshint is the default linting tool used in this seed project although Eslint is another great linting tool alternative. By default, Angular Babbon has jshint is set up to be very strict, but you can modify the .jshintrc file to relax jshint. Check out the jshint documentation for all the available options.
Modify the environment.config.js file to change the Angular application's directories, build and environment settings.
Git is the only source control you should use. A few tips:
- It is recommended to commit your bower_components to source control. This reduces your project risk on these dependencies.
- It is not recommended to commit your node_modules to source control. Windows machines can freak out with nodes long paths.
- It is not recommended to commit your .build, dist, coverage, or styleguide to source control.
Modify the .gitignore file to customize what Git includes in your source control.
Karma is the tool used to run the Angular tests that are written with Jasmine. By convention, this projects indicates test files with the .spec.js extension. Mock test data files, or fixtures, are demarcated as .spec.json.
Modify the karma.config.js file to customize the testing configuration or include dependencies required during testing.
The basic usage is briefly described below, and detailed in the installation section 1.2:
npm install
npm test
npm start
Section 3.1 below describes the focused gulp tasks usages that are useful for CI server intergration or specific build scenarios.
Gulp is the task runner used to build the Angular app. The gulpfile.js has the following build tasks setup:
gulp or gulp dev - Once off debug friendly build of the Angular app, includes linting, testing and a code coverage report.
gulp clean - Cleans out the build, distribution and code coverage directories.
gulp watch - Watches the source directory for file contents changes, on which modified files are selectively rebuilt and live reloaded. Note that new or deleted files are not detected by gulp watch at this time.
gulp qa - Once off build with Teamcity reporting and minification for the qa environment.
gulp live - Once off build with Teamcity reporting and minification for the live environment.
A new experimental feature has been added to Angular Baboon to generate a living style guide per Angular application. It can be generated using the following gulp command:
gulp styleguide - Generates an application specific styleguide using the Bootstrap 3 documentation.
By default, it's accessible from _styleguide/index.html. The style guide generation doesn't rebuild the bootstrap documentation from scratch using Ruby and Jekyll. What it does in take a prebuilt version of the docs, and replace the boostrap assets with the release build of the angular application's css.
TODO
You can add your custom gulp files to the gulp tasks directory. They will automatically be included into the master gulp file when executing gulp tasks.
Baboon.Angular.App
| README.md
| gulpfile.js
│ ...
│
└───gulp tasks
│ cleaning tasks.js
│ my custom gulp file.js
│ ...
my custom gulp file.js:
var gulp = require('gulp');
gulp.task('custom-task', function() {
// place code for your custom task here
});Then running gulp custom-task in the root of the Angular project (Baboon.Angular.App) will execute your custom task.
Use npm shrinkwrap to lock down your node dependency versions.
This is very useful in maintaining consistency between developer environments.
npm shrinkwrap generates a file called npm-shrinkwrap.json which will override the normal packages.json file when resolving dependencies during an npm install.
Below is the Angular project structure after all the setup and build has been run:
Baboon.Angular.App
| .bowerrc
| .gitignore
| .jshintrc
| bower.json
| environment.config.js
| gulpfile.js
| karma.config.js
| package.json
| README.md
|
└───.build
└───bower_components
└───coverage
└───dist
└───gulp tasks
└───node_modules
└───styleguide
└───src
| app.js
| app.scss
| app.module.js
| app.spec.js
| app.vendors.module.js
| config.tpl.js
| index.html
|
└───api
└───assets
└───generated
└───modules
Note that only the configuration files are kept at the root of the project, whilst the actual source code that gets built into the final distributable is kept in the src directory. Explicitly included resources from the bower_components directory are also included in the final distribution, but must be configured from the environment.config.js file. Within the src directory:
The src/assets is the general purpose assets directory. Anything not .css or .js should go in there.
The src/api directory contains .json Swagger API definition files. This is only relevant if you choose to use the Angular resource scaffolding features.
The src/generated directory contains the generated files from the scaffolding, don't modify these files, rather extend them.
The src/assets directory gets flattened and included as is during hte release build.
The src/modules directory contains all your glorious hand written code, see the next section for details on this.
app.js is the main Angular application file. Any $rootscope or run code should live here.
app.scss is the root scss file, a good place for any bootstrap styling overrides.
app.module.js is the root module definition file. Register all your new modules here.
app.spec.js is the root application test file.
app.vendors.module.js is the root vendor module registration file. Register any new bower stuff here.
config.tpl.js is a template javascript file for the root angular app configuration. Runtime and environment variables get setup here.
index.html is the base html page. This is the entry point to your app.
Angular Baboon promotes the usage of module and submodule structures that are feature focused. Each module contains only the controllers, filters, directives etc. that it needs. Similarly, each module contains its own styling and tests. Any shared code between (sub)modules should be elevated to a higher module. This approach keeps modules small and easy to test.
myModule
| myModule.config.js
| myModule.module.js
| myModule.scss
|
└───controllers
└───directives
└───filters
└───services
└───templates
└───tests
└───mySubModule
| mySubModule.config.js
| mySubModule.module.js
| mySubModule.scss
|
└───controllers
└───directives
└───filters
└───services
└───templates
└───tests
The *.module.js files simply contain the module definition and dependency hierarchy. Not the usage of the fully qualified name space. The prevents module name collision as the project grows:
(function(){
'use strict';
angular.module( 'angular-baboon.my-module', [
'angular-baboon.my-module.my-sub-module'
]);
})();The *.config.js files contain any module configuration code, for example ui-router state configuration:
(function () {
'use strict';
angular.module('angular-baboon.my-module')
.config(function ($stateProvider) {
$stateProvider
.state('my-module', {
abstract: true,
url: '/my-module',
template: '<div>Hello World</div>'
});
});
})();Every major open-source project has its own style guide: a set of conventions (sometimes arbitrary) about how to write code for that project. It is much easier to understand a large code base when all the code in it is in a consistent style.
But because this just a seed project, you can choose to ignore all of this and do things your own way.
Angular Baboon does have some style enforcement via jshint, which you can choose to customize, but for the most part Angular Baboon is convention driven. The following guides are recommended:
Angular Baboon follows John Papa's style guide for the Angular code (mostly). We've found this to be a practical and relatively maintainable style.
Angular Baboon is is build with the SASS implementation of Bootstrap 3. The reason for this is that Bootstrap is changing from LESS to SASS officially as part of Bootstrap 4. Check out this style guide on how to keep your sassy css clean.
Its entirely up to you what IDE you use. For the the most consistent code base, it's recommended that developers use a common IDE. Angular Baboon is written in Visual Studio Code and uses the built in code formatters. In no particular order, some other great alternatives are:
Check out this Year Of Moo - Full Spectrum Angular Testing guide. It's a little out of date, so the syntax is incorrect, but the concepts and approaches are useful in understanding how to test your Angular applications.
As part of the build tools, a code coverage report is generated. This report can be accessed from coverage/browser-name/index.html.
It is recommended that you run the tests locally, via a normal gulp call, as this will give you a detailed breakdown of the code coverage.
The code coverage report from a release build only gives the coverage of the minified files.
TODO
TODO
Q scaffolding - how are the backend api calls happening?
- Matthew van der Velden (matthew.vdvelden@entelect.co.za)
- Ahmad Mahomed (ahmad@entelect.co.za)
The MIT License (MIT)
Copyright (c) 2015 Entelect
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.