feat(app generator): add ability to retrieve a build distribution tar…

…get-environment's settings at run-time

Replace madlib-hostmapping based solution.

generators/app/index.js

@@ -340,6 +340,10 @@ var AppGenerator = generators.Base.extend(
                     ,   'src/style/images/debug/'
                     ,   'src/style/images/sprites/'
 
+                        //  Target environment settings:
+
+                    ,   'settings'
+
                         //  Testing:
 
                     ,   'test'
@@ -391,6 +395,7 @@ var AppGenerator = generators.Base.extend(
 
                     ,   [ 'src/collections/api-services.coffee' ]
                     ,   'src/models/api-service.coffee'
+                    ,   [ 'src/models/settings-environment.coffee' ]
 
                         //  Style and Compass:
 
@@ -405,6 +410,15 @@ var AppGenerator = generators.Base.extend(
                     ,   'src/sass/debug.sass'
                     ,   'src/style/images/debug/internals.jpg'
                     ,   'src/style/images/sprites/check-green.png'
+
+                        //  Target environment settings:
+
+                    ,   'settings/@README.md'
+                    ,   [ 'settings/production.json' ]
+                    ,   [ 'settings/acceptance.json' ]
+                    ,   [ 'settings/testing.json' ]
+                    ,   [ 'settings/local.json' ]
+
                     ]
                 ;
 
@@ -462,7 +476,6 @@ var AppGenerator = generators.Base.extend(
                         'backbone'
                     ,   'backbone.cocktail'
                     ,   ( 'jquery' + ( data.ie8 ? '@<2' : '' ))
-                    ,   'madlib-hostmapping'
                     ,   'madlib-settings'
                     ,   'q'
                     ,   'underscore'

generators/app/templates/@Gruntfile.coffee

@@ -14,6 +14,9 @@
 ##            * dist/app/   - collects the app's build results
 ##            * dist/doc/   - collects the app's code documentation
 ##
+##        * Source directory for per target-environment settings
+##            * settings/
+##
 ##        * Tests directory:
 ##            * test/
 ##
@@ -22,7 +25,7 @@
 ##        * The application
 ##        * The application's code documentation
 ##
-##    * The build's target environment:
+##    * The build's target-environment:
 ##        * local
 ##        * testing
 ##        * acceptance
@@ -32,6 +35,7 @@
 ##        * app<@ if ( i18n ) { @>
 ##            * i18n<@ } @>
 ##            * style
+##            * target-environment settings
 ##            * brief
 ##            * bootstrap
 ##        * documentation
@@ -76,13 +80,14 @@
 ##        * A debugging build implies as-is packing.
 ##        * Minified packing implies a non-debugging build.
 ##
-##    * A for-acceptance targetted build is identical to a for-production build.
+##    * The build environment directly determines the default target-environment settings's build part's source.
 ##
 ##    * The build's artifacts are an all-or-nothing deal, currently.
 ##
 ##    * The build parts can be processed seperately, but some depend on others:
 ##          * The bootstrap build part needs a brief.
-##          * The app build part will also trigger builds of the <@ if ( i18n ) { @>i18n, <@ } @>style, brief, and bootstrap build parts.
+##          * The app build part will also trigger builds of the <@ if ( i18n ) { @>i18n, <@ } @>style, target-environment settings, brief, and bootstrap
+##            build parts.
 ##
 ##
 ##  Mapping to grunt tasks and targets:
@@ -121,6 +126,12 @@
 ##                            (Note that this variant doesn't exit. Instead, it'll keep a close watch on
 ##                            filesystem changes, selectively re-triggering part builds as needed)
 ##
+##
+##  The `--target` command line option sets the build target environment.
+##  So, for an for-acceptance, non-debugging, all-parts, tested, minified build, do:
+##
+##      * grunt --target acceptance
+##
 ##  ====
 ##
 
@@ -158,10 +169,17 @@ module.exports = ( grunt ) ->
                 app:                    '<%= build.dist %>app/'
                 doc:                    '<%= build.dist %>doc/'
 
+            settings:                   'settings/'
             test:                       'test/'
 
             artifactBase:               '<%= build.dist %><%= npm.name %>-<%= npm.version %>'
 
+            ##
+            ##  This is the default build environment but may be overridden by the 'environment' task
+            ##
+
+            environment:                'production'
+
             ##
             ##  Parts:
             ##
@@ -202,6 +220,10 @@ module.exports = ( grunt ) ->
                     src:                '<%= build.source %>i18n/'
                     tgt:                '<%= build.assembly.app %>i18n/'<@ } @>
 
+                settings:
+                    src:                '<%= build.settings %><%= build.environment %>.json'
+                    tgt:                '<%= build.assembly.app %>settings.json'
+
                 style:
                     src:
                         copy:           '<%= build.source %>style/'
@@ -348,6 +370,11 @@ module.exports = ( grunt ) ->
                     src:                '<%= build.part.i18n.tgt %>'
                 ]<@ } @>
 
+            settings:
+                files: [
+                    src:                '<%= build.part.settings.tgt %>'
+                ]
+
             style:
                 files: [
                     src:                '<%= build.part.style.tgtDir %>'
@@ -558,6 +585,13 @@ module.exports = ( grunt ) ->
                     dest:               '<%= build.part.i18n.tgt %>'
                 ]<@ } @>
 
+            settings:
+                files: [
+                    filter:             'isFile'
+                    src:                '<%= build.part.settings.src %>'
+                    dest:               '<%= build.part.settings.tgt %>'
+                ]
+
             style:
                 files: [
                     filter:             'isFile'
@@ -610,6 +644,8 @@ module.exports = ( grunt ) ->
 
                         grunt.fail.fatal( "Unable to read the build brief (\"#{file}\"). Wasn't it created?" ) unless brief?.timestamp
 
+                        environment:    brief.environment
+
                         app:            path.relative( grunt.config( 'build.assembly.app' ), grunt.config( 'build.part.app.tgt' ))
                         style:          path.relative( grunt.config( 'build.assembly.app' ), grunt.config( 'build.part.style.tgt' ))
                         styleBase:      path.relative( grunt.config( 'build.assembly.app' ), grunt.config( 'build.part.style.tgtDir' ))
@@ -685,6 +721,7 @@ module.exports = ( grunt ) ->
                     ##
                                         '<%= build.part.app.tgt %>'<@ if ( i18n ) { @>
                                         '<%= build.part.i18n.tgt %>**/*'<@ } @>
+                                        '<%= build.part.settings.tgt %>'
                                         '<%= build.part.style.tgtDir %>**/*.css'
 
                     ##                  Watch for changed bootstrap - source -
@@ -702,6 +739,13 @@ module.exports = ( grunt ) ->
                 ]
                 tasks:                  'i18n'<@ } @>
 
+            settings:
+                files:                  '<%= build.part.settings.src %>'
+                tasks: [
+                                        'environment:<%= build.environment %>'
+                                        'settings'
+                ]
+
             style:
                 files: [
                                         '<%= build.part.style.src.copy %>**/*'
@@ -795,6 +839,7 @@ module.exports = ( grunt ) ->
                 revision:       process.env.GIT_COMMIT or 'working dir'
 
                 grunted:        grunt.template.date( stamp, 'yyyy mmm dd HH:MM:ss' )
+                environment:    grunt.config( 'build.environment' )
                 debugging:      ( debugging is 'debug' )
 
                 name:           grunt.config( 'npm.name' )
@@ -807,6 +852,20 @@ module.exports = ( grunt ) ->
             return
     )
 
+    grunt.registerTask(
+        'environment'
+        'Set the target environment'
+        ( environment ) ->
+
+            if ( ( override = grunt.option( 'target' ) ? process.env.GRUNT_TARGET )? and override isnt environment )
+                grunt.log.ok( "Overriding target environment to #{override}" )
+                environment = override
+
+            grunt.config.set( 'build.environment', environment ) if environment?
+
+            return
+    )
+
 
     ##  ================================================
     ##  Per build part tasks:
@@ -823,6 +882,7 @@ module.exports = ( grunt ) ->
 
                 "browserify:app_#{debugging}"<@ if ( i18n ) { @>
                 'i18n'<@ } @>
+                'settings'
                 "style:#{debugging}"
 
                 ##  brief before bootstrap
@@ -892,6 +952,15 @@ module.exports = ( grunt ) ->
             )
     )
 
+    grunt.registerTask(
+        'settings'
+        'Build the build\'s target environment\'s settings.'
+        [
+            'clean:settings'
+            'copy:settings'
+        ]
+    )
+
     grunt.registerTask(
         'style'
         'Build the app\'s stylesheet and related assets'
@@ -913,6 +982,8 @@ module.exports = ( grunt ) ->
         [
             'clean:dist'
 
+            'environment:production'
+
             'app:dist'
 
             'uglify:app'
@@ -931,6 +1002,8 @@ module.exports = ( grunt ) ->
         [
             'clean:dist'
 
+            'environment:testing'
+
             'app:debug'
 
             'test'
@@ -944,6 +1017,8 @@ module.exports = ( grunt ) ->
         [
             'clean:dist'
 
+            'environment:local'
+
             'app:debug'
 
             'watch'

generators/app/templates/settings/@README.md

@@ -0,0 +1,51 @@
+### About target-environment settings
+
+This directory contains one settings JSON file per each build distribution's target-environment:
+
+    * local (aka developement)
+    * testing`
+    * acceptance
+    * production
+
+Settings to be determined in such a file include:
+
+    setting         | explanation
+    :---            | :---
+    `environment`   | The target-environments name (production, acceptance, testing, staging, local, etc). Should really be identical to the settings file's name (excluding the `.json` extension).
+    `apiBaseUrl`    | The base URL of the API to use.
+    `locales`       | A list of available locales.
+
+Feel free to add further files to this directory as you see fit; for instance `<yourname>.js` for your personal local development configuration.
+
+Just keep in mind that the [`Gruntfile.coffee`](../Gruntfile.coffee) is tailored towards using the defaults outlined above, and that you would need to supply a
+`--target <environment>` argument to the `grunt` command to override that default.
+
+So, to target a development build distribution to use settings different from `local.json`, f.i. `<yourname>.js`, use
+
+```sh
+grunt --target <yourname> dev`
+```
+
+To target a production build distribution to use the `acceptance.json` settings instead of `production.json`, use:
+
+```sh
+grunt --target acceptance`
+```
+
+#### Example settings file
+
+```json
+{
+    "environment": "production"
+,   "apiBaseUrl": "/api"
+,   "locales":
+        {
+            "en-GB":    "English"
+        ,   "en-US":    "English (US)"
+        ,   "nl-NL":    "Nederlands"
+        }
+}
+```
+
+For more detailed information on builds, distributions and target-environments, see the introductory comments included within the 
+[`Gruntfile.coffee`](../Grunfile.coffee)

generators/app/templates/settings/acceptance.json

@@ -0,0 +1,8 @@
+{
+    "apiBaseUrl": "/api"
+,   "environment": "acceptance"<% if ( i18n ) { %>
+,   "locales":
+        {
+            "<%- i18nLocaleDefault %>":    "<%- i18nLocaleDefaultLanguage %> (<%- i18nLocaleDefaultRegion %>)"
+        }<% } %>
+}

generators/app/templates/settings/local.json

@@ -0,0 +1,8 @@
+{
+    "apiBaseUrl": "/api"
+,   "environment": "local"<% if ( i18n ) { %>
+,   "locales":
+        {
+            "<%- i18nLocaleDefault %>":    "<%- i18nLocaleDefaultLanguage %> (<%- i18nLocaleDefaultRegion %>)"
+        }<% } %>
+}

generators/app/templates/settings/production.json

@@ -0,0 +1,8 @@
+{
+    "apiBaseUrl": "/api"
+,   "environment": "production"<% if ( i18n ) { %>
+,   "locales":
+        {
+            "<%- i18nLocaleDefault %>":    "<%- i18nLocaleDefaultLanguage %> (<%- i18nLocaleDefaultRegion %>)"
+        }<% } %>
+}

generators/app/templates/settings/testing.json

@@ -0,0 +1,8 @@
+{
+    "apiBaseUrl": "/api"
+,   "environment": "testing"<% if ( i18n ) { %>
+,   "locales":
+        {
+            "<%- i18nLocaleDefault %>":    "<%- i18nLocaleDefaultLanguage %> (<%- i18nLocaleDefaultRegion %>)"
+        }<% } %>
+}