RendererComponents.md

title	noteRendererChangesPost15	category
Renderer Components	true	Infusion

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.