Component Configuration Options

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:
  1. the original defaults record,
  2. the subcomponent record,
  3. direct user options (supplied to a component creator function),
  4. 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, TypedArrays, 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

Description Options that will be passed directly to the renderer creation function, fluid.renderer.createRendererSubcomponent
Example Definition
fluid.defaults("fluid.tableOfContents.levels", {
    rendererFnOptions: {
        noexpand: true
    },
    ...
});
Example Override
var recEditor = cspace.recordEditor(container, {
    rendererFnOptions: {
        rendererTargetSelector: "dialog"
    },
    ...
});
See also Renderer Components
fluid.renderer.createRendererSubcomponent

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