Documentation for a historical release of Infusion: 1.4
Please view the Infusion Documentation site for the latest documentation, or the Infusion 1.3. Documentation for the previous release.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

How to Use Infusion IoC


This functionality is Sneak Peek status. This means that the APIs may change. We welcome your feedback, ideas, and code, but please use caution if you use this new functionality.

This page provides an overview of the typical way to use the IoC system in a component. There are variations on this theme, but the this overview provides a basic, full-function implementation.

IoC Overview

Infusion components make use of the Framework's IoC system through three main mechanisms which work together:

  • Subcomponents demand what they need of a parent component.
  • A parent component declares what subcomponents it uses.
  • The parent component asks the Framework to create the necessary subcomponents.

Demands

A subcomponent can demand information from any of the parent components in given context using the fluid.demands. The demands specification will be registered with the Framework and referenced when the subcomponent is requested by name.

fluid.demands("subComponent1Name", // the "demanding name"
    "myNamespace.myComponentName", // the context
    {                              // the demands specification
        funcName: "mySubComponent1Impl", // Creator function to be used.
        args: { // Creator function arguments.
            model: "{myComponentName}.model",
            url: "{myComponentName}.url"
        }
    }
);

What this example means is:

"When someone asks for subComponent1Name in the context of myNamespace.myComponentName, use the function myComponent1Impl, passing the model and url properties of the component myComponentName in the environment."

fluid.demands("subComponent1Name", // the "demanding name"
    "myNamespace.myComponentName", // the context
    {                              // the demands specification
        container: "{myComponentName}.dom.subComponent1Selector", // subcomponent's container
        options: { // options for the creator function.
            model: "{myComponentName}.model",
            url: "{myComponentName}.url"
        }
    }
);

What this example means is:

"When someone asks for subComponent1Name in the context of myNamespace.myComponentName, use myComponentName's subComponent1Selector selector as the subcomponent's container, options argument to the creator function will contain model and url properties of the component myComponentName."

For detailed information on the format of the demands specification object, please see Demands Specifications.

For more information on the required parameters see the fluid.demands API specification.

Declaring Subcomponents

A parent component declares what subcomponents it requires through the components block of the parent component's default options using fluid.defaults. This list of subcomponents will be examined when the parent component ask the Framework to create subcomponents, as described below in #Creating Subcomponents.

fluid.defaults("myNamespace.myComponentName", {
    ...
    components: {
        mySubComponent1: {
            type: "subComponent1Name"
        },
        mySubComponent2: {
            type: "subComponent2Name"
        },
    },
    ...
});

In this example, the default type for myComponentName 's subcomponent mySubComponent1 is specified as type name subComponent1Name.

For more information on how components can declare subcomponents, see Subcomponent Declaration. For details on the fluid.defaults() function, please see its API page.

Creating Subcomponents

A component creator function must call fluid.initDependents to instantiate any subcomponents declared in the defaults. The call to fluid.initDependents will create each of the subcomponents using the demands specifications registered using fluid.demands.

myNamespace.myComponentName = function (container, options) {
    var that = initView(...);
    ...
    fluid.initDependents(that);
    ...
    return that;
};

Assuming this example is combined with the demands specifications and component defaults shown above, when fluid.initDependents() is called within the creator function of myNamespace.myComponentName, the Framework will create the subcomponent mySubcomponent1 according to the demands specification, calling the mySubComponent1Impl creator function and attaching the returned object to myNamespace.myComponentName 's that object as that.mySubcomponent1.

Every component of grade "autoInit" will call it's fluid.initDependents function during its lifecycle in order to initialize any of its subcomponents.The call to fluid.initDependents will create each of the subcomponents using the demands specifications registered using fluid.demands.

fluid.defaults("myNamespace.myComponentName", {
    gradeNames: ["autoInit", ...],
    ...,
    components: {
        mySubComponent1: {
            type: "subComponent1Name"
        },
        mySubComponent2: {
            type: "subComponent2Name"
        },
    },
    ...
});

fluid.initDependents() is called within the creator function of myNamespace.myComponentName, the Framework will create the subcomponent mySubcomponent1 according to the demands specification, calling the mySubComponent1Impl creator function and attaching the returned object to myNamespace.myComponentName 's that object as that.mySubcomponent1.

For more information on the fluid.initDependents() function, please see its API page. For a more detailed overview of this whole process, see IoC Pipeline.