HourlyNerd AngularJS Reference Application

A starter AngularJS project with an extensive Gulp build process, including mocha unit tests with Karma and end-to-end tests with Protractor. The Gulp file is designed to be able to package the app for use in a private bower server to enable the development of modular Angular apps that live in separate repositories.

Required Packages

• npm install -g wiredep - Allows bower packages to be added to the .tmp/index.html file when you install them. Without this you will need to run gulp to inject bower dependencies.
• npm install -g protractor - Required to run E2E tests
• npm install -g mocha - Required to run E2E tests

Gulp Tasks

• gulp - spawns a development server at the port and host specified in config.coffee. Does the following: compiles sass and coffeescript, makes sourcemaps, compiles ngClassify classes, injects local scripts and css as well as bower dependencies. Updating files will rebuild them.
• gulp package - Does the same thing as gulp but does not launch a dev server. It also annotates angular files and concatenates to the ./dist folder. Bower css and js will be in scripts/bower.css and scripts/bower.js, respectively. Local scripts and css will be in files named hn.css and hn.js.
• gulp watch:package - Watches for changes just like gulp (in addition to images), does not launch a development server, but does the package step at each change. Use this when you are working on multiple apps and one is bower linked to another.
• gulp docs - Compiles docs from our coffeescript code. See YUIDocs for more information.
• gulp build - Does the same thing as gulp package but also uglifies javascript and minifies css. Provides production-ready code at the ./prod directory.
• gulp test - Runs Mocha unit tests with the Karma test runner. Tests for each module must be in a /tests folder relative to the module root.
• gulp e2e - Runs Mocha end-to-end tests with Protractor. Test specs must reside in the app/modules/e2e folder and must end in .spec.js.

Important files:

• config.coffee - Configuration file for gulp. These will be included in the index.html file in the global variable "window.X"
  • app_name - Application name
  • css_namespace - the global namespace for the app. This must match a class attribute on the html element.
  • dev_server - The host and port number for the development server started using gulp
  • bower_exclude - A list of bower folders or files that will be excluded from being injected into the index file. These will still be available for Karma testing, however.
  • main_module_name - The name of the main module folder
  • event_namespace - Prefix for Angular events. You must prefix them yourself.

Working with multiple apps

Use bower link to work on two apps that require each other. For example, say we have two apps, app A and app B. App B requires a directive from App A. Say you need to work on both at the same time. You can use bower link to do that.

1. Checkout both app's repositories to your local machine
2. Make sure App A is registered in the private bower server and has a correctly formatted bower.json file.
3. In App A's root directory, run bower link
4. In App B's root directory, run bower link [name] where [name] is the name attribute of App A's bower.json file.

In App B's bower_components folder, App A's root folder can be found.

After you make a change to App A, you must run gulp package in App A's root directory to see changes in App B.

When you are done, you can remove the link with bower link [name].

Registering a private-bower package

The following property must either be located in each project's .bowerrc file or your own home directory's .bowerrc file: { "registry": "http://yourPrivateBowerRepo:5678" }

This will tell bower to look there to find packages. If it can't find a package in our private bower, it will fall back to the public one.

Then use bower as normal. To register a package, run bower register [packageName] [gitRepo] Make sure to use the SSH clone URL and not the HTTPS url.

Overriding project's bower.json files

If you wish to include a bower project that does not have a "main" attribute of its bower.json file, or you wish to manually pick which files are injected into your index file, you may override their bower.json file in your local bower.json file.

Add the following attribute to your bower.json file:

"overrides": {
    "[bower_project_name]": {
        "main": ""
    }
}

Specify the bower project name and what you want its new main attribute to be. This can be a String or an Array of Strings.

Naming conventions

* The main module should be named after the app. This is so there is no conflict with templates when someone includes your app in bower further down the line.
* Use the CSS and event namespaces as defined in config.json

Directory structure conventions

These are for the src dir

├── docs/
├── e2e/
│   ├── module_name.spec.coffee
├── modules/
│       ├──module_name/
│       ├── images/
│       │   ├── module_name.docs.html
│       ├── styles/
│       │   ├── module_name.scss
│       │   ├── module_name.animation.scss
│       ├── tests/
│       │   ├── module_name.ctrl.spec.coffee
│       ├── views/
│       │   ├── example_template.html
│       │   ├── _example_directive_template.html
│       ├── module_name.module.coffee
│       ├── module_name.routes.coffee
│       ├── module_name.ctrl.coffee
│       ├── module_name.services.coffee
│       ├── module_name.dir.coffee
│       ├── module_name.filters.coffee
│       ├── module_name.config.coffee
│       ├── module_name.constants.coffee
│       ├── module_name.run.coffee
│       ├── settings.provider.coffee
├── components/
        ├── [same as modules]
├── bower.json
├── package.json
├── README.md