add overlay-config

CHANGELOG.md

@@ -17,6 +17,16 @@ and this project adheres to
   Adding them to the framework makes these dependencies available from the
   framework to those MUMAA apps on upgrade as well as available to any other
   upgrading apps.
++ Add `overlay-config`, a module intended for overlaying upon in tier-specific
+  overlays on uportal-app-framework applications.
+  overlay-config by default is an empty module.
+  Replace that file in tier-specific overlays to set tier-specific settings.
+  That is, the layers are
+  a tier-specific overlay (overrides overlay-config to set tier-specifics)
+  overlays upon
+  an application (overrides override.js to set app options etc)
+  overlays upon
+  this framework.
 
 ## 17.0.1
 

components/config.js

@@ -59,6 +59,7 @@ define(['./my-app/app-config.js'], function(myAppConfig) {
       'app-config': 'js/app-config',
       'frame-config': 'js/frame-config',
       'override': 'js/override',
+      'overlay-config': 'js/overlay-config',
       'moment': 'https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.19.1/moment.min',
   };
 
@@ -81,6 +82,7 @@ define(['./my-app/app-config.js'], function(myAppConfig) {
         deps: ['angular', 'ngAria', 'angular-animate', 'angular-mocks'],
         exports: 'ngMaterial',
       },
+      'overlay-config': {deps: ['angular']},
       'ui-bootstrap': {deps: ['angular']},
       'ui-gravatar': {deps: ['angular']},
       'ui.select': {deps: ['angular']},

components/js/overlay-config.js

@@ -0,0 +1,10 @@
+define(['angular'], function(angular) {
+  return angular.module('overlay-config', []);
+  // replace this file in tier-specific overlay with
+  // a fork of this file that defines an overlay-config module
+  // with the definition specific to that tier.
+  //
+  // (Typically, declaring values for constants such that these values differ
+  // by tier, e.g. specifying use of mocks in some tiers and of live data in
+  // other tiers.)
+});

docs/configuration.md

@@ -193,6 +193,29 @@ list][uportal-user@].
 Collaborating on developing `uPortal-app-framework`? Discuss on [the
 development list][uportal-dev@].
 
+## Tier-specific application configuration
+
+One option is to additionally override `override.js` in tier-specific overlays.
+This has the advantage that anything configurable in `override.js`
+(that is, anything configured in app-config), and an additions to that,
+are arbitrarily configurable in tier-specific overlays. This is powerful.
+It also may duplicate application configuration that's the same in all tiers
+into tier-specific overlays because it replaces the application's `override.js`
+configuration of the frame.
+
+Another, complementary option is to override `overlay-config.js` in
+tier-specific overlays. This has the advantage of *not* being `override.js` and
+so not clobbering whatever the application was doing in `override.js`.
+This has the disadvantage of *not* being `override.js` and so not overriding
+`app-config`. The framework has no current special support for
+ `overlay-config.js` -- that is, the framework does not expect anything of that
+ module, does not use it for anything, and does not consult it in interpreting
+ framework configuration. `overlay-config` is currently whatever the downstream
+ applications make of it -- if a particular application invents a constant
+ configured in that module and gives that constant meaning, then that constant
+ becomes configurable per-tier by overriding the implementation of this module
+ in tier-specific overlays.
+
 [KeyValueStore]: https://github.com/UW-Madison-DoIT/KeyValueStore
 [uportal-dev@]: https://groups.google.com/a/apereo.org/forum/#!forum/uportal-dev
 [uportal-user@]: https://groups.google.com/a/apereo.org/forum/#!forum/uportal-user