Section | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Field | Description | Type | In/Out |
---|---|---|---|
| Perhaps the most important parameter, contains the "data model" to which value bindings expressed within the tree will be expressed. | free | Mostly In, but the supplied model may be written to later as a result of servicing user actions, especially if the parameter |
| a ChangeApplier object associated with the |
| In |
| If set, any user modification of fields with |
| In |
| If set, will cause the rendered ids to be uniquified against the supplied document, rather than the current one |
| In |
| If set, mismatches between template and component tree will be highlighted in an unreasonable garish pink colour |
| In |
| This map operates in conjunction with the | free | In/Out |
| Configures the lookup from (I18N) messages referenced in the component tree, to some source of a message bundle |
| In |
| Will construct a |
| In |
| Will XMLEncode the rendered markup before insertion into the document. Can be useful for debugging |
| In |
| This is properly a directive to the parser, rather than the renderer, but the options structure is shared. This contains a list of pairs of | Array of | In |
reRender
Code Block | ||||
---|---|---|---|---|
| ||||
var templates = fluid.reRender(templates, node, tree, options); |
Return: the original parsed template.
fluid.reRender()
is identical to fluid.selfRender()
, except that it uses the supplied templates
(the first parameter) as the template instead of the node
parameter. This is useful for re-rendering a template that has been previously rendered.
The options for fluid.reRender()
are identical to those of fluid.selfRender()
.
Sneak Peek: render
New in v1.3: The new fluid.render
function will eventually be the primary means of using the renderer, and will automatically be included in components created using the Sneak Peek fluid.initRendererComponent()
component initialization function. It is available in Infusion version 1.3 as a sneak peek, to allow users to play with it and provide us with feedback.
Code Block | ||||
---|---|---|---|---|
| ||||
var something = fluid.render(source, target, tree, options); |
Return: the original parsed template.
A simple driver for single node self-templating. Treats the markup for a node as a template, parses it into a template structure, renders it using the supplied component tree and options, then replaces the markup in the node with the rendered markup, and finally performs any required data binding. The parsed template is returned for use with a further call to fluid.reRender()
.
Parameters
source
Either a structure {node: node, armouring: armourstyle
} or a string holding a literal template
target
The node to receive the rendered markup
tree
As for fluid.selfRender
: A Javascript Object representing a component tree. See Renderer Component Trees for more information.
options
As for fluid.selfRender
: A JavaScript object used to configure the details of the rendering process.
Renderer Utility Functions
explode
"Explodes" a section of data model to a flat section of component tree bound against the data. This is suitable only in very straight-forward cases of data binding, where each field in a model can be associated with a piece of markup with a corresponding rsf:id
representing a UIBound
component.
Code Block | ||||
---|---|---|---|---|
| ||||
var tree = fluid.explode(hash, basepath) |
Parameter | Type | Description |
---|---|---|
|
| A section of data model representing a flat hash of keys to values |
|
| An optional prefix to be placed on the EL path supplied to the generated |
For example, the following hash:
Code Block | ||||
---|---|---|---|---|
| ||||
var hash = {sku: "thing1", description: "explodes"} |
could be exploded to
Code Block | ||||
---|---|---|---|---|
| ||||
[{ID: "sku", value: "thing1", valuebinding: "1.sku"}, {ID: "description", value: "explodes", valuebinding: "1.description"} ] |
if supplied with fluid.explode(hash, "1")
.
explodeSelectionToInputs
A common markup representation is of a UISelect
component as a series of named radio-buttons or checkboxes, in successive rows of a table (in comparison to its natural HTML representation as a <select> tag). This framework function automates the work of generating the additional component tree material to back this representation:
Code Block | ||||
---|---|---|---|---|
| ||||
var tree = fluid.explodeSelectionToInputs(optionlist, opts) |
Parameter | Type | Description |
---|---|---|
|
| The raw list of options which are available for choice - in general, the value held at |
|
| An options structure to guide the explosion process - described below |
Return |
| A section of component tree which should be added to the same container as the parent |
The opts
structure has the following keys, all of which must be supplied:
Member | Type | Description |
---|---|---|
|
| The |
|
| The |
|
| The |
|
| The |
Following rendering, the returned subtree needs to be added to the same container as the parent UISelect
control by the user - for example, here is a compact call showing compound copying, explosion and addition, where selection_tree
directly holds the UISelect
control:
Code Block | ||||
---|---|---|---|---|
| ||||
var tree = {children: [fluid.copy(selection_tree)].concat( fluid.explodeSelectionToInputs(selection_tree.optionlist, explode_options("radio")))}; |
The explode_options
function sourcing the options could have been implemented as:
Code Block | ||||
---|---|---|---|---|
| ||||
var explode_options = function(type) { return { selectID: "select", rowID: type + "-row:", inputID: type, labelID: "label" }; }; |
Other Important Renderer Functions
fetchResources
New in v1.3: In Infusion v1.3, the API of fluid.fetchResources
has changed. Please see our new documentation for more information: fluid.fetchResources.
For v1.2 and earlier:
Code Block | ||||
---|---|---|---|---|
| ||||
fluid.fetchResources(resourceSpecs, callback) |
fluid.fetchResources
automates the likely tedious work of performing multiple back-to-back AJAX requests for resource (be they markup, JSON or otherwise) and collecting the responses. It operates on a basic resourcesSpecs
structure which is a hash of objects with a particular layout. The keys in resourceSpecs
represent a unique key to represent each resource specification. On conclusion of all of the fetches, the function callback
will be called with the now filled-in resourceSpecs
structure as argument. The fields in a resourcesSpec
entry are as follows:
Field | Direction | Purpose |
---|---|---|
href | In | A full resolvable URL holding a template or template fragment. This will be fetched via AJAX and used to populate the |
nodeId | In | The id of a node within the current document holding a template, for which |
baseURL | Out | Computed from href, in order to rebase local URLs in the template. |
resourceText | Out | The full text of the template fragment, as a string |
fetchError | Out | Filled in if the AJAX request to fetch the resource failed. It will be populated with a structure |
queued | Out | A reserved flag by the system to track the progress of AJAX calls |
The filled-in resourceSpecs
structure is suitable for passing directly as the argument to the low-level function fluid.parseTemplates
.
parseJavaProperties
Code Block | ||||
---|---|---|---|---|
| ||||
var messageSource = fluid.parseJavaProperties(text) |
The Java Properties File Format is a well-specified and common but rather baroque format for storing messages used to internationalise an application. A good tool chain exists for this structure although its main deficiency is that it is not directly Unicode-ready. An application without a legacy background might want to consider encoding the same information directly in a JSON structure. This call converts a textual representation of a .properties
file in this format into the equivalent JSON structure, with a key for each property key, and a value consisting of the properly unescaped message format. The resultant structure is a suitable argument for the fluid.messageLocator
function to create an active message locator.
Parameter | Type | Description |
---|---|---|
|
| String form of the contents of a Java-formatted properties file |
Return |
| JSON form of parsed file |
fluid.parseTemplates
The driver for parsing a multiple template set:
Code Block | ||||
---|---|---|---|---|
| ||||
var templates = fluid.parseTemplates(resourceSpec, templateList, opts) |
Parses a set of textual representations of templates into a complex binary form, suitable for rapid rendering against a component tree. This is part of the low-level functionality which is packaged by high-level calls such as fluid.selfRender
.
Parameter | Type | Description |
---|---|---|
|
| A hash of |
|
| A list of the keys within |
|
| Options to guide the parsing process - see options |
Return |
| A complex structure holding the parsed templates. In general this should not be accessed by users, but passed around to rendering functions as an immutable object. |
renderTemplates
The driver for rendering a template set against a component tree:
Code Block | ||||
---|---|---|---|---|
| ||||
var markup = fluid.renderTemplates(templates, tree, options, fossilsIn); |
Parameter | Type | Description |
---|---|---|
|
| A parsed template structure as returned from |
|
| |
|
| Options to guide the rendering process - see options |
|
| A hash of component "submitting name" to a |
Return |
| A string holding the markup rendered by the renderer for this pass |