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-rederer.html"
        }
    }
});


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

The template "examples-rederer.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.