Renderer Components

Note: The renderer will undergo significant changes post Infusion 1.5

If you are creating a component that requires the use of the Renderer, you should use the fluid.rendererComponent grade as a parent grade in your component's defaults block:

fluid.defaults("my.component", {
    gradeNames: ["fluid.rendererComponent"]
    // put your options here
});

var that = my.component();

This function automates the work of constructing a component creator function, applying the Renderer, fetching templates, configuring cutpoints based on the DOM binder, as well as localisation via the string bundle.

This function will:

create that.model, using options.model if available (creating an empty object if not)
fetch any resources (such as HTML templates, etc.) specified in options.resources
create a renderer function and attach it to your that object as that.render(tree);

Options for Renderer Components

While developers are free to define whatever options they like for their component, a component descended from fluid.rendererComponent will also understand certain options specific to the Renderer:

Name	Description	Values	Default
`model`	The data model to which value bindings expressed within the tree will be expressed	Object	none
`resources`	A list of resources (such as HTML files, CSS files, data files) that are required by the component.	Object as required by fluid.fetchResources	none
`resolverGetConfig`	Configuration functions to be applied to any data retrieved from the model	Array of Functions	The raw value will be retrieved unchanged.
`resolverSetConfig`	Configuration functions to be applied to any data being saved in the model	Array of Functions	The raw value will be saved unchanged.
`rendererOptions`	Options that will be included in the `rendererFnOptions` as `rendererOptions`	Object
`rendererFnOptions`	Options that will be passed directly to the renderer creation function	Object	See the documentation for fluid.renderer.createRendererSubcomponent
`selectors`	A set of named selectors that will be converted to cutpoints for use by the renderer	Object	none
`repeatingSelectors`	A list of any of the named selectors that reference elements that will be repeated when renderer (e.g. rows in a table)	Array of Strings	none
`selectorsToIgnore`	A list of any of the named selectors that should not be included in the renderer cutpoints	Array of Strings	none
`protoTree`	A data structure that represents the binding between the contents and data. Also see Renderer Component Trees for more detail.	Object	none
`produceTree`	A user-defined function that returns protoTree	Function	none
`renderOnInit`	A flag indicating whether or not the component should render itself automatically after initialization.	Boolean	false

Events for Renderer-bearing Components

Note: The 3 events are fired in the order of prepareModelForRender, onRenderTree, afterRender. They are only intended for use by experts.

prepareModelForRender

Description	This event fires before the generation of protoTree. Whatever adjustment on the model, which is the protoTree is generated based on, is ideal to be performed at this event.
Parameters	`model` The internal Model Component that is used by this renderer component. `applier` The internal Change Applier Component that is used by this renderer component. `that` The reference to the current renderer component.
Returns	None
Note	The first event to be fired before events `onRenderTree` and `afterRender`.

onRenderTree

Description	This event fires right before protoTree is rendered. This event is ideal for the final manipulation of the fully expanded protoTree.
Parameters	`that` The reference to the current renderer component. `tree` Expanded renderer tree.
Returns	None
Note	The event fired after `prepareModelForRender` and before `afterRender`.

afterRender

Description	This event fires after protoTree is rendered.
Parameters	`that` The reference to the current renderer component.
Returns	None
Note	The event fired after `onRenderTree` and `afterRender`.

Functions on "that"

render(tree)

that.render(tree);

Expands the provided tree, generates cutpoints, and renders the tree.

produceTree()

that.produceTree();

This function is only present if a protoTree has been provided in the options. This function can be overridden by providing a produceTree in the options.

refreshView()

that.refreshView();

This function calls that.render(that.produceTree()); This function is only present if a protoTree has been provided in the options.

Example: Rendering a select box

fluid.defaults("fluid.examples.renderer", {
    gradeNames: ["fluid.rendererComponent"],
    selectors: {
        textFont: ".flc-examples-text-font",
        notInProtoTree: ".flc-examples-not-in-protoTree"
    },
    // "selectorsToIgnore" is an array of all the selectors
    // that are defined in "selectors" but not used in
    // "protoTree". It tells renderer not to generate cutpoints
    // for these selectors.
    selectorsToIgnore: ["notInProtoTree"],
    model: {
        textFontNames: ["Serif", "Sans-Serif", "Arial"],
        textFontList: ["serif", "sansSerif", "arial"],
        textFontValue: ""
    },
    rendererOptions: {
        autoBind: true
    },
    renderOnInit: true,
    protoTree: {
        // "textFont" is an ID that is defined in "selectors"
        // option
        textFont: {
            // "textFontNames", "textFontList", "textFontValue"
            // must be defined in "model"
            optionnames: "${textFontNames}",
            optionlist: "${textFontList}",
            selection: "${textFontValue}"
        }
    },
    resources: {
        template: {
            forceCache: true,
            url: "examples-renderer.html"
        }
    }
});


var that = fluid.examples.renderer("#options");

The template "examples-renderer.html" looks like,

<form id="options" action="">
    <label for="text-font" class="fl-label">Font style:</label>
    <select class="flc-examples-text-font" id="text-font">
    </select>
</form>

This example uses a renderer component to generate a drop down list box. The protoTree is the key option that establishes the binding between the selectors and data presented in model.