Generating an AngularJS project with ITE Architecture

Whats coming in AngularJS 2? =  http://blog.angularjs.org/2014/03/angular-20.html

Advice from the experts – see “The module pattern: a module for each feature” here  https://medium.com/opinionated-angularjs/9f01b594bf06

In case you haven’t realised it, building computer systems is hard. As the complexity of the system gets greater, the task of building the software gets exponentially harder. As in any profession, we can progress only by learning, both from our mistakes and from our successes, but all in all its far better to learn from someone else’s.

In this tutorial we are going to use a project wide and element specific code generator to achieve some standard for front end application structure in ITE projects. I guess it makes sense to ask: “why do we use a code generator at all?” I know that its a controversial idea in some circles and in other communities its a best practice.

For us its a way to get everyone in sync. We determine our best practice and use a generator to take the pain out of following it. We do the same for code format with CodeSniffer. We chose a code format standard, and CodeSniffer automates code inspection for us.

We welcome any, and all tools and techniques that are likely to help improve refactoring and prevent errors when changing code later in a project’s lifecycle.

 

Our aim:

  • Amplify the magnitude of our successes.
  • Limit the scope of our failures.
  • Free our creativity through standardising and automating the mundane.

 

What do we need?

  1. tools that make it easy to create an application
  2. structure that separates concerns e.g. domain from infrastructure and model from control
  3. consistency – so we can easily maintain many projects from many authors
  4. minimise technical debt – have bulk of the code come from peer reviewed sources e.g. open source framework

 

What do we want?

  1. code that writes itself with guidance from us
  2. code that works everywhere
  3. code that is clear and concise
  4. code structure that mirrors the problem it solves

 

The tool-chain provider we chose describes their solution as:

“Our workflow is comprised of three tools for improving your productivity and satisfaction when building a web app: yo (the scaffolding tool), grunt (the build tool) and bower (for package management).”

For AngularJS projects we use cg-angular. It is a generator module for AngularJS projects and runs on Yeoman (yo). The author Chris Gross especially modified it to support our modular file and folder requirements.

Here is an example structure:

.
└── app
    ├── Gruntfile.js
    ├── README.md
    ├── api.php
    ├── app.js
    ├── app.less
    ├── bower.json
    ├── bower_components
    ├── dist
    │   ├── app.full.min.css
    │   ├── app.full.min.js
    │   ├── bower_components
    │   │   └── font-awesome
    │   │       └── fonts
    │   │           ├── FontAwesome.otf
    │   │           ├── fontawesome-webfont.eot
    │   │           ├── fontawesome-webfont.svg
    │   │           ├── fontawesome-webfont.ttf
    │   │           └── fontawesome-webfont.woff
    │   └── index.html
    ├── index.html
    ├── modules
    │   ├── employees
    │   │   └── employees-list
    │   │       ├── employees-list-spec.js
    │   │       ├── employees-list.html
    │   │       ├── employees-list.js
    │   │       └── employees-list.less
    │   ├── system
    │   │   └── postfix
    │   │       └── postfix.js
    │   └── user
    │       ├── user-create
    │       │   ├── user-create-spec.js
    │       │   ├── user-create.html
    │       │   ├── user-create.js
    │       │   └── user-create.less
    │       ├── user-list
    │       │   ├── user-list-spec.js
    │       │   ├── user-list.html
    │       │   ├── user-list.js
    │       │   └── user-list.less
    │       ├── user-service
    │       │   ├── user-service-spec.js
    │       │   └── user-service.js
    │       └── user-update
    │           ├── user-update-spec.js
    │           ├── user-update.html
    │           ├── user-update.js
    │           └── user-update.less
    ├── node_modules
    └── package.json

Here is the example project we are currently using to learn how to structure our applications: EnterpriseAngularJS

Set up the tools:

Getting started section is the right place.

Create your new project:

mkdir MyNewAwesomeApp
cd MyNewAwesomeApp
yo cg-angular

This generates the base project with no sub-structure.

bower update

npm update

It sets up the node.js and bower component folders with toolchain and project dependencies respectively.

ITE Architecture

The next steps uses sub-generators:

yo cg-angular:directive my-directive
yo cg-angular:partial my-partial
yo cg-angular:service my-service
yo cg-angular:filter my-filter

But before we can start using them, we need to have a plan. I would call it an architecture plan, because it needs to reflect the logical separation of the code. So its not just about file and folder structures. Its about scope.

There are many ways to organise your project if you don’t have a guiding idea.

Our guiding idea, however, leaves us with only one way. What is this guiding idea? “Domain Driven Design

So to use the sub-generators, we need to have a “Domain Driven Design” already worked out for the work we are planning to do in the sprint or near future.

The ITE approach – Modular Development

In the project example given above (in tree and git repo) we see 3 modules.

  1. Employees
  2. System
  3. User

Whatever your domain model breaks down to, at ITE we try to separate the “Domain Specific Code” from the system and infrastructure code.

One solution is to have a “src” folder where all “Domain Specific Code” can be found and “app” folder for framework and system related code.

In the example above we have a “modules” folder and there are two “Domain Specific” modules and one system and infrastructure module called “system”. So how did we generate those?

yo cg-angular:partial user-list
[?] Enter your route url (i.e. /mypartial/:id). If you don't want a route added for you, leave this empty.
/user-list
[?] Where would you like to create the partial files? (partial/user-list/)
modules/user/user-list/
updating index.html
updating app.less
updating app.js
create modules/user/user-list/user-list-spec.js
create modules/user/user-list/user-list.html
create modules/user/user-list/user-list.js
create modules/user/user-list/user-list.less
yo cg-angular:partial user-create
[?] Enter your route url (i.e. /mypartial/:id). If you don't want a route added for you, leave this empty.
/user-create
[?] Where would you like to create the partial files? (partial/user-create/)
modules/user/user-create/
updating index.html
updating app.less
updating app.js
create modules/user/user-create/user-create-spec.js
create modules/user/user-create/user-create.html
create modules/user/user-create/user-create.js
create modules/user/user-create/user-create.less
yo cg-angular:partial user-update
[?] Enter your route url (i.e. /mypartial/:id). If you don't want a route added for you, leave this empty.
/user-update
[?] Where would you like to create the partial files? (partial/user-update/)
modules/user/user-update/
updating index.html
updating app.less
updating app.js
create modules/user/user-update/user-update-spec.js
create modules/user/user-update/user-update.html
create modules/user/user-update/user-update.js
create modules/user/user-update/user-update.less

The interactive command line process is shown above with answers to questions posed by the sub-generator for partials.

While “user-service” was slightly different.

yo cg-angular:service user-service
[?] Where would you like to create the service files? (service/)
modules/user/user-service/
updating index.html
create modules/user/user-service/user-service-spec.js
create modules/user/user-service/user-service.js

This modular project builds into one “html”, one “js” and one “css” file using the Grunt command “build”.

$ grunt build

It creates a “dist” folder with the projects distribution version.

In another post we will look at customising the templates that ships with cg-angular.

One Response

  1. Awesome tutorial. Ive been trying to get around cg-angular and yours cleared most of my doubts. Thanks

Leave a Reply