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.