The Fluid/RSF Renderer

Inputs to the renderer

The renderer accepts two primary inputs

1. a block (or several blocks) of markup representing a template, and
2. a "component tree" representing the instructions to the renderer on how to transform the markup and bind it to its model.

Optionally, the renderer can accept a 3rd argument being a list of "cutpoints" or named selectors, which impute an id structure onto the template.

Current packaging of the renderer

The renderer is part of the main Fluid distribution held in SVN at renderer

The renderer depends on the core Fluid framework file Fluid.js.

Invoking the renderer

The simplest invocation of the renderer is via "self-rendering" - that is, using an already existing DOM node in the current document as a template for rendering against itself. This uses the fluid.selfRender driver. As a very simple example, the following markup

<tr id="table-header">
  <th>Count</th><th>Name</th><th rsf:id="header:">1</th><th>Median ave</th>
</tr>

could be self-rendered with the following call

fluid.selfRender($("#table-header"),  {"header:": [1, 2, 3, 4, 5]} );

The first argument to fluid.selfRender may be either a raw DOM node, or else a JQuery object representing one (although there is no hard dependency between fluidRenderer.js and the JQuery framework). The second argument is a Javascript Object representing a component tree, for which the accepted syntax is documented here.

Component trees

The component trees accepted by the client-side renderer are direct equivalents of those handled by the RSF server-side framework - the full set of server-side components is documented on the Primitive Components page. The majority of these are now implemented on the clientside. Whilst there are no plans current to port the RSF Decorator infrastructure directly to the client, the Fluid renderer does have its own rich set of #Decorators which are tailored for work on the client side. The currently implemented set consists of UIBound (covering the subset of its descendents of UIBoundBoolean, UIInput, UIOutput and UIBoundList), UISelect (with UISelectChoice), UILink, UIVerbatim, UIBranchContainer, UIJointContainer and UIInitBlock.

Component Tree: ID syntax and structure

To represent a repeating element use a ":" at the end of the id name. (e.g. "repeatingID:")

Branches of a component tree are represented by these repeating elements, while leafs are none repeating elements. The DOM agnostic nature of the Renderer allows you to only have to specify those leaf nodes which are are to be rendered differently than the default in the template.

sample markup template

  <table>
    <tr id="table-row">
      <td class="table-data">
        <a class="table-data-link"></a>
      </td>
    </tr>
  </table>

sample hydrated component tree

var hydratedComponentTree = {
    children: [{
        ID: "data:",
        value: "No Link"
    },
    {
        ID: "data:",
        children: [{
            ID: "link",
            target: "#",
            linktext: "Link"
        }]
    }]
};

var selectorMap = [{selector: ".table-data", id: "data:"},
    {selector: ".table-data-link", id: "link"}];
    
fluid.selfRender($("#table-row"), hydratedComponentTree, {cutpoints: selectorMap});

Duck typing and duck compression

Duck inference for components

Javascript is supplied with a native "object-oriented" system based on prototype and this, but this is unsatisfactory and deprecated for Fluid development. RSF components represent a data-driven and finite hierarchy, and thus are suited to "structural inference" aka "duck typing", whereby the members detected by name in a raw Object allow the framework to infer component types directly. For example, the following structure

{ID: "entry-field",
 value: "this-value",
 }

represents what would be a UIBound instance in RSF Server (strictly, a UIBoundString), by virtue of having an entry named value of type string.

Duck compression

In Javascript's completely flexible type system, we can represent component trees in simple cases in forms even closer to pure JSON than the form above. In particular, for the UIBound/UIBranchContainer family, where no input is required, we can accept arbitrary hashes (Objects) as compresssed representations of component trees, where the hash key represents the "ID" field in the above, and the hash value represents the "value". For example, an object representing three UIBound components (one of which is identical with the one above) could be as follows:

{ "entry-field": "this-value",
  "field-list:": ["value1", "value"]
}

For more complex components (or those with name collisions between IDs and the duck inference fields), the "full" form of the previous section still needs to be used - however the very useful auto-expander RSF.explode may be used to convert raw JSON data structures into fully expanded and properly bound component trees, described in its own section below.

Supported component set

This table shows the supported component "types", together with the duck fields which are used to detect them, along with any other fields which are recognised and "type" information for these fields. The "duck fields" are shown in the first row of information for each type, and highlighted in background.

Note that these components do form a (conceptual) "hierarchy", in an arrangement which agrees with that in the Primitive Components page.

Decorators

Every component, regardless of type, may be decorated with any number of decorators, entered into a field named decorators. Like component trees, these may be written out in a "fully hydrated" form with separate type fields, or in many cases can be usefully condensed onto a few or a single object.

For more information, see Renderer Decorators

Data binding

As well as performing "output only" rendering of data, the fluid renderer is also capable of managing a (bidirectional) association between the rendered markup and a data model. The data model is a Javascript object (root) which is (optionally) supplied at render-time, is processed alongside the component tree, and "bound" into the rendered markup.

As with "RSF Server", the data model association is bidirectional. Firstly, at render-time, any bound (UIBound) component which has a valuebinding set, but no value initialised, will have the value queried from the model as part of a "fixup". Secondly, as the markup is rendered, the list of fossils (an index of the submittingname field of each bound component, its old value (that is, the value at time of rendering), and the EL path into the model) is rendered as a fossil bolus into the root node of the rendered markup, alongside the physical data model itself.

The fossil bolus

The bolus is currently marked into the DOM by a call to jquery.Data for the root node under a name of fluid-binding-root. The utility function for users who wish to perform this manually (either for advanced purposes, or to rebind the model or fossils) looks as follows:

  fluid.bindFossils = function(node, data, fossils) {
    $.data(node, "fluid-binding-root", {data: data, fossils: fossils});
    },

Using data binding

The fossil bolus makes various often tedious model update procedures extremely simple. Firstly, any updated value arising from a DOM node, can be transparently served by a call to fluid.applyChange - for example, when using the Inline Edit control, an update event handler can simply be written as follows:

    function commitChange(node) {
      var newValue = $(node).val();
      fluid.applyChange(node, newValue);
      }

By using the autoBind option to rendering, even writing this handler is unnecessary - any changes made in the UI will be automatically reflected in the tree.

Secondly, the bolus can be very easily used to implement "reset/changed value" functionality, where a control can be easily returned to its original condition by backing out the effects of user changes, on a local or global bases by inspecting the fossil record.

fluid.explode for convenient data binding

Writing the EL expressions necessary to specify the data binding required for a number of controls can be verbose and boring, and so the framework includes a utility fluid.explode to automate this for some simple cases. Where we can operate the convention that the id assigned to a set of components should be equal to the key used for matching fields in an Object in the model, we can use fluid.explode to perform simultaneous duck decompression and data binding. For example, given the structure

  var dataTable = [
    {sku: "thing1", description: "explodes"},
    {sku: "thing2", description: "disinteggrates"}
   ]

we could apply fluid.explode in a loop like this:

    var tree = [];
    for (var i = 0; i < dataTable.length; ++ i) {
      var row = fluid.explode(dataTable[i], i);
      tree[tree.length] = row;
      }
    tree = {"table-row:": tree};

(note that the above loop could be condensed considerably by use of the utility fluid.transform)
which would produce the following nearly fully decompressed tree, suitable for rendering rows producing both input and output:

  {"table-row:": [
    [{ID: "sku",
     value: "thing1",
     valuebinding: "1.sku"},
    {ID: "description",
     value: "explodes",
     valuebinding: "1.description"}
     ],
    [{ID: "sku",
     value: "thing2",
     valuebinding: "2.sku"},
    {ID: "description",
     value: "disinteggrates",
     valuebinding: "2.description"}
     ]
    ]
  }

It is imagined that lots more "component-building kit" methods will be available
so that the work of JSON transformation from data model to component form will be
as easy and transparent as possible.

Selector-based rendering

One of the possible entries in the opts argument to fluid.selfRender (and also in the more advanced drivers discussed below}} is a named selector list called cutpoints, which allows the use of pure markup (without any rsf:id) structure) to be used as a template. As a simple example, here is our little table header from before, but with a plain CSS class notating the header cell to be repeated, rather than the rsf:id:

<tr id="table-header">
  <th>Count</th><th>Name</th><th class="column-header">1</th><th>Median ave</th>
</tr>

In order to use this with the same component tree as before, we can make the following call to selfRender:

  var tree = {"header:": [1,2,3,4,5]};

  fluid.selfRender($("#table-header"), tree, 
        { cutpoints: [{selector: "th.column-header", id: "header:"}]
     });

The value selector is a standard CSS selector nominating the node which is to "receive" an id, and the id value in each entry in the list is the id that nodes matching the selector are to receive (should this structure perhaps be a hash rather than a list, once we can support comma-separated selectors?)

The selector subset currently supported is basic, but actually accounts for the vast bulk of selectors typically written in practice (as reported by JQuery developers) - we support selectors by id (#), class (.), tag name as well as child (>) and descendent specifiers.

Advanced renderer driving

See Advanced Renderer Driving for information.

Options structure for configuring rendering

Like a Fluid component, the renderer takes an Options structure which is used to configure the details of its rendering process. Unlike options for most Fluid components, this structure sometimes has a bi-directional aspect - it can be used for returning information about the rendering process back to the client, as well as for receiving it. Here is a list of the supported fields and types within the renderer options: