@TODO: provide rationale for SPA Single html file Uses 'latest' versions of Angular and Twitter bootstrap. Bootstrap has a dependency on jQuery so we will use that as well
- Angular - v1.2.1-rc.3 (v1.2.7 is out as of 1/3/14)
- Bootstrap - v3.0.0 (v3.0.1 is out as of 10/30/13)
- jQuery - v1.10.2 (http://jquery.com/download/: Since IE 6/7/8 are still relatively common, we recommend using the 1.x version unless you are certain no IE 6/7/8 users are visiting the site)
Those are the only 'standard' libs we will use (see below for usage on 3rd party libs).
- 2 space (no tabs) indentation for js, css, and html
- For javascript use 'use strict' (@rationale needed)
- CSS: space between selector and brace
- CSS: each declaration on a new line
- CSS: space after a colon
- CSS: each declaration terminated with a semicolon
- CSS: end brace on a new line
- CSS: blank line between rules
Example module code
//bad
.cmc-fixedcol{width:50px!important;display:none}//good
.cmc-fixedcol {
display: none;
width: 50px!important;
}- all lowercase
- try to keep to a single word, but if multiple words, use hyphens as word separators eg. my-items
##Folder Semantics
- js
- javascript files
- can optionally have sub folders for controllers, services, etc.
- css
- css files
- fonts files
- img
- image files
- preferrably pngs
- libs
- 3rd party libs
- always use folders; don't put any files directly in the libs dir
- data
- json files (.json)
- templates
- angular template html files (.html)
CMC has a modular design built using Angular modules. Modules are a way of encapsulating related functionality. Controllers, services, module specific routes, models, stylings, etc.
To minimize the chances of conflict we'll use some conventions to create a namespace for each module. We will use a dot notation just like in java. So for example, Work Manager, we'll give it the namespace 'wm'. All modules will be prefixed w/ 'cmc'. So the Work Manager module name is 'cmc.wm'.
There can be sub-modules, so Estimates which is under Work Manager has a module name of 'cmc.wm.estimates'.
Module names should be all lower case. Try to keep module names to a single word, but if you do need to use multiple words, separate the name by a hyphen.
For example - My Items under Work Manager would be 'cmc.wm.my-items'
If you are having trouble with coming up with a module name, ask for help. While possible, it can be difficult to change the name later.
Example module code
(function(window, angular, undefined) {
'use strict';
angular.module('cmc.wm.estimates', [])
.config(['$routeProvider', function ($routeProvider) {
$routeProvider
.when('/wm/estimates', {
templateUrl: 'wm/estimates/estimates.html',
controller: 'cmc.wm.estimates.EstimateCtrl'
})
.when('/wm/estimates/:id', {
templateUrl: 'wm/estimates/detail.html',
controller: 'cmc.wm.estimates.EstimateCtrl'
});
}])
.controller('cmc.wm.estimates.EstimateCtrl',
['$scope', '$routeParams',
function ($scope, $routeParams) {
$scope.model = {
id: $routeParams.id
}
}]);
})(window, window.angular);Controllers are classes which tell angular which objects or primitives, functions to expose to the ui. Controllers have three responsibilities:
- Set up the initial state in the model
- Expose the model and functions to the view (UI template) through $scope
- Watch other parts of the model for changes and take action
Although not a hard and fast rule, controllers should be pretty small and limited in the amount of functionality they provide.Most functionality belongs in a Service.
Example of exposing the model to the view: Create a model object that contains the data. Put 'someText' via 'messages' on $scope, don't put 'someText' on $scope directly.
function TextController($scope) {
var messages = {};
messages.someText = 'You have started your journey.';
$scope.messages = messages;
}Note: It's good to keep things out of the global namespace. So instead of this -
function TextController($scope) {
var messages = {};
messages.someText = 'You have started your journey.';
$scope.messages = messages;
}do this -
var myAppModule = angular.module('myApp', []);
myAppModule.controller('TextController', function($scope) {
var someText = {};
someText.message = 'You have started your journey.';
$scope.someText = someText;
});Note: Controllers specified directly in the markup (eg. ng-controller) will automatically be instantiated. If you want control over whether or not as instantiated or to do some 'pre-processing' then it should be done via a route (@add more info here).
Recommendation: To keep your controllers small and manageable, our recommendation is that you create one controller per functional area in your view.
Recommendation: If you have complex sections of your UI, you can keep your code simple and maintainable, by creating nested controllers that can share model and functions through an inheritance tree. Nesting controllers is simple; you do it by simply assigning a controller to a DOM element that is inside another one, like so:
<div ng-controller="ParentController">
<div ng-controller="ChildController">...</div>
</div>Though we express this as nested controllers, the actual nesting happens in scopes. The $scope passed to a nested controller prototypically inherits from its parent controller’s $scope. In this case, this means that the $scope passed to ChildController will have access to all the properties of the $scope passed to ParentController.
Services are singleton (single-instance) objects
Angular comes with many services like $location, for interacting with the browser’s location, $route, for switching views based on location (URL) changes, and $http, for communicating with servers.
@TODO: finish Services section
- User
- Application
- Module - like template data
- Projects
- Project
@TODO: finish data model section