Config
internal

This class holds the description of a config property. Only one instance of this class is needed for each config name (e.g., "text"). If config options are supplied, however, they also contribute to the cached instance.

Instances should always be retrieved by calling Config.get().

The Configs of this class correspond to options that can be supplied to the get() method. These affect the behavior of the config property in some way, as descried by their respective documentation.

This class is not used directly.

The Setter

The primary functionality provided by Config is its standard setter. This setter function ensures consistent behavior when modifying config properties.

The standard setter algorithm is as follows (using the 'text' config for illustration):

If the class defines a changeText() method, call it passing the new value and the current value: changeText(newText, oldText).
Then:
- If changeText() exits without returning a value (i.e., undefined), exit and do nothing further. The assumption is that the changer method has done all that is required.
- Otherwise, the return value of changeText() replaces the incoming value passed to the setter.
If the new value (or the value returned by changeText()) is !== to the current value:
- Update the stored config value in this._text.
- If the class defines an updateText() method, call it passing the new value and the previous value. updateText(newText, oldText)
- Any return value from updateText() is stored in this.textUpdated.
- If the class defines an onConfigChange() method, call it passing an object with the following properties:
  - name - The config's name
  - value - The new value
  - was - The previous value
  - config - The Config instance.

NOTE: unlike changeText() and updateText(), the name of the onConfigChange() method is unaffected by the config's name.

No results

Configs

Configs are options you supply in a configuration object when creating an instance of this class

date : Booleanfalse

Indicates that values are Date objects.

equal : Function

internal

A function that compares values for equality. This test is used to determine if the update method should be called when the setter is invoked.

To handle Date values:

 class Foo extends Base {
     static configurable = {
         date : {
             $config : {
                 equal : 'date'
             },

             value : null
         }
     };

     updateDate(date) {
         // date has changed
     }
 }

Also useful for some configs, a custom equal function can be specified. The function is called using the owning instance as the thisObj

 class Foo extends Base {
     static configurable = {
         bar : {
             $config : {
                 equal : ObjectHelper.isEqual
             },

             value : null
         }
     };

     updateBar(value) {
         // value has changed
     }
 }

lazy : Boolean/Stringfalse

internal

Indicates that this config property should not automatically initialize during construction. When this property is set to true, initialization is triggered by the first use of the config property's getter.

This property can alternatively be set to a string, in which case it can be initialized as a group using the triggerConfigs method which will initialize all lazy configs with the same value for this property. Note: the config will still initialize on first use if that occurs prior to the call to triggerConfigs.
nullify : Booleanfalse

internal

Indicates that this config property should automatically be set to null on destroy.
render : Booleanfalse

internal

Indicates that this config participates in rendering. This has does not affect the behavior of the property directly, but allows classes that perform rendering to detect which config changes will affect the rendered result.

Properties

Properties are getters/setters or publicly accessible variables on this class

cache : Object

private

static

This object holds Config instances keyed by their name. For example:

 Config.cache = {
     disabled : Config.get('disabled'),
     text     : Config.get('text'),
     title    : Config.get('title')
 };

convertMethods : Object

internal

static
This object holds config value converter methods.

All methods in this object have the same signature as the convert() method.

This object has the following convert methods:
- array : Converts non-null values into arrays.
- date : Converts values to Date type.
- day : Converts values to Date type and clears the time to midnight.
equalityMethods : Object

private

static
This object holds config value equality methods. By default, the === operator is used to compare config values for semantic equality. When an equal option is specified as a string, that string is used as a key into this object.

All equality methods in this object have the same signature as the equal() method.

This object has the following equality methods:
- array : Compares arrays of values using === on each element.
- date : Compares values of Date type.
- day : Compares values of Date type.
- strict : The default equal algorithm based on === operator.
mergeMethods : Object

internal

static
This object holds config value merge methods. By default, merge is used to merge object's by their properties. Config merge methods are used to combine config values from derived classes with config values from super classes, as well as instance config values with those of the class.

All merge methods in this object have the same signature as the merge() method.

This object has the following merge methods:
- distinct : Combines arrays of values ensuring that no value is duplicated. When given an object, its truthy keys are included, while its falsy keys are removed from the result.
- merge : The default merge algorithm for configurable() properties, based on merge.
- items : Similar to merge, but allows reordering (see ObjectHelper.mergeItems).
- objects : The same as to merge except this method promotes true to an empty object.
- 'classList' : Incoming strings are converted to an object where the string is a property name with a truthy value.
- replace : Always returns newValue to replace the super class value with the derived class value, or the class value with the instance value.

descriptor : Object

private

READONLY

The descriptor to use with Reflect.defineProperty() for defining this config's getter and setter.
initDescriptor : Object

private

READONLY

The descriptor to use with Reflect.defineProperty() for defining this config's initter.

Functions

Functions are methods available for calling on the class

get( name, options )
: Config

internal

static

Returns the Config instance for the given name and options.
makeArrayEquals( fn )
: Function

private

static

Returns an equality function for arrays of a base type, for example 'date'.
makeCacheKey( name, options )
: String

private

static

Returns the key to use in the Config cache.

convert( value, instance )
: *

internal

This method converts a value presented to the setter to the value that will be processed by config hook methods (e.g., changeFoo and updateFoo).
define( target )

internal

Defines the property on a given target object via Reflect.defineProperty(). If the object has its own getter, it will be preserved. It is invalid to define a setter.
defineInitter( target, value )

internal

Defines the property initter on the target. This is a property getter/setter that propagates the configured value when the property is read.
equal( value1, value2 )
: Boolean

internal

This method compares two values for semantic equality. By default, this is based on the === operator. This is often overridden for configs that accept Date or array values.
extend( options )
: Config

internal

Extends this config with a given additional set of options. These objects are just prototype extensions of this instance.
makeDescriptor( )
: Object

private

Creates and returns a property descriptor for this config suitable to be passed to Reflect.defineProperty().
makeInitter( )
: Object

private

Creates and returns a property descriptor for this config's initter suitable to pass to Reflect.defineProperty().
merge( newValue, currentValue, metaNew, metaCurrent )
: *

internal
This method combines (merges) two config values. This is called in two cases:
- When a derived class specifies the value of a config defined in a super class.
- When a value is specified in the instance config object.
removeInitter( instance )

private

Removes the property initter and restores the instance to its original form.

Source path

Core/Config.js

Inheritance tree1

Config

Config internal