Infusion components are configured using options that are defined by the component developer and customized by the integrator.
While component developers are free to define whatever options are appropriate for their component, the Infusion Framework supports a number of predefined options.
The particular set of options interpreted by the framework is determined by the Grades that the component is derived from. Developers and integrators
can define further grades which respond to yet further options, which they should document if they expect the options to be generally useful.
This page briefly describes these predefined options and provides links to more information about the related framework functionality.
Options Supported By All Components Grades
The following options are supported by all component grades, that is, those derived from fluid.component
:
gradeNames
Description |
A String or Array of String grade names. |
Example Definition |
fluid.defaults("component.name", {
gradeNames: "fluid.modelComponent",
// ...
});
|
See also |
Component Grades |
invokers
Description |
A record defining methods on the component whose arguments are resolved from the environment as well as the direct argument list at invocation time. |
Example Definition |
fluid.defaults("component.name", {
invokers: {
inv1: {
},
inv2: {
}
}
});
|
See also |
Invokers |
members
Description |
A record defining properties to be added to the component object. These can be anything, including methods, strings, objects, etc. Definitions are evaluated as IoC expressions. |
Notes |
Defining a method as a Function in members will differ from invokers in that the arguments of members are not resolved at invocation time. The use of such function members is not recommended except where very high invocation performance is required.
The right-hand-side may contain an expander definition, which may perhaps itself resolve onto an invoker. |
Example Definition |
fluid.defaults("component.name", {
members: {
member1: "{that}.options.optionsValue",
member2: "{theOther}.dom.otherSelector",
},
});
|
events
Description |
A record containing key/value pairs that define the events the component will fire: the keys are the event names, the values define the type of the event (see Infusion Event System for information on the different event types). |
Notes |
The Framework will create event firers for the listed events. The builtin events onCreate , onDestroy and afterDestroy will be fired automatically by the framework.
It is the responsibility of the component to fire user-defined events at the appropriate times.
|
Example Definition |
fluid.defaults("component.name", {
events: {
onSave: "preventable",
onReady: null
}
});
|
See also |
Infusion Event System |
listeners
Description |
A record defining listener functions for the events supported by a component. |
Notes |
Both component developers and integrators can define listeners for events.
Invokers and the fire method of other events can be used as listeners here, as well as any function handle resulting from an Expanders.
Note that as well as being a simple string holding the name of an event on this component, a listener key may also be a full IoC Reference
to any other event held in the component tree (for example "{parentComponent}.events.parentEvent" . As well as being a simple function name, the value associated with the key may be a Listener Record
or else follow the syntax of an invoker indicating that the registered listener receives a different signature from the one that the event has fired (see Event injection and boiling).
|
Example Definition |
examples.myListener = function (number, condition) {
console.log("Event listener received number " + number + " and condition " + condition);
};
<p>fluid.defaults("examples.eventedComponent", {
gradeNames: ["fluid.component"],
events: {
myEvent: null
},
listeners: {
"myEvent.myNamespace": "examples.myListener"
}
});
|
Example Override |
var myComp = examples.eventedComponent({
listeners: {
"myEvent.myNamespace": "examples.myOtherListener",
}
});
|
See also |
Infusion Event System |
components
Description |
A record containing named definitions of the component's subcomponents. |
Notes |
This (the subcomponent record) is one of the core sources from which the options configuring a component in a particular context. The total set of options sources are:
- the original defaults record,
- the subcomponent record,
- direct user options (supplied to a component creator function),
- distributed options.
|
Example Definition |
fluid.defaults("component.name", {
components: {
subcomponent1: {
type: "component.subcomp1",
options: {...}
}
// ...
}
// ...
});
|
See also |
Documentation: Subcomponents |
|
Tutorial: Subcomponents |
distributeOptions
Description |
A record directing the framework to distribute options from this component to one or more other components in the component tree. Either a single record, an Array or Object holding these records is supported.
In the Object form, the keys of the object will be taken to represent the namespace
|
Example Definition |
fluid.defaults("component.name", {
gradeNames: ["fluid.component"],
distributeOptions: {
namespace: "myDistribution",
record: "another.grade.name",
target: "{that target.grade.name}.options.gradeNames"
}
});
|
See also |
IoCSS for options distributions |
mergePolicy
Description |
A record providing instructions for how particular options should be merged when integrator options are merged with default values. |
Notes |
It is uncommon to need this option. The most common use case is to protect "exotic values" derived from some external library or framework from being corrupted by the options merging/expansion process by use of the "nomerge" policy.
For example, some noxious circularly-liked structure such as a node.js HTTP request object should be protected in such a way. The 2.0 framework will automatically protect an object which fails the fluid.isPlainObject test, which will exclude
any object with a nondefault constructor or native type such as DOM elements, TypedArray s, Infusion components themselves, etc.
|
Example Definition |
fluid.defaults("component.name", {
mergePolicy: {
option1: "noexpand",
option2: "nomerge"
}
});
|
See also |
Options Merging |
dynamicComponents
Description |
An object containing named definitions of the component's dynamic subcomponents. Rather than exactly one subcomponent being associated with its parent from these records, there may be one subcomponent per element of an array, or one per firing of an event. |
Notes |
Some special context names will be available within the subcomponent's definition block, for example {source} and {sourcePath} or {arguments} , derived from the material responsible for constructing the component.
This framework facility will be replaced by a more declarative equivalent in time - ask on the fluid-work mailing list
or #fluid-work IRC channel if you seem to find yourself needing to use it. |
Example Definition |
fluid.defaults("component.name", {
dynamicComponents: {
dynamic1: {
type: "component.subcomp1",
source: "{context}.someArray",
options: {
}
}
}
});
|
See also |
Documentation: Dynamic components |
|
Tutorial: Subcomponents |
Model Components
Components defined with a grade of fluid.modelComponent
support all of the common options described above, as well as those defined below. Component developers are free to define their own additional options.
See also: Component Grades
model
Description |
An record containing the data model to be used by the component. |
Example Definition |
fluid.defaults("fluid.pager", {
model: {
pageIndex: undefined,
pageSize: 10,
totalRange: undefined
}
});
|
Example Override |
var myPager = fluid.pager(container, {
model: {
pageIndex: 1
}
});
|
See also |
Model Objects
ChangeApplier API
|
modelListeners
Description |
A record defining a set of functions wishing to be notified of changes to the model
|
Example Definition |
fluid.defaults("fluid.tests.allChangeRecorder", {
gradeNames: "fluid.tests.changeRecorder",
modelListeners: {
"": "{that}.record({change}.path, {change}.value, {change}.oldValue)"
}
});
|
See also |
Model Listeners |
modelRelay
Description |
A set of rules or constraints linking values held in this model to those elsewhere in the component tree (or to other values within this model) |
Example Definition |
fluid.defaults("examples.volumeModelRelay", {
gradeNames: ["fluid.modelComponent"],
model: {
volumeAsPercent: 95,
},
modelRelay: {
source: "volumeAsPercent",
target: "volumeAsFraction",
singleTransform: {
type: "fluid.transforms.linearScale",
factor: 0.01
}
}
});
|
See also |
Model Relay |
changeApplierOptions
Description |
Options that will be passed on to the ChangeApplier constructed for this component. There are currently no such options supported. This section is left as a placeholder, since such options,
like lemon-soaked paper napkins, will one day be supported here again.
|
See also |
ChangeApplier API |
View Components
Components defined with a grade of fluid.viewComponent
are also model components, so they support
Component developers are free to define their own additional options.
selectors
Description |
A record containing named CSS-based selectors identifying where in the DOM relative to the component's container different elements can be found.
|
Notes |
The Framework will create a DOM Binder that should be used to access the elements identified by selectors. The DOM Binder attaches a function to the component object called locate() which retrieves the element given the selector name. |
Example Definition |
fluid.defaults("fluid.progress", {
selectors: {
displayElement: ".flc-progress",
progressBar: ".flc-progress-bar",
indicator: ".flc-progress-indicator",
label: ".flc-progress-label",
ariaElement: ".flc-progress-bar"
}
});
|
Example Override |
var myEdit = fluid.progress(container, {
selectors: {
indicator: "div.progress-indicator",
label: "span.progress-label"
}
});
|
See also |
DOM Binder |
styles
Description |
A record containing named CSS classes that the component will apply to its markup in order to achieve state-dependent styling effects. |
Notes |
The contents of this block are not interpreted by the framework at all. The existence of this block amounts to a helpful convention that implementors of view components are recommended to use, to organise
and advertise the CSS class names that they will apply on behalf of their users |
Example Definition |
fluid.defaults("demo.initGridReorderer", {
gradeNames: ["fluid.reorderGrid"],
styles: {
dragging: "demo-gridReorderer-dragging",
avatar: "demo-gridReorderer-avatar",
selected: "demo-gridReorderer-selected",
dropMarker: "demo-gridReorderer-dropMarker"
},
disableWrap: true
});
|
In addition to the options above, a View Component also accepts an additional argument named container
which may be supplied either as the first argument to its Creator Function
or else at top level in its Subcomponent Record. It is not currently supported to supply this value as a standard option in the options record.
Renderer Components
Components defined with a grade of rendererComponent
are also view components (and hence model components), so they support
Component developers are free to define their own additional options.
Note: The Infusion Renderer system will be rewritten completely before the Infusion 3.0 release - the use of the current renderer and component hierarchy is not recommended.
selectorsToIgnore
Description |
An array of selector names identifying elements that will be ignored by the Renderer. These elements will be displayed exactly as provided in the template, with no processing |
Example Definition |
fluid.defaults("cspace.header", {
selectors: {
menuItem: ".csc-header-menu-item",
label: ".csc-header-link",
searchBox: ".csc-header-searchBox",
logout: ".csc-header-logout",
user: ".csc-header-user",
userName: ".csc-header-userName"
},
selectorsToIgnore: ["searchBox", "logout"]
});
|
repeatingSelectors
Description |
An array of selector names identifying elements that will be repeated by the Renderer based on the data being rendered. For example, the selector for a table row that will be replicated many times should appear in the list of repeating selectors. |
Example Definition |
fluid.defaults("cspace.header", {
selectors: {
menuItem: ".csc-header-menu-item",
label: ".csc-header-link",
searchBox: ".csc-header-searchBox",
logout: ".csc-header-logout",
user: ".csc-header-user",
userName: ".csc-header-userName"
},
repeatingSelectors: ["menuItem"]
});
|
produceTree
Description |
A function that will return a Renderer Component Tree for the component. |
Notes |
The referenced function must accept the component object as its only parameter and return a Renderer component tree.
NOTE that if both produceTree and protoTree are specified, only the produceTree function will be used; the protoTree will be ignored. |
Example Definition |
cspace.confirmationDialog.produceTree = function (that) {
var tree = {
};
return tree;
};
fluid.defaults("cspace.confirmationDialog", {
produceTree: cspace.confirmationDialog.produceTree
});
|
See also |
protoTree
Renderer Component Tree |
protoTree
Description |
A tree of Renderer protocomponents. |
Notes |
NOTE that if both produceTree and protoTree are specified, only the produceTree function will be used; the protoTree will be ignored. |
Example Definition |
fluid.defaults("cspace.searchTips", {
protoTree: {
searchTips: {decorators: {"addClass": "{styles}.searchTips"}},
title: {
decorators: {"addClass": "{styles}.title"},
messagekey: "searchTips-title"
},
expander: {
repeatID: "instructions",
type: "fluid.renderer.repeat",
pathAs: "row",
controlledBy: "messagekeys",
tree: {
messagekey: "${{row}}"
}
}
}
});
|
Example Override |
var searchTips = cspace.searchTips(container, {
protoTree: {
searchTips: {decorators: {"addClass": "{styles}.searchTips"}},
title: {
decorators: {"addClass": "{styles}.title"},
messagekey: "searchTips-title"
},
expander: {
repeatID: "instructions",
type: "fluid.renderer.repeat",
pathAs: "row",
controlledBy: "messagekeys",
tree: {
messagekey: "${{row}}"
}
}
},
});
|
See also |
produceTree
Renderer Component Tree
ProtoComponent Types |
resources
Description |
An object that lists resources (such as HTML files, CSS files, data files) required by the component. |
Notes |
The specified resources will be loaded automatically and the file content will be stored within the resources object itself. |
Example Definition |
fluid.defaults("component.name", {
resources: {
headerTemplate: {
href: "../templates/Header.html"
},
footerTemplate: {
href: "../templates/Footer.html"
}
}
});
|
Example Override |
var myComp = component.name(container, {
resources: {
footerTemplate: {
href: "../templates/FrontPageFooter.html"
}
}
});
|
See also |
fluid.fetchResources |
strings
Description |
An object containing named strings or string templates. The strings will be used by the Renderer. |
Notes |
The Framework will create a Message Resolver and add it to the component object if the strings option is present. |
Example Definition |
fluid.defaults("cspace.searchToRelateDialog", {
gradeNames: ["fluid.rendererComponent"],
strings: {
createNewButton: "Create",
title: "Add Related %recordType Record",
closeAlt: "close button",
relationshipType: "Select relationship type:",
createNew: "Create new record:",
addButton: "Add to current record"
}
});
|
Example Override |
var myDialog = cspace.searchToRelateDialog(container, {
strings: {
relationshipType: "Select a relationship type from the list below:",
createNew: "Create a new record:",
addButton: "Add this record to the current record"
}
});
|
See also |
fluid.messageResolver |
rendererFnOptions
rendererOptions
Description |
Options that will be included in the rendererFnOptions as rendererOptions |
Example Definition |
fluid.defaults("cspace.searchBox", {
rendererOptions: {
autoBind: false
}
});
|
Example Override |
var search = cspace.searchBox(container, {
rendererOptions: {
autoBind: true
}
// ...
});
|
See also |
Renderer Components
rendererFnOptions |
renderOnInit
Description |
A boolean flag indicating whether or not the component should render itself automatically once initialization has completed. By default, renderer components do not render themselves automatically. |
Example Definition |
fluid.defaults("cspace.login", {
gradeNames: ["fluid.rendererComponent"],
renderOnInit: true
// ...
});
|
Example Override |
var login = cspace.login(container, {
renderOnInit: false
});
|
See also |
fluid.initRendererComponent |