src/app/README.md

   1 # The `src/app` Directory
   2
   3 ## Overview
   4
   5 ```
   6 src/
   7   |- app/
   8   |  |- home/
   9   |  |- about/
  10   |  |- app.js
  11   |  |- app.spec.js
  12 ```
  13
  14 The `src/app` directory contains all code specific to this application. Apart
  15 from `app.js` and its accompanying tests (discussed below), this directory is
  16 filled with subdirectories corresponding to high-level sections of the
  17 application, often corresponding to top-level routes. Each directory can have as
  18 many subdirectories as it needs, and the build system will understand what to
  19 do. For example, a top-level route might be "products", which would be a folder
  20 within the `src/app` directory that conceptually corresponds to the top-level
  21 route `/products`, though this is in no way enforced. Products may then have
  22 subdirectories for "create", "view", "search", etc. The "view" submodule may
  23 then define a route of `/products/:id`, ad infinitum.
  24
  25 As `ngBoilerplate` is quite minimal, take a look at the two provided submodules
  26 to gain a better understanding of how these are used as well as to get a
  27 glimpse of how powerful this simple construct can be.
  28
  29 ## `app.js`
  30
  31 This is our main app configuration file. It kickstarts the whole process by
  32 requiring all the modules from `src/app` that we need. We must load these now to
  33 ensure the routes are loaded. If as in our "products" example there are
  34 subroutes, we only require the top-level module, and allow the submodules to
  35 require their own submodules.
  36
  37 As a matter of course, we also require the template modules that are generated
  38 during the build.
  39
  40 However, the modules from `src/common` should be required by the app
  41 submodules that need them to ensure proper dependency handling. These are
  42 app-wide dependencies that are required to assemble your app.
  43
  44 ```js
  45 angular.module( 'ngBoilerplate', [
  46   'templates-app',
  47   'templates-common',
  48   'ngBoilerplate.home',
  49   'ngBoilerplate.about'
  50   'ui.state',
  51   'ui.route'
  52 ])
  53 ```
  54
  55 With app modules broken down in this way, all routing is performed by the
  56 submodules we include, as that is where our app's functionality is really
  57 defined.  So all we need to do in `app.js` is specify a default route to follow,
  58 which route of course is defined in a submodule. In this case, our `home` module
  59 is where we want to start, which has a defined route for `/home` in
  60 `src/app/home/home.js`.
  61
  62 ```js
  63 .config( function myAppConfig ( $stateProvider, $urlRouterProvider ) {
  64   $urlRouterProvider.otherwise( '/home' );
  65 })
  66 ```
  67
  68 Use the main applications run method to execute any code after services
  69 have been instantiated.
  70
  71 ```js
  72 .run( function run () {
  73 })
  74 ```
  75
  76 And then we define our main application controller. This is a good place for logic
  77 not specific to the template or route, such as menu logic or page title wiring.
  78
  79 ```js
  80 .controller( 'AppCtrl', function AppCtrl ( $scope, $location ) {
  81   $scope.$on('$stateChangeSuccess', function(event, toState, toParams, fromState, fromParams){
  82     if ( angular.isDefined( toState.data.pageTitle ) ) {
  83       $scope.pageTitle = toState.data.pageTitle + ' | ngBoilerplate' ;
  84     }
  85   });
  86 })
  87 ```
  88
  89 ### Testing
  90
  91 One of the design philosophies of `ngBoilerplate` is that tests should exist
  92 alongside the code they test and that the build system should be smart enough to
  93 know the difference and react accordingly. As such, the unit test for `app.js`
  94 is `app.spec.js`, though it is quite minimal.