« return to the manuals

Preliminary readings:

• Widgets and Activities

LaxarJS Configuration in an Application

LaxarJS has a built-in configuration API which is available to libraries and widgets as laxar.configuration. In contrast to the bower- and RequireJS-configuration, this configuration is designed to be used at application run time.

What is LaxarJS Configuration Used for?

When writing widgets, it is generally recommended to avoid global configuration options in favor of widget feature configuration. Sometimes however, a single setting must be respected across a large number of widgets: For example, all widgets should use the same validation trigger (on change vs. on focus-out) to guarantee a consistent user experience.

In other cases, LaxarJS itself needs to be configured, for example to determine the theme, file listing URIs, available locales and so on. The LaxarJS Core configuration options are listed below.

Configuration Structure

Configuration keys are simple JSON paths, reflecting a hierarchical configuration structure. The configuration API looks for the configuration values within the laxar property of the global object (window).

Libraries, widgets and activities may define their own configuration keys, but must always use the lib. prefix, followed by a suitable module identifier (e.g. the name of the library vendor) to avoid name collisions. For example, LaxarJS UiKit controls use the prefix lib.laxar-uikit.controls for their configuration options. Keys without the lib.-prefix are used by LaxarJS Core.

The Configuration API

The LaxarJS configuration exposes a single method laxar.configuration.get( key, fallback ). The key-parameter is the path within the configuration object (window.laxar), and the (optional) fallback is returned as a default value if the key was not set in the configuration.

For example, a module my_module may allow to enable some kind of compatibility behavior for a special foo environment by exposing a boolean configuration fooCompatibility. By default, the option should be disabled as compatibility with foo involves jumping through some hoops. The module my_module would then access the option like this:

define( [ 'laxar' ], function( ax ) {
  function setup() {
     var respectFoo = ax.configuration.get( 'lib.my_module.fooCompatibility', false );
     if( respectFoo ) {
        // ... jump though some hoops ...
        return { hoops: 'JUMPED' };
     }
     return {};
  }
} );

And the corresponding configuration block to enable foo-compatibility would then look like this:

window.laxar = {
   // ...
   lib: {
      my_module: {
         fooCompatibility: true
      },
      // ...
   }
};

Testing a Module that Uses Configuration

To test the behavior of a module with test-controlled configuration options, one can simply spy on the method configuration.get. Here is an exemplary jasmine test for a module my_module, which tries to test the module behavior with foo-compatibility enabled.

define( [ 'laxar/laxar_testing', 'my_module' ], function( ax, myModule ) {
   describe( 'a my_module with foo compatibility enabled', function() {
      beforeEach( function() {
         var origGet = ax.configuration.get;
         var hoops;
         spyOn( ax.configuration, 'get' ).andCallFake( function( key, fallback ) {
            return key === 'lib.my_module.fooCompatibility' ? true : origGet( key, fallback );
         } );
         hoops = setup();
      } );
      it( 'jumps through some hoops', function() {
           expect( hoops ).toBe( 'JUMPED' );
      } );
   } );
} );

Injecting Configuration into an AngularJS module

Instead of using RequireJS, AngularJS modules such as widgets can have the configuration module injected by requesting the service 'Configuration'. In cases where configuration is injected, an angularMocks.module provider may be defined during testing instead of the approach described above.

Available Configuration Keys in LaxarJS Core

The following configuration options are available in LaxarJS Core. For options available in LaxarJS UiKit, have a look at the respective documentation.