LaxarJS Configuration in an Application

« return to the manuals

LaxarJS has a built-in configuration API which is available to libraries and widgets through the axConfiguration injection. Not to be confused with the laxar.config.js which is only used at build-time by tools such as the laxar-loader, this configuration is designed to be used at application run time.

Preliminary readings:

• Widgets and Activities

What is LaxarJS Configuration Used for?

First, the configuration is used to customize the behavior of a LaxarJS bootstrapping instance. This includes deployment-specific options such as the log-level, so you may want to prepare the configuration outside of the init.js

When writing widgets, it is generally recommended to avoid global configuration options in favor of widget feature configuration, placed in the page definitions. 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, flow, available locales and so on. The LaxarJS Core configuration options are listed below.

Configuration Structure

Configuration keys are simple attribute paths, reflecting the hierarchical configuration structure. The configuration is passed to LaxarJS create when launching your application instance, usually in the init.js:

const laxar = require( 'laxar' );
const adapters = [ /*...*/ ];
const artifacts = require( 'laxar-loadert/artifacts?flow=main' );
const configuration = {
   // ... other configuration options, e.g. logging level ...
   name: 'My App',
   description: 'A well-configured application',
   theme: 'default',
   logging: {
      level: 'WARN'
   }
};

laxar.create( adapters, artifacts, configuration )
   .flow( 'main', document.querySelector( /*...*/ ) )
   .bootstrap();

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 Service

The LaxarJS configuration is exposed as the widget service injection axConfiguration with a single method get( key, fallback ). The key-parameter is the path within the configuration object (passed to laxar.create), and the (optional) fallback is returned as a default value if the key was not set in the configuration.

For example, let us assume that the controller of a "plain" activity called my-activity wants to enable some kind of compatibility behavior for a special foo environment by exposing a Boolean configuration fooMode. By default, the option should be disabled, as compatibility with foo involves jumping through some hoops.

The widget implementation module would then access the option like this:

export const injections = [ 'axConfiguration' ];
export function create( configuration ) {
   const respectFoo = configuration.get( 'widgets.my-activity.fooMode', false );
   if( respectFoo ) {
      // ... jump though some hoops ...
   }
}

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

const configuration = {
   // ... other configuration options, e.g. logging level ...
   widgets: {
      'my-activity': {
         fooMode: true
      }
   }
};
// ... laxar.create ...

No special magic is attached to the widgets sub-key of the configuration, except that it is never used by LaxarJS core or libraries.

Testing a Module that Uses Configuration

To simplify testing, LaxarJS Mocks always uses a mock configuration instance when loading widgets in spec-tests. Refer to the Configuration Mock API docs or to the [LaxarJS Mocks API docs] for details.

Available Configuration Keys

The following configuration options are defined by LaxarJS Core.