This documentation is quite incomplete. At the moment, it is simply a holding place for various bits of documentation that don't have a proper home yet.

The Fluid framework includes a number of functions and utilities that component developers can avail themselves of. These are described below.

fluid.js

fluid.accumulate(list, fn, arg)

Scan through a list of objects, "accumulating" a value over them (may be a straightforward "sum" or some other chained computation). The results will be added to the initial value passed in by "arg" and returned.

  • list {Array}: The list of objects to be accumulated over
  • fn {Function}: An "accumulation function" accepting the signature (object, total, index) where object is the list member, total is the "running total" object (which is the return value form the previous function), and index is the index number.
  • arg {Object}: The initial value for the "running total" object

Return: arg

fluid.allocateSimpleId(element)

Allocate an id to the supplied element if it has none already, by a simple scheme resulting in ids "fluid-id-nnnn" where nnnn is an increasing integer.

  • element {Element}: The element to place the simple id.

Return: String (representing the id)

fluid.byId(id, dokkument)

Returns a DOM element quickly, given an id.

  • id {Object}: The id of the DOM node to find
  • dokkument {Document}: the document in which it is to be found (if left empty, use the current document)

Return: Element or null if none exists

See also: fluid.jById

fluid.clear(target)

Clears an object or array of its contents. For objects, each property is deleted.

  • target {Object|Array}: Either an object or an array whose contents you wish to clear

fluid.COMPONENT_OPTIONS

A special "marker object" which is recognized as one of the arguments to fluid.initSubComponents. This object is recognized by reference equality - where it is found, it is replaced in the actual argument position supplied to the specific subcomponent instance, with the particular options block for that instance attached to the overall "that" object.

Constant: {}

See also: fluid.initSubComponents

fluid.container(containerSpec)

Fetches a single container element and returns it as a jQuery.

  • containerSpec {String|jQuery|Element}

Return: jQuery (a single-element jQuery of container)

fluid.copy(tocopy)

Performs a deep copy (clone) of its argument

  • tocopy {Object}: the object to be copied

Return: Object (the copy)

fluid.createDomBinder(container, selectors)

Creates a new DOM Binder instance, used to locate elements in the DOM by name.

  • container {Object}: The root element in which to locate named elements
  • selectors {Object}: A collection of named jQuery selectors

Return: Object

See: Markup Configuration and Selectors

fluid.defaults()

Retrieves and stores a component's default settings centrally.

  • {Boolean}: (optional) if true, manipulate a global option (for the head component) rather than instance options
  • {String}: componentName the name of the component
  • {Object}: (optional) a container of key/value pairs to set

Return: Object (If the object is passed in the argument, this is added to the store and then returned. If not, the current object in the store is returned)

See: Markup Configuration and Selectors, Fluid Component API
See also: fluid.mergeComponentOptions

fluid.dumpEl(element)

Dumps a DOM element into a readily recognizable form for debugging - produces a "semi-selector" summarizing its tag name, class and id, whichever are set.

  • element {jQueryable}: can be an element, selector, function that returns an element, or a jQuery.

Return: String representing the DOM element

fluid.emptySubcomponent(options)

Construct a dummy or "placeholder" subcomponent, that optionally provides empty implementations for a set of methods.

  • options {Anything}: can be anything, will use jQuery.makeArray to turn it into an array

Return: Object (the empty sub-component)

fluid.event.getEventFirer(unicast, preventable)

Constructs an "event firer" object which can be used to register and unregister listeners, to which "events" can be fired. These events consist of an arbitrary function signature.

  • unicast {Boolean}: If true, this is a "unicast" event which may only accept a single listener.
  • preventable {Boolean}: If true, the return value of each handler will be checked for false in which case further listeners will be short circuited, and this will be the return value of fire().

Returns: Object (see below)

{
    addListener: function(listener, namespace, exclusions),
    removeListener: function(listener),
    fire: function()
}

See: Infusion Event System

fluid.expectFilledSelector(result, message)

Expect that an output from the DOM binder has resulted in a non-empty set of results. If none are found this function will fail with a diagnostic message, with the supplied message prepended.

  • result {jQuery}: The return value from the DOM Binder
  • message {String}: message to report if the results are empty

fluid.fail(message)

Causes an error message to be logged to the console and a real runtime error to be thrown.

  • message {String|Error}: The error message to log

fluid.find(list, fn, deflt)

Scan through a list of objects, terminating on and returning the first member which matches a predicate function.

  • list {Array}: The list of objects to be searched
  • fn {Function}: A predicate function, acting on a list member. A predicate which returns any value which is not null or undefined will terminate the search. The function accepts (object, index).
  • deflt {Object}: A value to be returned in the case no predicate function matches a list member. The default will be the natural value of undefined.

Return: Object (the first object in the list that matches the predicate function, or deflt if nothing does)

fluid.findAncestor(element, test)

Finds the nearest ancestor of the element that passes the test.

  • element {Element}: DOM element
  • test {Function}: A function which takes an element as a parameter and returns true or false for some test

fluid.findKeyInObject

Deprecated

See: fluid.keyForValue

fluid.formatMessage(messageString, args)

Expand a message string with respect to a set of arguments, following a basic subset of the Java Message Format rules. http://java.sun.com/j2se/1.4.2/docs/api/java/text/MessageFormat.html

The message string is expected to contain replacement specifications such as {0}, {1}, {2}, etc.

  • messageString {String}: The message key to be expanded
  • args {String|Array of Strings}: An array of arguments to be substituted into the message.

Return: String (the formatted String)

fluid.getId(element)

Returns the id attribute from a jQuery or pure DOM element

  • element {jQuery|Element}: The element to return the id attribute for

Return: String representing the id

fluid.initDomBinder(that)

Creates a new DOM Binder instance for the specified component and mixes it in.

  • that {Object}: the component instance to attach the new DOM Binder to

See: Markup Configuration and Selectors

{anchor: fluid.initSubcomponent

fluid.initSubcomponent(that, className, args)

This function provides a generic way of instantiating and configuring any "sub-components" that may be a part of, or used by, a parent component. For example, this function is used by the Inline Edit component to instantiate the Undo decorator, a sub-component that provides Undo functionality to components that support it.

  • that {Component}: the top-level component for which sub-components are to be instantiated. It contains specifications for these sub-components in its options structure.
  • className {String}: The "class name" or "category" for the sub-components to be instantiated. A class name specifies an overall "function" for a class of sub-components and represents a category which accept the name signature of instantiation arguments.
  • args {Array of Object}: The instantiation arguments to be passed to each constructed sub-component. These will typically be members derived from the top-level "that" or perhaps globally discovered from elsewhere. One of theses arguments may be fluid.COMPONENT_OPTIONS in which case this placeholder argument will be replaced by instance specific options configured into the member of the top-level options structure named for the className.

Return Component (a single component)

See: Subcomponents, fluid.initSubcomponents

fluid.initSubcomponents

Initialize all the "sub-components" which are configured to be attached to the supplied top-level component, which share a particular "class name".

  • that {Component}: the top-level component for which sub-components are to be instantiated. It contains specifications for these sub-components in its options structure.
  • className {String}: The "class name" or "category" for the sub-components to be instantiated. A class name specifies an overall "function" for a class of sub-components and represents a category which accept the name signature of instantiation arguments.
  • args {Array of Object}: The instantiation arguments to be passed to each constructed sub-component. These will typically be members derived from the top-level "that" or perhaps globally discovered from elsewhere. One of theses arguments may be fluid.COMPONENT_OPTIONS in which case this placeholder argument will be replaced by instance specific options configured into the member of the top-level options structure named for the className.

Return: Array of sub-components

See also: fluid.COMPONENT_OPTIONS, fluid.initSubcomponent

fluid.initView(componentName, container, userOptions)

The central initialization method called as the first act of every Fluid component. This function automatically merges user options with defaults, attaches a DOM Binder to the instance, and configures events.

  • componentName {String}: The unique "name" of the component, which will be used to fetch the default options from store. By recommendation, this should be the global name of the component's creator function.
  • container {jQueryable}: A specifier for the single root "container node" in the DOM which will house all the markup for this component. Can be an element, selector, function that returns an element, or a jQuery.
  • userOptions {Object}: The configuration options for this component.

Return: Component

fluid.instantiateFirers(that, options)

Sets up a component's declared events.

Events are specified in the options object by name. There are three different types of events tat can be specified.

  1. An ordinary multicast event, specified by "null"
  2. A unicast event, which allows only one listener to be registered
  3. A preventable event.


  • that {Object}: The component
  • options {Object}: The component's options structure, containing the declared event names and types.

fluid.invokeGlobalFunction(functionPath, args, environment)

Allows you to call a function from an EL expression "functionPath", with the arguments "args", scoped to an "environment".

Return: The function represented by "functionPath" with the "args" applied

See: fluid.initSubcomponents
See also: fluid.model.getBeanValue

fluid.isPrimitive(value)

Determines if the passed value is of a primitive type

  • value {Object}: The value to be tested

Return: Boolean (true if value is a primitive)

fluid.jById(id, dokkument)

Returns a jQuery object given the id of a DOM node. In the case this not found, will return an empty list.

  • id {String}: id of the DOM node to find
  • dokkument {}: the document in which it is to be found (if left empty, use the current document)

Return: Object (a jQuery Object for the id) or an empty list of the id doesn't exist

See also: fluid.byId

fluid.keyForValue(obj, value)

Searches through the supplied object for the first value which matches the one supplied.

  • obj {Object}: The Object to be searched through
  • value {Object}: The value to be found. This will be compared against the object's member using === equality

Return: String representing the key for the passed value, or null if no key is found

See also: fluid.findKeyInObject

fluid.log(str)

Log a message to a suitable environmental console. If the standard "console" stream is available, the message will be sent there - otherwise either the YAHOO logger or the Opera "postError" stream will be used. Logging must first be enabled with a call for the fluid.setLogging(true) function.

  • str {String}: the message to log

See also: fluid.setLogging

fluid.mergeComponentOptions(that, componentName, userOptions)

Merges the component's declared defaults, as obtained from fluid.defaults(), with the user's specified overrides

  • that {Object}: The instance to attach the options to
  • componentName {String}: The unique "name" of the component, which will be used to fetch the default options from store. by recommendation, this should be the global name of the component's creator function.
  • userOptions {Object}: The user-specified configuration options for this component

See also: fluid.defaults

fluid.merge(policy, target)

Merge a collection of options structures onto a target, following an optional policy. This function is typically called automatically, as a result of an invocation of fluid.initView.

  • policy {Object|String}: A "policy object" specifying the type of merge to be performed. If policy is of type String it should take on the value "reverse" or "replace" representing a static policy. If it is an object, it should contain a mapping of EL paths onto these String values, representing a fine-grained policy. If it is an Object, the values may also themselves be EL paths representing that a default value is to be taken from that path.
  • target {Object}: The options structure which is to be modified by receiving the merge results.
  • options {Object}: An arbitrary list of options structure which are to be merged "on top of" the "target". These will not be modified

Return: Object, the modified target

See: Options Merging for Fluid Components
See also: fluid.initView

fluid.mergeListeners(events, listeners)

Attaches the user's listeners to a set of events.

  • events {Object}: A collection of named event firers
  • listeners {Object}: Optional listeners to add

fluid.messageLocator(messageBase)

Converts a data structure consisting of a mapping of keys to message strings, into a "messageLocator" function which maps an array of message codes, to be tried in sequence until a key is found, and an array of substitution arguments into a substituted message string.

  • messageBase {Object}: The data structure of keys to message strings

Return: String (formatted) or an error message indicating that message string for the key wasn't found

fluid.model.composePath(prefix, suffix)

Assembles a path by concatenating two String values, representing portions of the path, with a "." separating them.

  • prefix {String}: A string representing the beginning of the path
  • suffix {String}: A string representing the end of the path

Return: String representing the composed path

fluid.model.copyModel(target, source)

Copy a source "model" onto a target

  • target {Object}: the object to be extended with the source
  • source {Object}: the object to add onto the target

fluid.model.getBeanValue

Evaluates an EL expression by fetching a dot-separated list of members recursively from a provided root.

  • root {Object}: The root data structure in which the EL expression is to be evaluated
  • EL {String}: The EL expression to be evaluated
  • environment {Object}: An optional "environment" which, if it contains any members at top level, will take priority over the root data structure.

Return: Function

fluid.model.parseEL(EL)

Parse an EL expression separated by periods (.) into its component segments.

  • EL {String}: The EL expression to be split

Return: Array of Strings

fluid.model.setBeanValue(root, EL, newValue)

Evaluates an EL expression by fetching a dot-sepearated list of members recursively from a provided root, and sets the value of the evaluated field.

  • root {Objecct}: The root data structure in which the EL expression is to be evaluated
  • EL {String}: The EL expression to be evaluated
  • newValue {Object}: the value to set the evaluated field to

fluid.remove_if(list, fn)

Can traverse through a list of objects, removing those which match a predicate. Similar to jQuery.grep, only acts on the list in-place by removal, rather than by creating a new list by inclusion.

  • list {Array}: The list of objects to be scanned over
  • fn {Function}: A predicate function determining whether an element should be removed. This accepts the standard signature (object, index) and returns a "truthy" result in order to determine that the supplied object should be removed from the list.

Return: Object (the modified list. *note that the original list is returned and it, itself is modified)

fluid.setLogging(enabled)

See also: fluid.log

fluid.stringTemplate

fluid.transform

fluid.unwrap

See also: fluid.wrap

fluid.VALUE

fluid.version

fluid.wrap

See also: fluid.unwrap

fluid.initComponents(that, className, args)

FluidDOMUtilities.js

fluid.dom.cleanseScripts(element)

Cleanse the children of a DOM node by removing all <script> tags. This is necessary to prevent the possibility that these blocks are reevaluated if the node were reattached to the document.

  • element {Element}: the parent element to begin removing <script> tags from.

fluid.dom.cleanseScripts.MARKER

Used to indicate that the DOM node has been stripped of all <script> tags

Constant: "fluid-scripts-cleansed"

See also: fluid.dom.cleanseScripts

fluid.dom.computeAbsolutePosition(element)

Returns the absolute position of a supplied DOM node in pixels. Implementation taken from quirksmode http://www.quirksmode.org/js/findpos.html

  • element {Element}: the element whose location is returned

Return: \[curleft, curtop\]

fluid.dom.getElementText(element)

Returns the element text from the supplied DOM node as a single String.

  • element {Element}: the element to return the text from

Return: String

fluid.dom.insertAfter(newChild, refChild)

Mockup of a missing DOM function

Inserts newChild as the next sibling of refChild.

  • newChild {Element}: the new element to insert
  • refChild {Element}: the element to insert newChild after

fluid.dom.isContainer(container, containee)

Checks if the specified container is actually the parent of containee.

  • container {Element}: the potential parent
  • conatainee {Element}: the child in question

Return: Boolean

fluid.dom.isIgnorableNode(node)

Determine if a node should be ignored by the iterator functions.
It will return true if the node is a Text node that is all whitespace or a comment node.

  • node {Element}: representing the DOM1 Node interface

Return: Boolean

fluid.dom.isWhitespaceNode(node)

Determine whether a node's text content is entirely whitespace

  • node {Element}: a node implementing the CharacterData interface (i.e., a Text, Comment, or CDATASection node

Return: Boolean

fluid.dom.iterateDom(node, acceptor, allNodes)

Walks the DOM, applying the specified acceptor function to each element. There is a special case for the acceptor, allowing for quick deletion of elements and their children.

  • node {Element}: a node to start walking the DOM from
  • acceptor {Function}: the function to invoke with each DOM element. If the return value is "delete", the element in question will be deleted. If the return value is "stop" the iteration will be terminated
  • allNodes {Boolean}: use true to call acceptor on all nodes, rather than just element nodes (type 1)

fluid.dom.iterateDom.DOM_BAIL_DEPTH

This is provided as a work around for IE's circular DOM issue. This is the default max DOM depth in IE.
http://msdn2.microsoft.com/en-us/library/ms761392(VS.85).aspx

Constant: 256

Defaults

Each Fluid component includes a standard options structure at its top-level. Options allow implementors to configure and customize a component. User-supplied options are merged with relevant defaults for the given components. These defaults registered by each component with the Fluid defaults management system via a call to fluid.defaults():

fluid.default(componentName, defaultsObject);

where

The options for each component (and their defaults) will vary, but all components share a subset of required defaults. These are:

Selectors

The selectors <something?> is a Javascript object that defines the necessary selector strings that will be used to access the various DOM elements that make up the component. Each component will have different selectors, but all components must have this selectors. Implementors can override the default selectors, so long as the selectors they provide meet the following requirements:

fluid.applySkin(skin, element)