This information is in draft form. Some parts are incomplete, or only present in point form. If you have comments or suggestions for improving this documentation, please contact ~a.cheetham@utoronto.ca.
Overview
The Fluid framework's DOM Binder makes it easy for users to change the look of a component by providing an interface that allows the component developer to access DOM elements though selectors, without knowing anything about the particular mark-up in question.
Components access elements in the DOM through unique selector names. The component defines default values for the selectors, but implementors are free to override the defaults if they choose.
Join the fluid-talk mailing list and ask your questions there.
Initialization
Component developers must declare the component's selectors in the defaults for the component:
fluid.defaults("fluid.newComponent", {
selectors: {
uiBit1: ".className1",
uiBit2: ".className2"
}
});
The DOM Binder is automatically created and attached to the component when the view is initialized with fluid.initView(). The DOM Binder's location() function is bound to that.locate() (see below for more information).
Using the DOM Binder
The component must use the DOM Binder for any access to the DOM elements that make up the component, using the locate() function:
that.locate(name, localContainer);
Parameter |
Description |
|---|---|
|
The selector name, as declared in the component's |
|
Optional. The container element used to constrain the search for the element. Defaults to the component container. |
Example
The Inline Edit component requires three parts in its user interface:
- a field to display the text that can be edited
- a field that can actually edit the text
- a container for the edit field
The component declares selector names for these elements, and provides defaults, in its call to fluid.defaults():
fluid.defaults("inlineEdit", {
selectors: {
text: ".text",
editContainer: ".editContainer",
edit: ".edit"
},
....
Here, the default selectors use class names. To use these defaults, an implementer can simply attach these class names to the relevant elements in mark-up. Alternatively, the implementer may choose to override some or all of these selectors with other selectors. For example:
var myOpts = {
selectors: {
text: "#display-text",
edit: "#edit-field"
}
};
var myIEdit = fluid.inlineEdit(myContainer, myOpts);
In this example, the implementer is using element IDs to identify the text and edit fields. Because a custom editContainer is not included, it will default to the class declared by the component.
To access the DOM elements, the Inline Edit component uses its DOM Binder:
that.viewEl = that.locate("text");
that.editContainer = that.locate("editContainer");
that.editField = that.locate("edit", that.editContainer);
In this way, the Inline Edit component is completely ignorant of the mark-up it is working with, or even the selectors used.