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);
};
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 Matrix 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: "$"
}
}
}
// ...
});
|
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: "$"
}
}
},
// ...
});
|
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 |