Options: System Wide Defaults

What are we learning here?

                                                                                ┌──────────────┐
                                                                                │   Change     │
                                                                                │   Options    │
                                                                                └───────┬──────┘
                 ┌──────────────┐ ┌─────────────────────────────────────────────────────┼──────┐
                 │ Loading      │ │ Component                                           │      │
                 │ Component    │ │                                                     │      │
                 │ ┌──────────┐ │ │                         ┌──────────────────┐   ╔════▼════╗ │
                 │ │ options  ├─┼─┼───Transform────────────►│ Received Options ├──►║ Final   ║ │
                 │ └──────────┘ │ │   (optional)            └────────▲─────────┘   ║ Options ║ │
                 │              │ │                                Merge           ╚════╤════╝ │
                 │ ┌──────────┐ │ │ ┌───────────────────┐   ┌────────┴─────────┐   ┌────▼────┐ │
┌──────────────┐ │ │ settings ├─┼─┼►│ Received Settings ├──►│ Merged Settings  │   │ ! Watch │ │
│ Parent       │ │ └──────────┘ │ │ └──────────▲────────┘   └────────▲─────────┘   └─────────┘ │
│ Component    │ └──────────────┘ │          Merge                 Merge                       │
│ ┌──────────┐ │                  │ ┌──────────┴────────┐            │                         │
│ │ Received ├─┼──────────────────┼►│ Parent Settings   │            │                         │
│ │ Settings │ │                  │ └───────────────────┘            │                         │
│ └──────────┘ │                  │                                  │                         │
└──────────────┘                  │ ┌───────────────────┐   ┌────────┴─────────┐               │
                                  │ │ Static Defaults   ├──►│ Merged Defaults  │               │
                                  │ └──────────▲────────┘   └──────────────────┘               │
                                  │          Merge                                             │
                                  └────────────┼───────────────────────────────────────────────┘
                                  ┌────────────┼──────────┐
                                  │ Base Component        │
                                  │ ┌──────────┴────────┐ │
                                  │ │ Static Defaults   │ │
                                  │ └──────────▲────────┘ │
                                  └──────────Merge────────┘
                                  ┌────────────┼──────────┐
                                  │ Base Component        │
                                  │ ┌──────────┴────────┐ │
                                  │ │ Static Defaults   │ │
                                  │ └───────────────────┘ │
                                  └───────────────────────┘

---

• Set defaults for the whole system or parts of it

You have two options to pass overriding options. We just got to know the first alternative. The options are passed using the load method. Either in the short version:

this.load(YourComponent, { /* Define "options" here */});

Or per start definition object:

this.load({
  component: YourComponent,
  options: {}              //Define "options" here
})

The second one can only be done per start definition object. The property you have to use is settings. This would look like:

this.load({
  component: YourComponent,
  settings: {}              //Define "settings" here
})

The "settings" have a very special meaning because they are used for the component to be loaded and all other child components loaded by this component. Settings are valid for the entire component hierarchy from this point on.

Since we call the complete component hierarchy “system”, settings can therefore define so-called “system wide defaults” or sometime just "partial system wide defaults".

There are several useful applications for system wide defaults. One of them, for example, is the authentication mechanism, which is set in the root component and can be used by every component. More on that later.

Each application can set any settings that are adopted in all defaults. And that's why you should be careful not to pollute the root level.

As a best practice you should either use your own namespace or put individual properties in the designated key $globals:

// Use the $globals key:
this.load({
  component: YourComponent,
  settings: {
    $globals: {
      yourGlobalThing: something
    }
  }
})
// Access the global somewhere later:
this.options.$globals.yourGlobalThing;

To change the own "setting" which should propagated to all child component you can use the setter this.env.settings. It works like the setter this.options which merge all properties to the existing ones:

this.env.settings = {
  $globals: {
    yourGlobalThing: something
  }
}
// All components that will be loaded from now receive the settings and inherit to all it's childs.
// Settings will also applied to the own options. You can from here on access the values with
// `this.options.$globals`