Renderer-bearing Components

Overview

If you are creating a component that requires the use of the Renderer, use the new fluid.initRendererComponent function in your component creator function:


my.component = function (container, options) {
    var that = fluid.initRendererComponent("my.component", container, options);
    ...
    return that;
}

This new function automates the work of 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-bearing Components

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

Events for Renderer-bearing Components

prepareModelForRender

onRenderTree

afterRender

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

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 simply calls that.render(that.produceTree()); This function is only present if a protoTree has been provided in the options.

Example to render a drop down list box


(function ($, fluid) {
    fluid.examples.rederer = function (container, options) {
        var that = fluid.initRendererComponent("fluid.examples.rederer", container, options);
        that.renderer.refreshView();

        return that;   
    };

    fluid.defaults("fluid.examples.rederer", {
        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,
        },
        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"
            }
        }
    });
})

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 renderer component to generate a drop down list box. fluid.initRendererComponent(). The option "protoTree" is the key option that establishes the binding between the "selectors" and data presented in "model". See Component Tree Expanders for more usage of "protoTree".