Skip to content

Component Registry

Every component have at least one component registry with the id main. You can add more registries with this.registerRegistry(Id). A registry basically predefine component start objects with a fixed id and target stage. Components can be organized hierarchical.

The main registry can be referenced with this.registry or more verbose this.getRegistry("main").

The idea behind of a component registry is a collection where all possible child components can be registered and not loaded. Other functions can reference it and trigger the loading of the registered components.

The structure of a registry is an object holding component start definition objects in each key. The absolute minimum that a start definition object must contain is the component property. If this property is missing, the object is ignored.

Each start definition object can have additional properties. All of them are optional:

  • manifest: Overwrite default manifest of component which is defined in defaults.$manifest.
  • restrictions: Overwrite default authentication settings of component which is defined in defaults.$auth.restrictions.
  • stage: Target stage name in which the component should be loaded. Default to main if not specified.

Please note the following: The manifest and restrictions properties are also used as options when the component is loaded. They override any $manifest and $auth.restrictions options that may have been specified.

Handling of id

The property id of each start definition object can be set to a specific value. If not set the key of the start definition object will be used:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "key1": {
    /* Start Definition Object without "id" */
  }
}

// Will be converted to:

{
  "key1": {
    id: "key1"
    /* Rest of Start Definition Object */
  }
}

Please note the difference between the key in the registry and the optional id of a component. You can even define the same component with the same id under different keys:

{
    key1: {
      id: "the_id_1",
      component: SomeComponent,
      options: {
        opt1: "First Value"
      }
    },
    key2: {
      id: "the_id_2",
      component: SomeComponent,
      options: {
        opt1: "Second Value"
      }
    },
}

In the example above you can start the component with key1 or with key2 as separate instances with different options.

Here another example:

{
    key1: {
      id: "the_id",
      component: SomeComponent,
      options: {
        opt1: "First Value"
      }
    },
    key2: {
      id: "the_id",
      component: SomeComponent,
      options: {
        opt1: "Second Value"
      }
    },
}

In the example above you can start the same component instance (because of the same id) with key1 or with key2 with different options. If the component was already started just the new options will be passed and the the running component will be fronted.

Nested Components

To define a subgroup, you must add an object with the property type: "group" and contents: {}. You can also define it as you would in a start definition object, if you wish:

  • manifest: With the properties name and iconHtml for the visual representation of the subgroup.
  • restrictions: Authentication restrictions of the subgroup.

The object defined in the property content will function as the root object of the registry, with keys handled as regular start definition objects within a sub-group (which can, of course, be a group or regular start definition object itself).

If the “content” property is missing, is not an object, or is an empty object, the group will be ignored!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    subGroup: {
      type: "group",
      manifest: {
        name: "...",
        iconHtml: "..."
      },
      restrictions: {
        required: false,
        roles: [],
        permissions: [],
        groups: []
      },
      content: {
        key1: {
          // Registry entry, component or group
        },
        key2: {
          // Registry entry, component or group
        }
      }
    }
}

Reference

add(registry):

Will add the given registry structure to the existing one. The existiing and the new one will be merged.

get(id)

Returns the registry entry with the specified id. If the id is not specified, the whole registry will be returned.

If no ID is found or the registry contains no objects, null is returned.

You can specify deeper nested id's with the dot notation: group1.key1.group2.key2 etc. You do not need to use content after specifying the group ID, even though it might seem logical to do so. The following IDs are identical: group1.content.key2 and group1.key2.

The returned objects do not contain any start definition objects for which the component property has not been defined, nor any groups that have an invalid or empty content property.

The returned objects will have always the property id set. Either the one specified in the registry or the one derived from the key of the start definition object

Unless you set the noMerge argument to true: The returned objects will have always the property manifest set. This contains the default manifest of the component merged with the optional overrides in the registry.

Unless you set the noMerge argument to true: The returned objects will have always the property restrictions set. This contains the default authentication restrictions of the component merged with the optional overrides in the registry.

async load(id, overrides)

Trigger the loading of the registered component with the specified id. Optional you can define an object that overrides properties of the registered start definition object.

Hint: Like in the load function of the stage, if the component was already started just the new options will be passed and the the running component will be fronted.

async destroy(id)

Trigger the destroying of the registered component.

getInstance(id)

Returns the running instance of the specified id.