freeipa/install/ui/doc/guides/registries

Components registration and build

This document contains design of component build system.

Build system

Build system is the core of Web UI. Its task is to create instance from components definition (spec object).

The system consists of:

• registries
• builders
• component classes for registration
• nested component specification

Registries

We can have two types of registries:

• constructor registries
• singleton registries

Constructor registry

Constructor registry holds information required for building an object. It's basically a map with component type as a key and {factory, constructor, default specification} as value. For successful registration one must provide a component type, and factory or a constructor. Default specification object is not required.

Both constructors and factories should not expect more than one parameter. The only param which they will receive is a specification object.

Singleton registry

Singleton registry is a object which stores [component_name, instance] pairs. The difference between singleton registry and normal JavaScript object is that the registry is supposed to create the instance if it doesn't exist when requested.

To accomplish such task registry has to have a factory or a component constructor and a specification object available. This values might be stored in a constructor registry. Therefore singleton registry might internally contain constructor registries.

Build

The build process has a general rule: Each component handles the build of its children. It's expected that the component knows what type of children it's supposed to contain and therefore it knows how to build them. Usually that means that it knows which builder to use.

To allow smooth transition, we need to support building object by using various methods: registry, factory and constructor. When using registry, we may also want to allow applying some defaults. Therefore spec object may contain following build related properties to tell how it should be build. Each build property should have $ prefix to distinguish it from spec properties.

• $type: string - component type
• $factory: factory function which expects this spec. obj. as param
• $ctor: constructor function which expects this spec. obj. as param
• $mixim_spec: boolean indicating that multiple specification objects can be mixed in.
• $pre_ops: operations which modify spec before instantiation
• $post_ops: operations which modify object after instantiation

Builder

We can see that the build process is moderately complex and therefore it should not be done by parent components. It's a task for a builder.

Additionally builder must deal with following conditions:

• to have or to not have associated constructor registry
• handle only string or a function as a spec object
• handle already built object
• handle array of spec

Builders tasks

1. get factory or constructor function
2. make copy of spec object
3. remove reserved properties from spec object
4. call factory|constructor with a copy of spec object as param
5. return built instance

Get factory or constructor function

The flow depends on:

• type of spec object (object, string, function)
• presence of Constructor registry

If more than one specification is defined (type, constructor, factory) the order of precedence is:

1. factory
2. constructor
3. type (registry contain spec) a. factory b. constructor

Distinguishing between methods

Methods are distinguished by type of spec object or it's properties.

Type

• spec is string
• spec is Object and spec.type is string
• spec in registry is evaluated the same way except that it shouldn't contain type property.

Factory

• spec is function
• spec is Object and spec.factory is function

Constructor

• spec is function and with extend method (indicates that it's dojo class)
• spec is Object and spec.constructor is function

Builder must have a reference to Constructor registry for Type method to be able to build the object, otherwise it doesn't have constructor or factory available, unless builder has defaults set.

Builder defaults

Builder can have default values for factory or constructor. It's useful for builders which specializes in building one object type. Ie. widget builder might have text_widget as a default.

String modes

Builder supports two behaviors when spec is a string: type and property.

type

String specifies object type - default

property

String represents a value of spec property. Spec property is specified by string_property builder property. One has to make sure that builder has default factory or a constructor set when using this mode.

Conflicts of specification objects

When spec is an Object and Constructor registry has also defined default specification object, only the supplied spec is used. This behavior might be overridden by setting mixim_spec attribute of supplied spec to true. In such case supplied spec is mixed in a default spec. Setting mixim_spec in default spec doesn't have any effect, it's ignored.

Spec modification - pre_ops

pre_ops' purpose is to modify spec object. Pre_ops can be specified at locations ordered by execution order as follows:

• builder: applies to all objects
• construct registry: applies to objects with given type
• spec: applies only to the one object

Types of operations

Pre_op can be function, object or diff object.

Function

Takes two params: spec and context. Has to return spec. It can replace the spec by other object but it has make sure that it returns something. Returned spec will replace the previous one.

Object

Plain object is mixed in into spec object

Diff object

Diff object is applied on spec by spec_mod utility. Control properties are removed and then remains are mixed in into spec as if it was just plain object.

Object modification - post_ops

post_ops are similar to pre_ops but their purpose is to modify the created object. Post_ops can only be functions and objects, no diff objects. Functions receive obj, spec and context as params and have to return obj.

Global registries for builders and registries

Web UI has several object types: entities, facets, widgets, fields, actions, validators, entity policies, facet policies. Each object type requires its builder, construct registry and some also a singleton registry. Two umbrella pseudo-registries were created to avoid creation of twice as many modules and also to allow redefinition of the registries: reg and builder.

reg is a registry of construct registries or singleton registries. Difference between normal registry is that one can access its registries directly.

builder is a registry of builders. Each object type may have its own builder with different defaults, pre_ops, post_ops and construct registry. Construct registry is usually the one registered in reg under the same type name. Builder also serves as general build interface so one don't have to obtain the builder first. It's interface is:

var new_obj = builder.build(object_type, spec, context, overrides);

builder contains general builder - a builder without any defaults. It can be used when there is a need to use builder logic but it doesn't require any defaults:

var new_obj = builder.build('', spec, context, overrides);

Examples

For demonstration purposes examples will use action as a framework object

Registration of builder and registry to global registries

// './facet_registry.js'
define(['./builder', './reg'], function(builder, reg) {

    var  exp = {};

    var exp.action = function(spec) {
        //fac definition
    };

    // Registration of Action builder and registry into global registries
    // ./builder can create new builder just by calling `get` with
    // not-yet-registered type
    exp.action_builder = builder.get('action');

    // setting default factory
    exp.action_builder.factory = exp.action;

    // registration of construct registry - builder by default creates its
    // own construct registry
    reg.set('action', exp.action_builder.registry);

    return exp;
});

Singleton registry

Some object types, like entities, are singletons. It's type corresponds to instance. For these types the registration is slightly different:

define(['./_base/Singleton_registry','./builder', './reg'],
        function(Singleton_registry, builder, reg) {

    var  exp = {};
    // module definition ...

    // registries definition
    var registry = new Singleton_registry();
    reg.set('entity', registry);
    builder.set('entity', registry.builder);
    registry.builder.factory = exp.entity;

    return exp;
});

New action registration

define([
        './phases',
        './reg'
    ], function(phases, reg) {
    var exp = {};
    exp.custom_action = function(spec) { /* definition */ };

    exp.registry = function() {
        var a = reg.action; // action construct registry
        a.register('custom', exp.custom_action);
    };

    // register in registration phase
    phases.on('registration', exp.registry);
    return exp;
});

Build of new action

define([
        './builder'
    ], function(builder) {
    var action = builder.build('action', {
        $type = 'custom'
        /* other spec properties */
    }); // no context and no overrides

    // simplified:
    action = builder.build('action', 'custom');
});

Raw usage of Singleton registry without using global registries

It's only example. One should use global registries for facets and entities.

Definition

// './facet_registry.js'
define(['./_base/Singleton_registry'], function(Singleton_registry) {

    return new Singleton_registry();
});

Usage

define(['./facet_registry', './ipa'], function(registry, IPA) {

    var my_facet = function(spec) {

        spec = spec || {};

        var that = IPA.facet(spec);
        return that;
    };

    // optional, but for facets preferable
    var default_spec = { /* some properties */ };

    // register factory as construct specification
    registry.register('foo_facet', my_facet, default_spec);


    // we may define other instance with the same factory
    var other_spec = { /* other properties */ };

    // register with spec object
    registry.register({
        type: 'other_facet',
        factory: my_facet,
        spec: other_spec
    });

    // obtaining instance
    var foo_facet = registry.get('foo_facet');
    var other_facet = registry.get('other_facet');
});