initial commit

.gitignore

+*.sw[a-z]
+vendor/*
+build/*
+bin/*
+node_modules/*
+CHANGELOG.md
+CONTRIBUTING.md
+LICENSE
+changelog.tpl
+tools.md
+
+

bower.json

+{
+  "name": "Interactive",
+  "version": "0.3.2",
+  "devDependencies": {
+    "angular": "~1.2",
+    "angular-mocks": "~1.2",
+    "bootstrap": "~3.1",
+    "angular-bootstrap": "~0.10.0",
+    "angular-ui-router": "~0.2",
+    "pixi.js": "~2.2.7"
+  },
+  "dependencies": {}
+}

build.config.js

+/**
+ * This file/module contains all configuration for the build process.
+ */
+module.exports = {
+  /**
+   * The `build_dir` folder is where our projects are compiled during
+   * development and the `compile_dir` folder is where our app resides once it's
+   * completely built.
+   */
+  build_dir: 'build',
+  compile_dir: 'bin',
+
+  /**
+   * This is a collection of file patterns that refer to our app code (the
+   * stuff in `src/`). These file paths are used in the configuration of
+   * build tasks. `js` is all project javascript, less tests. `ctpl` contains
+   * our reusable components' (`src/common`) template HTML files, while
+   * `atpl` contains the same, but for our app's code. `html` is just our
+   * main HTML file, `less` is our main stylesheet, and `unit` contains our
+   * app's unit tests.
+   */
+  app_files: {
+    js: [ 'src/**/*.js', '!src/**/*.spec.js', '!src/assets/**/*.js' ],
+    jsunit: [ 'src/**/*.spec.js' ],
+    
+    coffee: [ 'src/**/*.coffee', '!src/**/*.spec.coffee' ],
+    coffeeunit: [ 'src/**/*.spec.coffee' ],
+
+    atpl: [ 'src/app/**/*.tpl.html' ],
+    ctpl: [ 'src/common/**/*.tpl.html' ],
+
+    html: [ 'src/index.html' ],
+    less: 'src/less/main.less'
+  },
+
+  /**
+   * This is a collection of files used during testing only.
+   */
+  test_files: {
+    js: [
+      'vendor/angular-mocks/angular-mocks.js'
+    ]
+  },
+
+  /**
+   * This is the same as `app_files`, except it contains patterns that
+   * reference vendor code (`vendor/`) that we need to place into the build
+   * process somewhere. While the `app_files` property ensures all
+   * standardized files are collected for compilation, it is the user's job
+   * to ensure non-standardized (i.e. vendor-related) files are handled
+   * appropriately in `vendor_files.js`.
+   *
+   * The `vendor_files.js` property holds files to be automatically
+   * concatenated and minified with our project source files.
+   *
+   * The `vendor_files.css` property holds any CSS files to be automatically
+   * included in our app.
+   *
+   * The `vendor_files.assets` property holds any assets to be copied along
+   * with our app's assets. This structure is flattened, so it is not
+   * recommended that you use wildcards.
+   */
+  vendor_files: {
+    js: [
+      'vendor/angular/angular.js',
+      'vendor/angular-bootstrap/ui-bootstrap-tpls.min.js',
+      'vendor/placeholders/angular-placeholders-0.0.1-SNAPSHOT.min.js',
+      'vendor/angular-ui-router/release/angular-ui-router.js',
+      'vendor/angular-ui-utils/modules/route/route.js'
+    ],
+    css: [
+    ],
+    assets: [
+    ]
+  },
+};

karma/karma-unit.tpl.js

+module.exports = function ( karma ) {
+  karma.set({
+    /** 
+     * From where to look for files, starting with the location of this file.
+     */
+    basePath: '../',
+
+    /**
+     * This is the list of file patterns to load into the browser during testing.
+     */
+    files: [
+      <% scripts.forEach( function ( file ) { %>'<%= file %>',
+      <% }); %>
+      'src/**/*.js',
+      'src/**/*.coffee',
+    ],
+    exclude: [
+      'src/assets/**/*.js'
+    ],
+    frameworks: [ 'jasmine' ],
+    plugins: [ 'karma-jasmine', 'karma-firefox-launcher', 'karma-coffee-preprocessor' ],
+    preprocessors: {
+      '**/*.coffee': 'coffee',
+    },
+
+    /**
+     * How to report, by default.
+     */
+    reporters: 'dots',
+
+    /**
+     * On which port should the browser connect, on which port is the test runner
+     * operating, and what is the URL path for the browser to use.
+     */
+    port: 9018,
+    runnerPort: 9100,
+    urlRoot: '/',
+
+    /** 
+     * Disable file watching by default.
+     */
+    autoWatch: false,
+
+    /**
+     * The list of browsers to launch to test on. This includes only "Firefox" by
+     * default, but other browser names include:
+     * Chrome, ChromeCanary, Firefox, Opera, Safari, PhantomJS
+     *
+     * Note that you can also use the executable name of the browser, like "chromium"
+     * or "firefox", but that these vary based on your operating system.
+     *
+     * You may also leave this blank and manually navigate your browser to
+     * http://localhost:9018/ when you're running tests. The window/tab can be left
+     * open and the tests will automatically occur there during the build. This has
+     * the aesthetic advantage of not launching a browser every time you save.
+     */
+    browsers: [
+      'Firefox'
+    ]
+  });
+};
+

module.prefix

+(function ( window, angular, undefined ) {

module.suffix

+})( window, window.angular );

package.json

+{
+  "author": "Richard Torenvliet",
+  "name": "Interactive",
+  "version": "0.3.2",
+  "dependencies": {},
+  "devDependencies": {
+    "grunt": "~0.4.1",
+    "grunt-bump": "0.0.6",
+    "grunt-coffeelint": "~0.0.10",
+    "grunt-contrib-clean": "^0.4.1",
+    "grunt-contrib-coffee": "^0.7.0",
+    "grunt-contrib-concat": "^0.3.0",
+    "grunt-contrib-copy": "^0.4.1",
+    "grunt-contrib-jshint": "^0.4.3",
+    "grunt-contrib-less": "~0.11.0",
+    "grunt-contrib-uglify": "^0.2.7",
+    "grunt-contrib-watch": "^0.4.4",
+    "grunt-conventional-changelog": "^0.1.2",
+    "grunt-html2js": "^0.1.9",
+    "grunt-karma": "^0.8.2",
+    "grunt-ng-annotate": "^0.8.0",
+    "karma": "^0.12.9",
+    "karma-coffee-preprocessor": "^0.2.1",
+    "karma-firefox-launcher": "^0.1.3",
+    "karma-jasmine": "^0.1.5",
+  }
+}

src/README.md

+# The `src` Directory
+
+## Overview
+
+The `src/` directory contains all code used in the application along with all
+tests of such code.
+
+```
+src/
+  |- app/
+  |  |- about/
+  |  |- home/
+  |  |- app.js
+  |  |- app.spec.js
+  |- assets/
+  |- common/
+  |  |- plusOne/
+  |- less/
+  |  |- main.less
+  |  |- variables.less
+  |- index.html
+```
+
+- `src/app/` - application-specific code, i.e. code not likely to be reused in
+  another application. [Read more »](app/README.md)
+- `src/assets/` - static files like fonts and images. 
+  [Read more »](assets/README.md)
+- `src/common/` - third-party libraries or components likely to be reused in
+  another application. [Read more »](common/README.md)
+- `src/less/` - LESS CSS files. [Read more »](less/README.md)
+- `src/index.html` - this is the HTML document of the single-page application.
+  See below.
+
+See each directory for a detailed explanation.
+
+## `index.html`
+
+The `index.html` file is the HTML document of the single-page application (SPA)
+that should contain all markup that applies to everything in the app, such as
+the header and footer. It declares with `ngApp` that this is `ngBoilerplate`,
+specifies the main `AppCtrl` controller, and contains the `ngView` directive
+into which route templates are placed.
+
+Unlike any other HTML document (e.g. the templates), `index.html` is compiled as
+a Grunt template, so variables from `Gruntfile.js` and `package.json` can be
+referenced from within it. Changing `name` in `package.json` from
+"ng-boilerplate" will rename the resultant CSS and JavaScript placed in `build/`,
+so this HTML references them by variable for convenience.

src/app/README.md

+# The `src/app` Directory
+
+## Overview
+
+```
+src/
+  |- app/
+  |  |- home/
+  |  |- about/
+  |  |- app.js
+  |  |- app.spec.js
+```
+
+The `src/app` directory contains all code specific to this application. Apart
+from `app.js` and its accompanying tests (discussed below), this directory is
+filled with subdirectories corresponding to high-level sections of the
+application, often corresponding to top-level routes. Each directory can have as
+many subdirectories as it needs, and the build system will understand what to
+do. For example, a top-level route might be "products", which would be a folder
+within the `src/app` directory that conceptually corresponds to the top-level
+route `/products`, though this is in no way enforced. Products may then have
+subdirectories for "create", "view", "search", etc. The "view" submodule may
+then define a route of `/products/:id`, ad infinitum.
+
+As `ngBoilerplate` is quite minimal, take a look at the two provided submodules
+to gain a better understanding of how these are used as well as to get a
+glimpse of how powerful this simple construct can be.
+
+## `app.js`
+
+This is our main app configuration file. It kickstarts the whole process by
+requiring all the modules from `src/app` that we need. We must load these now to
+ensure the routes are loaded. If as in our "products" example there are
+subroutes, we only require the top-level module, and allow the submodules to
+require their own submodules.
+
+As a matter of course, we also require the template modules that are generated
+during the build.
+
+However, the modules from `src/common` should be required by the app
+submodules that need them to ensure proper dependency handling. These are
+app-wide dependencies that are required to assemble your app.
+
+```js
+angular.module( 'ngBoilerplate', [
+  'templates-app',
+  'templates-common',
+  'ngBoilerplate.home',
+  'ngBoilerplate.about'
+  'ui.router',
+  'ui.route'
+])
+```
+
+With app modules broken down in this way, all routing is performed by the
+submodules we include, as that is where our app's functionality is really
+defined.  So all we need to do in `app.js` is specify a default route to follow,
+which route of course is defined in a submodule. In this case, our `home` module
+is where we want to start, which has a defined route for `/home` in
+`src/app/home/home.js`.
+
+```js
+.config( function myAppConfig ( $stateProvider, $urlRouterProvider ) {
+  $urlRouterProvider.otherwise( '/home' );
+})
+```
+
+Use the main applications run method to execute any code after services
+have been instantiated.
+
+```js
+.run( function run () {
+})
+```
+
+And then we define our main application controller. This is a good place for logic
+not specific to the template or route, such as menu logic or page title wiring.
+
+```js
+.controller( 'AppCtrl', function AppCtrl ( $scope, $location ) {
+  $scope.$on('$stateChangeSuccess', function(event, toState, toParams, fromState, fromParams){
+    if ( angular.isDefined( toState.data.pageTitle ) ) {
+      $scope.pageTitle = toState.data.pageTitle + ' | ngBoilerplate' ;
+    }
+  });
+})
+```
+
+### Testing
+
+One of the design philosophies of `ngBoilerplate` is that tests should exist
+alongside the code they test and that the build system should be smart enough to
+know the difference and react accordingly. As such, the unit test for `app.js`
+is `app.spec.js`, though it is quite minimal.

src/app/app.js

+angular.module( 'Interactive', [
+    'templates-app',
+    'templates-common',
+    'Interactive.index',
+    'ui.router'
+])
+
+.config( function ( $stateProvider, $urlRouterProvider ) {
+    $urlRouterProvider.otherwise( '/index' );
+})
+
+.run( function run () {
+})
+
+.controller( 'AppCtrl', function AppCtrl ( $scope, $location ) {
+    $scope.$on('$stateChangeSuccess', function(event, toState, toParams, fromState, fromParams){
+        if ( angular.isDefined( toState.data.pageTitle ) ) {
+            $scope.pageTitle = toState.data.pageTitle;
+        }
+    });
+})
+
+;
+

src/app/app.spec.js

+describe( 'AppCtrl', function() {
+  describe( 'isCurrentUrl', function() {
+    var AppCtrl, $location, $scope;
+
+    beforeEach( module( 'Interactive' ) );
+
+    beforeEach( inject( function( $controller, _$location_, $rootScope ) {
+        $location = _$location_;
+        $scope = $rootScope.$new();
+        AppCtrl = $controller( 'AppCtrl', { $location: $location, $scope: $scope });
+    }));
+
+    it( 'should pass a dummy test', inject( function() {
+        expect( AppCtrl ).toBeTruthy();
+    }));
+  });
+});

src/app/index/index.js

+angular.module('Interactive.index', [
+    'ui.router'
+])
+
+.config(function($stateProvider) {
+    $stateProvider.state( 'index', {
+        url: '/index',
+        views: {
+            'main': {
+                controller: 'IndexCtrl',
+                templateUrl: 'index/index.tpl.html'
+            }
+        },
+
+        data: {pageTitle: 'index'}
+    });
+})
+
+.controller( 'IndexCtrl', function IndexController($scope) {
+})
+
+;
+
+

src/app/index/index.tpl.html

+<div>
+    <h1>Index</h1>
+</div>

src/assets/README.md

+# The `src/assets` Directory
+
+There's really not much to say here. Every file in this directory is recursively transferred to `dist/assets/`.
+

src/common/README.md

+# The `src/common/` Directory
+
+The `src/common/` directory houses internal and third-party re-usable
+components. Essentially, this folder is for everything that isn't completely
+specific to this application.
+
+Each component resides in its own directory that may then be structured any way
+the developer desires. The build system will read all `*.js` files that do not
+end in `.spec.js` as source files to be included in the final build, all
+`*.spec.js` files as unit tests to be executed, and all `*.tpl.html` files as
+templates to compiled into the `$templateCache`. There is currently no way to
+handle components that do not meet this pattern.
+
+```
+src/
+  |- common/
+  |  |- plusOne/
+```
+
+- `plusOne` - a simple directive to load a Google +1 Button on an element.
+
+Every component contained here should be drag-and-drop reusable in any other 
+project; they should depend on no other components that aren't similarly 
+drag-and-drop reusable.

src/common/plusOne/plusOne.js

+angular.module( 'plusOne', [] )
+
+.directive( 'plusOne', function() {
+  return {
+    link: function( scope, element, attrs ) {
+      gapi.plusone.render( element[0], {
+        "size": "medium",
+        "href": "http://bit.ly/ngBoilerplate"
+      });
+    }
+  };
+})
+
+;
+

src/index.html

+<!DOCTYPE html>
+<html ng-app="Interactive" ng-controller="AppCtrl">
+  <head>
+    <title ng-bind="pageTitle"></title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <!-- font awesome from BootstrapCDN -->
+    <link href="http://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
+
+    <!-- compiled CSS --><% styles.forEach( function ( file ) { %>
+    <link rel="stylesheet" type="text/css" href="<%= file %>" /><% }); %>
+
+    <!-- compiled JavaScript --><% scripts.forEach( function ( file ) { %>
+    <script type="text/javascript" src="<%= file %>"></script><% }); %>
+  </head>
+  <body>
+      <div class="container" ui-view="main">
+          <h1>Test</h1>
+      </div>
+  </body>
+</html>

src/less/README.md

+# The `src/less` Directory
+
+This folder is actually fairly self-explanatory: it contains your LESS/CSS files to be compiled during the build. 
+The only important thing to note is that *only* `main.less` will be processed during the build, meaning that all
+other stylesheets must be *imported* into that one.
+
+This should operate somewhat like the routing; the `main.less` file contains all of the site-wide styles, while
+any styles that are route-specific should be imported into here from LESS files kept alongside the JavaScript
+and HTML sources of that component. For example, the `home` section of the site has some custom styles, which
+are imported like so:
+
+```css
+@import '../app/home/home.less';
+```
+
+The same principal, though not demonstrated in the code, would also apply to reusable components. CSS or LESS
+files from external components would also be imported. If, for example, we had a Twitter feed directive with
+an accompanying template and style, we would similarly import it:
+
+```css
+@import '../common/twitterFeed/twitterFeedDirective.less';
+```
+
+Using this decentralized approach for all our code (JavaScript, HTML, and CSS) creates a framework where a
+component's directory can be dragged and dropped into *any other project* and it will "just work".
+
+I would like to eventually automate the importing during the build so that manually importing it here would no
+longer be required, but more thought must be put in to whether this is the best approach.

src/less/main.less

+/**
+ * This is the main application stylesheet. It should include or import all
+ * stylesheets used throughout the application as this is the only stylesheet in
+ * the Grunt configuration that is automatically processed.
+ */
+
+
+/**
+ * First, we include the Twitter Bootstrap LESS files. Only the ones used in the
+ * project should be imported as the rest are just wasting space.
+ */
+
+@import '../../vendor/bootstrap/less/bootstrap.less';
+
+
+/**
+ * This is our main variables file. We must include it last so we can overwrite any variable
+ * definitions in our imported stylesheets.
+ */
+
+@import 'variables.less';
+
+
+/**
+ * Typography
+ */
+
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 400;
+  src: local('Roboto Regular'), local('Roboto-Regular'), url(fonts/Roboto-Regular.woff) format('woff');
+}
+
+code, pre, .pre {
+  padding: 5px;
+  margin: 10px 0;
+  background-color: #EFEFEF;
+  border: 1px solid #DADADA;
+  border-radius: 3px;
+}
+
+code {
+  padding: 0 3px;
+}
+
+pre {
+  margin: 10px 0;
+  padding: 5px;
+}
+
+.page-header {
+  margin-top: 60px;
+
+  &:first-child {
+    margin-top: 20px;
+  }
+}
+
+h2 {
+  margin: 20px 0;
+  color: #666;
+}
+
+
+/**
+ * Navigation
+ */
+
+.navbar {
+  margin-top: 20px;
+  
+  small {
+    font-size: 60%;
+  }
+}
+
+
+/**
+ * Footer
+ */
+
+.footer {
+  margin-top: 80px;
+
+  .footer-inner {
+    padding: 40px 0;
+    border-top: 1px solid #DDD;
+  }
+
+  .social {
+    float: right;
+    margin: 0;
+    list-style: none;
+
+    li {
+      float: left;
+      margin-left: 20px;
+
+      a, a:visited {
+        color: @gray-light;
+        text-decoration: none;
+        font-size: 40px;
+        .transition( 250ms ease-in-out );
+
+        &:hover {
+          color: @gray;
+        }
+      }
+    }
+  }
+}
+
+
+/**
+ * Now that all app-wide styles have been applied, we can load the styles for
+ * all the submodules and components we are using. 
+ *
+ * TODO: In a later version of this boilerplate, I'd like to automate this.
+ */
+
+/*  @import '../app/home/home.less'; */
+

src/less/variables.less

+/**
+ * These are the variables used throughout the application. This is where 
+ * overwrites that are not specific to components should be maintained.
+ */
+
+/**
+ * Typography-related.
+ */
+
+@sansFontFamily: 'Roboto', sans-serif;
+