Floatbox v6.0 - Programmer's API Reference

floatboxjs.com

Functions

fb.start ( source, options )

fb.start creates and invokes a floatbox.

The 'source' parameter is overloaded. It can be a URI string (path to the content), a DOM element, an element's id, or a string of HTML.
The optional 'options' parameter can accept a string of floatbox options formatted the same as for data-fb-options attributes, or can accept an associative array (javascript object) of option name:value pairs.

Examples:
Load an image in floatbox with some options.
fb.start( 'path/image.jpg', 'controlsPos:tr caption:`my caption`' );
or fb.start( 'path/image.jpg', { controlsPos: 'tr', caption: 'my caption' } );

Launch an existing anchor in floatbox. Pass anchor's id, or the actual element itself, to fb.start().
fb.start( 'someAnchorId' ); or var myLink = fb.$('someAnchorId'); fb.start( myLink );

Open inline hidden div content.
fb.start( '#someDivId' ); or var myHiddenDiv = fb.$('someDivId'); fb.start( myHiddenDiv );

Use direct html as the content source.
fb.start( '<p>hello world</p>', 'roundCorners:none showClose:false' );
(The direct content string must contain '<' and '>' to be recognized as html.)

A dynamically added anchor could launch itself in floatbox with:
<a href="image1.jpg" onclick="fb.start( this ); return false;">click me</a>
An anchor started directly in this manner does not need a floatbox class and does not have to be activated by fb.activate().

Note that the options parameter can itself contain a 'source' option which will override the first source parameter. This allows you to define the entire start action in one associative array, and invoke a box based on that object with fb.start( null, myOptionsObject );

fb.end ( arg )

Call fb.end() to close a running floatbox.

The 'arg' parameter is optional and is overloaded in terms of functionality.
If 'arg' is a boolean value of true and multiple floatbox instances are currently open, all instances will be closed.
If 'arg' is a string it is assumed to be a URL and the base page will attempt to navigate to that URL when the floatbox end completes. The string 'self' will cause the currently loaded base page to refresh, while 'back' will load the previous item from the browser's history list.
(See the Multiple Floatboxes section for how to close a specific floatbox when more than one is open.)

Typical usage: fb.end( );
To navigate to a page on exit: fb.end( 'somePage.html' );

fb.resize ( width, height, left, top, animationTime )

Resizes and/or repositions an open floatbox.

The 'width' and 'height' parameters can assign specific dimensions or can request measuring and auto-sizing of the floatbox to match new content.
Positive integers will set the new content dimensions in pixels, not including the box decoration around the content.
If width and/or height are 0, or not provided, that dimension will be measured and set to the results of the measurement.
If a dimension is passed -1, that dimension will not change and will remain at its current size while the other dimension is set or measured.

The 'left' and 'top' parameters accept the same values as the 'boxLeft' and 'boxTop' options, or can be set to -1. Positive integers assign pixel location relative to the visible browser viewport, percentages will move the box a portion of the screen's available free space, and 'auto' will re-center the floatbox on the screen. If the 'left' or 'top' parameters are -1, the corresponding position will not change and the left and/or top side of the floatbox will remain where it is while re-sizing occurs. When the 'left' and 'top' options are not provided, or are 0, box positioning is determined by the current values of the 'boxLeft' and 'boxTop' options (which default to 'auto').

The speed of any animated resizing or relocation of a resized floatbox is determined by the resizeTime option. That setting can be overridden in any fb.resize() call by passing the target animation time in seconds to the animationTime parameter. Pass in 0 here to temporarily turn off resizing animations and instantly jump the box to it's new size and position.

Examples:
If the html content in a floatbox has just been dynamically changed in some fashion, the box can be resized to the new content's width and height with a simple call of fb.resize( );
A specific new width combined with a re-measure of the height can be requested with fb.resize( 350 );
The width can be held at its current value while the height is set to specific value with fb.resize( -1, 500 );
The same resizing can be done with a simultaneous positioning of the box in the top-left corner of the screen with fb.resize( -1, 500, 5, 5 );
A floatbox can be remeasured with its current position held constant and resize animations disabled with a call of fb.resize( 0, 0, -1, -1, true );

fb.reload ( source )

Reloads the content in an already running box.

Only content of types iframe, image and ajax can be reloaded. Inline, media and direct content cannot be.
The optional 'source' parameter is a URI path to new content that can replace current box content of the same type without altering or resizing the existing box.
Standard usage leaves the 'source' parameter empty thereby causing the existing content to be re-fetched. To load new content in a floatbox, it's probably better to use the fb.start() function and include the 'sameBox:true' option in that call.

fb.activate ( node )

fb.activate crawls a node or a document and assigns actions to elements that are marked up for some kind of floatbox behaviour. It activates floatboxed anchors, image cycler sets, enhanced tooltips, context boxes and popup thumbnails.

When dynamically adding floatbox-enabled elements to a page some time after the initial page load, you can run fb.activate() to 'light up' that new content. Until activated in some manner, floatbox elements on the page will not have behaviours attached and the links will open just like normal links with the browser navigating to the href'd page.
Instead of manually invoking fb.activate() from your code, you can set the 'activateOnClick' option to true and have fb.activate run whenever the main document is clicked or touched. See the instructions and the options reference for 'activateOnClick' details.

fb.activate's 'node' parameter is optional. If provided, it should be a node's id or the node object itself that contains the elements requiring activation. If the node parameter is not provided, the entire document will be crawled.

The easiest way to dynamically fetch and add new content to a page is with the floatbox library function 'fb.ajax', described below.
When you use this function with its 'updateNode' parameter, fb.activate() will be automatically run against that node for you.

For any other method of dynamically adding new floatbox content, your code will have to invoke fb.activate() after the new content is in place or, alternatively, set the 'activateOnClick' option, or, have an onclick action of onclick="fb.start( this ); return false;" assigned.
See the section about dynamically loading floatbox content in the instructions for examples of using fb.activate with traditional ajax calls, jQuery and ASP.NET UpdatePanels.

fb.pause ( boolean )

fb.pause( true ) pauses a running slideshow (started with the 'doSlideshow' options) and fb.pause( false ) resumes a paused one.

fb.showItem ( index )

Use showItem to change the currently displayed image in a gallery set to another member of that set.

The index parameter can be a number, or a string of 'next' or 'prev'. If it's one of the strings, a gallery set will show the previous or next item in the set, wrapping around the set ends if necessary.
If a numerical index is provided, the corresponding item from the gallery set will be shown. The first item in a set has an index of 0.
For example: fb.showItem( 3 ) will show the 4th item in a currently displayed gallery set while fb.showItem( 'next' ) will show the next item.

fb.goBack ( )

If a previous item has been displayed in a floatbox instance (either because a gallery set is running or content has been updated with either fb.reload or by fb.start combined with the sameBox:true option) fb.goBack will reload the item displayed immediately prior to the current item.
An example of how this might be used can be found in the news-reader example on the HTML tab of the Floatbox demo page.

fb.itemCount & fb.currentIndex

(These aren't callable functions, but rather simple property values.)
When showing a gallery set of multiple items (usually images), the fb.itemCount and fb.currentIndex properties can be used to fetch the number of items in the gallery set and the index of the currently showing item within that set.
See the 'Multiple Floatboxes' section below for information about how to read these properties for specific floatbox instances when more than one box is open simultaneously.

Back to Index

Multiple Floatboxes

Multiple floatboxes can be open at the same time, and actions such as ending or resizing a floatbox may need to determine which floatbox is to be acted upon. When the functions are invoked as members of the 'fb' object as shown above, they will act upon the top-most floatbox.

To explicity act upon a particular floatbox when multiple boxes are open, get a reference to the floatbox instance of interest and run the desired function from that instance. The functions that can be run directly from an instance reference are: end, resize, reload, pause, showItem and goBack.

fb.getInstance ( name )

Use fb.getInstance to retrieve a reference to a particular floatbox instance when more than one is open simultaneously.

Each floatbox instance has a name which can be assigned using the instanceName option. If no name is assigned, the filename (without extension) or the id from the starting item will be used as the name. Retrieve a reference to a particular floatbox instance by calling fb.getInstance with the name of the box.

Alternatively, the 'name' parameter can also be a numeric index into the fb.instances array. References to all open floatbox instances are captured in the fb.instances array with the first opened instance having an index of zero.

Here's an illustrative example using a named floatbox instance. Suppose we have a floatbox that opened content from a hidden div with an id of "Bob" (e.g., href="#Bob"). We can then close that particular floatbox as follows:

or simply...

We were lazy in that example and just used the name that was picked up in the background from the starting href. To be more clear and obvious in our coding, we probably should have explicitly assigned a name to the box and used that. Like this:

(The default instance name in this example would have been "some_page" had we not set instanceName with our own value.)

fb.getOwnerInstance ( node )

getOwnerInstance accepts a DOM node or an id string and returns the floatbox instance (if any) that contains the passed node. If the referenced node is not in a floatbox, getOwnerInstance returns null.

The ability to determine the owner instance of a node can be handy when multiple floatboxes are open and you want to execute an API action against a particular instance.

For example, suppose we want to close a floatbox from an onclick action somewhere in its content:

<instance>.fbContent, etc.

fbContent is the DOM node (element) holding the content that is displayed by a floatbox. It may be an img, iframe, or div depending on what kind of content is currently showing.
Having this node reference can be helpful when dynamically working with floatboxed iframe or other html content.
The components of the first floatbox opened (often the only floatbox displayed) can be reached as a reference from the global 'fb' object, such as 'fb.fbContent'. Use 'fb.getInstance' or one of the other instance references to get to the fbContent element for secondary (stacked) floatboxes and retrieve the components by name as properties of the particular instance. - e.g. fb.getInstance( 'name' ).fbContent
Other floatbox components can be similarly accessed. For example, if you want to manipulate the caption, it can be reached through the 'fb.fbCaption' or '<instance>.fbCaption reference.

Back to Index

Event Callbacks

The Floatbox API includes various event callbacks that allow you to run custom code at various points in a floatbox's life-cycle. The callbacks are setup us Floatbox options to which Javascript code is assigned. The callback options are assigned their values in the same manner as other options and can be defined in fbPageOptions or on an anchor's rev or data-fb-options attribute.
Callbacks defined in a page's fbPageOptions definition can be either true javascript functions or strings to be eval'd.
By their nature, callbacks defined as options in an anchor's data-fb-options (or rev) tag will be strings and so will be eval'd.

If any of the before* callback functions return a value of false, the associated Floatbox action will be cancelled.
This applies only to callbacks defined as true functions. Eval strings do not return values and so cannot cancel Floatbox actions.

Some callback functions will receive an argument that is the active floatbox instance. This might be handy for something like checking the state of the HTML within fbContent prior to allowing a box end to occur. The callbacks that receive the instance parameter are beforeItemStart, afterBoxStart, afterItemStart, beforeItemEnd, beforeBoxEnd, beforePrint and afterResize.

Example - A function callback in the page options:

And a string callback in an anchor's data-fb-options attribute:

(Don't forget the back-quotes. They're required for correct parsing.)

beforeBoxStart

beforeBoxStart is executed prior to a floatbox being started by either a click on an activated anchor or by an API fb.start call.
It could be used to check that desired conditions have been met before starting up the floatbox, and cancelling the box start by returning false from the assigned function if the conditions are not right.

beforeItemStart

The only practical difference between beforeItemStart and beforeBoxStart occurs when a gallery set of items is being displayed. beforeItemStart will fire whenever the associated gallery set item is shown whereas beforeBoxStart will not when the floatbox navigates to a new content item in a set. If the beforeItemStart returns false from an assigned function, the floatbox will not start if it is just starting up, or else will not navigate if it is responding to a previous or next command in gallery set.

afterBoxStart

afterBoxStart runs as soon as a new floatbox is initially created. It differs from beforeBoxStart in that it cannot cancel the floatbox's creation and it receives a single parameter which is a reference to the newly created floatbox instance.
afterBoxStart could be used to tweak or modify some of the components in the reference floatbox.

afterItemStart

afterItemStart runs whenever new content is shown in a floatbox, either because the floatbox has just started, or because the associated item has just been invoked by a previous or next action in a gallery set.
The afterItemStart function receives a reference to the current floatbox instance, and may be used to setup initial states or behaviours in the freshly arrived content. It can be considered as similar to a window.onload event where the 'window' is the floatbox display area (fbContent).

beforeItemEnd

beforeItemEnd is fired whenever a currently showing item is about to go away, either from its host floatbox closing, or from a gallery set navigation. It receives a single parameter that is a reference to the current floatbox and could be used to check that conditions in the content have been met and can cancel the box end or navigation by returning false from its assigned function.
For example, suppose we have a quiz with a series of multiple choice questions shown as a multi-question gallery set. beforeItemEnd could check that an answer has been selected and, if not, could alert that all questions must be answered and then return false to cancel navigation to the next question.

beforeBoxEnd

beforeBoxEnd is fired prior to a floatbox closing, receives a parameter of current floatbox instance, and can return false to cancel the closing of the floatbox.
It could, for example, be used to ask for confirmation before closing a displayed shopping cart that had unprocessed items in it.

afterItemEnd

afterItemEnd will fire whenever a floatbox item goes away, either because the floatbox has closed or because a gallery set has navigated to a new item.
This is probably the least useful of Floatbox's callbacks and is provided primarily for consistency. It could be used for something obscure like sending an AJAX notification back to the server that reports how long the departing item was viewed.

afterBoxEnd

afterBoxEnd fires when a floatbox has finished closing in response to one of the close controls or from an API fb.end call.
This is useful in an interactive web page to invoke an action or behaviour when the user is finished with the floatbox and closes it. (Note: If it's page navigation or refresh that you want to do after a floatbox closes, be sure to check out the 'loadPageOnClose' option and the 'fb.end()' API function.)

afterResize

The afterResize callback fires whenever the floatbox content changes size for whatever reason. This includes when it first opens, when it is drag-resized with the mouse or touch gesture, when an auto-sized image is viewed full size, when the floatbox adjusts in response to centerOnResize, and whenever the fb.resize() API function is called.
Use afterResize as a trigger to manipulate DOM elements in HTML content or perhaps overlay something on top of a displayed image. afterResize is one of the callbacks that receives the floatbox instance as its parameter in order to facilitate access to components such fbContent.

beforePrint

beforePrint will fire whenever Floatbox's node printing capability is invoked, whether directly through the fb.printNode API function or through the 'showPrint' option.
Use this to manipulate content prior to printing, or perhaps to display a message or disclaimer. Returning false from your function will cancel the print request.

afterPrint

afterPrint fires at the conclusion of the printing of a node and could be used to provide further instructions or present related content.

Back to Index

Library Functions

In addition to the floatbox functions described above, the fb object exposes a comprehensive set of functions that allow you to use floatbox as a javascript library.
The floatbox library is a robust and correct collection of functions that make it easy to manage ajax, flash, events, forms, DOM interactions and many other operations simply and reliably across all client browsers.

Note: All library functions that have a 'node' parameter will accept either a DOM element or the id string for an element as that parameter.

fb.$ ( id, doc )

The fb.$ function is short-hand for 'document.getElementById', with additional behaviour.

If the id parameter is a string, it will return the element that has that id, or null if there is no such element.
If the id parameter is already an element, that element will be returned.
The optional 'doc' parameter is for iframe environments and is a specific document element on which to look for the requested id.
If no 'doc' parameter is passed, each document in a heirarchy of same-domain iframes that have the floatbox code installed will be searched for the requested element, starting with the top (base) document.

fb.DOMReady ( func )

Use fb.DOMReady to register a function to be called as soon as possible after a document's DOM is fully loaded and ready for interaction.

The single parameter is a function to be exectured at DOMContentLoaded time.
The fb.DOMReady function supports all browsers, including older versions of IE that do not have built-in support for DOMContentLoaded.

fb.addEvent ( node, action, func )
fb.removeEvent ( node, action, func | obj)

These two functions standardize DOM2 event handling across different browsers, removing most of the troublesome characteristics of older IE's event handlers.

All parameters are required.
The 'node' parameter is the element (or its id) to attach (or detach) the event handler to. The same event handler(s) can be assigned in one go to multiple nodes by passing an array of nodes and/or ids as the node parameter.
The 'action' parameter is the name of the event you want to target. For DOM2 events, do not include the 'on' prefix used by IE (e.g., use 'load' and not 'onload'). 'action' can be an array of action names to assign the same function as the handler for multiple event types.
The event handler code is passed as a function in the third parameter.
Using fb.addEvent standardizes event handling across all browsers (including old Internet Explorer) to align with DOM2 event standards by ensuring the following:

• The 'this' keyword in the event handler function will properly reference the element to which the handler is attached.
• The event object will be passed as a parameter to the event handler function.
• The event.target property will be present and will reference the element which received the triggering action. ('target' may be different than the element the handler is attached to.)

The return value for fb.addEvent is a javascript object that can be passed to fb.removeEvent to detach the assigned event handler. Retaining this value for future event removal helps minimize memory leaks in IE.
Example:

fb.addEvent and fb.removeEvent can also be used to assign and remove DOM0 events by having the action parameter begin with 'on'. For example, fb.addEvent ( someNode, 'onclick', someFunc ) will assign a DOM0 click action equivalent to someNode.onclick = someFunc.
The DOM0 event handlers are standardized in the same way as described for DOM2 events above, with a proper 'this' keyword, an event parameter, and event.target set.

fb.stopEvent ( e, stopPropagation, preventDefault )

fb.stopEvent is a cross-browser way to manage the bubbling (propagation) and default action behaviours for an event.

Pass the event you want to block as the first manadatory parameter.
The optional 'stopPropagation' and 'preventDefault' parameters give control over these specific aspects of the event sequence. 'stopPropagation' defaults to false while 'preventDefault' has a default value of true, meaning that without explictly requesting different handling, the event will propagate but the default action will not fire.
stopEvent's return value is always a boolean false that can be passed through by your calling function.
For example, to stop the default click behaviour in the example above for addEvent, we would make our click function look like this:
function( e ) { alert( ... ); return fb.stopEvent( e ); } )

fb.extend ( objTarget, objSource [, objSource2 ...] )

Merges and duplicates javascript objects.

fb.extend takes any number of javascript objects as parameters and extends the properties and values of the first object with those from the other objects.
The target object is modified in place and is also the return value of the function.
If passed only a single object in the parameters, fb.extend will return a duplicate copy of that object.
fb.extend( myObj, yourObj ) will copy yourObj's name:value pairs into myObj.
ourObj = fb.extend( {}, myObj, yourObj ) returns a new merged object without modifying myObj.
newObj = fb.extend( oldObj ) returns a new object seeded with name:value pairs from oldObj.

fb.executeJS ( strURI, callback )

Use fb.executeJS to dynamically load and execute an external javascript file.

The javascript file can come from any domain (cross-domain scripting restrictions are not in effect).
The optional callback function will be fired after the external javascript has completed execution.
fb.executeJS can be useful for performing 'lazy loads' of javascript files in a document's window after the page has been rendered, and is in fact used internally for the dynamic loading of the Floatbox modules. It is also a good mechanism for fetching JSONC/JSONP data or loading API services such as those from Google Code.
For example, Google's translation widget can be dynamically added to a page with something like

fb.getFormValues ( source )

Returns an associative array of all the name:value pairs respresenting the elements of a form.

The source parameter can be a form DOM element, a form's name, or a form's id.
The getFormValues function provides correct form handling as per the W3C forms recommendations and properly handles empty and missing values, radio buttons and user defined input types.
The following input element types are ignored: file, image, reset, submit and button.

fb.serialize ( source )

serialize returns a properly encoded string of name=value pairs that can be used as a URI's querystring or for submission by an AJAX POST call.
The source parameter accepts any of an associative array, a form DOM element, a form's name, or a form's id.
If a form is passed as the source, the values are first parsed out using getFormValues and the result of that is serialized.

fb.deserialize ( str )

deserialize reverses the serialize function by taking an encoded parameter string as its argument and returning an associative array (javascript object) of decoded name:value pairs.
The passed string is first run through fb.decodeHTML to translate encoded HTML entities such &amp; into their corresponding simple characters.

fb.addClass ( node, className )

Use addClass to assign one or more class names to one or more document nodes (elements). The 'node' parameter can a node reference or a node's id, and can be an array of nodes or ids for multiple assignment in one call. Multiple classes can be assigned in one go by passing an array of class names as the className parameter, or with a string containing multiple names separated by spaces.

fb.removeClass ( node, className )

The companion function to fb.addClass, removeClass will also accept an array of nodes or node ids, and an array of classNames or multiple classNames separated by spaces in a string.

fb.hasClass ( node, className )

Returns a boolean value reporting whether the referenced node has className assigned to its 'class' attribute. The node can be passed in as an actual DOM node reference, or as a node's id. Multiple class names can be searched for in one call by passing an array as the 'className' parameter, or by separating names with spaces in a string parameter. If any of the class names are present, the return value will be true.

fb.attr ( node, name, val )

Reads, sets, or removes an attribute from an element.

The node parameter can be an actual element reference or an element's id. Pass null to the val parameter to remove the named attribute. If val is not provided (is undefined), fb.attr will return the current value of the named attribute, or the empty string if the attribute is not present. If val is neither null nor undefined, the named attribute will be assigned the passed value. The attribute will be created if it is not already present.

fb.hasAttribute ( node, attribute )

Returns true or false based on whether the DOM element 'node' has 'attribute' set in its tag.

The node parameter can be a DOM element or the string id of an element. If the attribute is present on the node, even if set to an empty string, the function will return true.

fb.getByClass ( className[s], node )

This is a getElementsByClassName substitute which returns an array (not a node list) of elements within 'node' that have a class name of 'className'. It works reliably on all browsers, including the old ones that don't natively support getElementsByClassName.

The className parameter can be a simple string or an array of strings. If an array, all elements that have any of the requested classNames will be returned.
The 'node' parameter is optional, can be provided as an element reference or an id string, and will default to the <html> element if not given.

fb.getByTag ( tagName, node, which )

This is a getElementsByTagName substitute which returns an array (not a node list) of elements within 'node' of a requested type (e.g., 'div' or 'img').

The 'node' parameter is optional, can be provided as an element reference or an id string, and will default to the entire document if not given.

If the number 0 is passed in as the 'which' parameter, the first element within 'node' of type 'tagName' will be returned. If 'which' is -1, the last element within 'node' of type 'tagName' will be returned.

fb.getStyle ( node, property, integerize )

Returns the cascaded or computed (currently active) style for a given element.

The optional 'property' parameter is any css property. You can use either the css or camelCase property syntax (i.e., 'font-size' or 'fontSize').
If 'property' is not passed, the return value will be a cssText string of all effective styles for the referenced node in the form 'property1: value1; property2: value2;...propertyN: valueN;'.
If the 3rd parameter is 'true', the return value will be an integer. E.g., a style of '49px' will come back as the number 49. Example: size = fb.getStyle( 'someId', 'font-size' )

fb.getScroll ( win )

fb.getScroll returns the current amount by which the document is currently scrolled. The return value is an associative array containing the two named values 'left' and 'top'. Pass a reference to an iframe's window as the optional 'win' parameter to retrieve an iframe's current scroll state.
Example usage:

fb.getViewport ( )

fb.getViewport returns the current dimensions in pixels of the browser window. The return value is an associative array containing the two named values 'width' and 'height'.
Example usage:

fb.getLayout ( node, local )

Use getLayout to get the position and dimensions of any node (or image area element) on a page.

getLayout accepts a DOM node or an element's id string and returns an associative array containing the values 'left', 'top', 'right', 'bottom', 'width' and 'height'.
Coordinates a screen-based, not document coordinates. To get document coordinates, add in the current page scroll values.
If the optional second parameter is true and the node is inside an iframe, the returned 'left', 'top', 'right' and 'bottom' coordinates will be relative to that iframe's window, otherwise the coordinates are relative to the top page's viewport.

The getLayout function is similar to the native getBoundingClientRect function except that it can 'see through' iframes and give position coordinates relative to the top document, works on older browsers, adds 'width' and 'height' to the return values, and will return layout information for image map area elements.

fb.getIframeDocument ( node )
fb.getIframeWindow ( node, allowCrossDomain )

These functions return an iframe's document object and window object respectively.

'node' is an optional parameter. If provided, it must be an iframe element or the iframe element's id. The iframe does not have to be inside a floatbox.
If 'node' is not passed, the fbContent element in the top floatbox instance (from a zIndex perspective) will be used.
If the optional 'allowCrossDomain' parameter is passed as true, fb.getIframeWindow will return cross-domain window objects as well as same-domain ones. This can be useful in setting up HTML5 messaging between cross-domain windows.

Null is returned if node is not an iframe and neither is the top-most floatbox's content element.

A simple example; get the window object of the iframe in the only running floatbox:
win = fb.getIframeWindow( ).

fb.nodeContains ( parentNode, childNode )

fb.nodeContains returns true or false based on whether the DOM element 'childNode' is contained inside the 'parentNode' element.

Both parentNode and childNode are mandatory arguments and can be either the actual DOM element or a string id value that identifies the element.
If parentNode and childNode are the same node, true is returned.
fb.nodeContains will 'see through' iframes. That is, if childNode is inside an iframe and that iframe is inside parentNode, fb.nodeContains will return true.

fb.preload ( imagePath, callback )

Fetches one or more images into the browser's cache.

Pass fb.preload the source path for the image to preload as a string. Or, pass an array of source path strings for images to be preloaded.
If the optional callback function is provided as the second parameter, that function will be invoked when the image preload completes.
The callback function can accept a single parameter that will be the unattached img element containing the preloaded image.
If imagePath is an array, callback is called after the last image loads.

fb.printNode ( node, style )

Use printNode to display a print dialog to your users that will print only the contents of a particular node, rather than printing the full page.

The printNode function accepts two arguments, both of which are optional.
The node parameter accepts either a DOM node or an element's id string. If node is null, the contents of the top-most floatbox will be printed.
You can apply styles to the print node's content using the optional style value. 'style' can be a string of css definitions (like you would place in a <style> element), or can be the path to a css file that contains the css definitions to be applied.

fb.getOuterHTML ( node )

Not all browsers support the outerHTML property on elements. fb.getOuterHTML will return the outerHTML (innerHTML plus the element's own markup) for any element in all browsers.

fb.setInnerHTML ( node, html )

This is a safe way to assign innerHTML to any element. It works reliably on both text/html and application/xhtml-xml pages.

The 'html' parameter is optional and defaults to the empty string. Applying the empty string clears the node of all its existing innerHTML.

fb.encodeHTML ( html )
fb.decodeHTML ( html )

fb.encodeHTML takes a string and returns that string with all & < > and " characters encoded to &amp; &lt; &gt; and &quot;.
fb.decodeHTML reverses that process and also decodes &apos; to a single quote and decodes numbered entities like &#222; to their character equivalents.

fb.typeOf ( thing )

The fb.typeOf function extends javascript's builtin 'typeof' operator by resolving and correcting ambiguous 'object' return values.

The return value will be one of 'number', 'string', 'boolean', 'object', 'array', 'function', 'date', 'NaN', 'undefined', 'null', 'node', 'window' or 'regexp'.
Note that IE (all versions) has major problems handling dynamically created and destroyed windows inside iframes. fb.typeOf will detect a tombstoned window in IE and return a value of 'null' for it.

fb.forEach ( object, function, all )

Use fb.forEach to execute a function against each member of an associative array (javascript object).

The function takes two mandatory parameters: object is a javascript object, array or object-like entity and function is a function which will receive two parameters of the 'name' and 'value' for each entry in the object.
Normally, fb.forEach invokes the function only for properties for which hasOwnProperty is true. Set the optional third parameter 'all' to true to iterate over all properties, not just the 'owned' ones.
Example:

fb.flashObject ( {
     source: strURI,
     width: numPixels,
     height: numPixels,
     params: { name: value [, name: value] } | strOptions,
     node: node | id,
     id: string,
     altContent: strHTML,
     minVersion: strVersion,
     success: function,
     failure: function
} )

A full-featured, but simple to use, script component that adds flexible cross-browser Flash objects to a page.

fb.flashObject can be used as a reliable and safe alternative to SWFObject, removing the need to have both scripts on the same page. It supports alternate content, Flash version checking, success and failure callbacks and provisioning of all Flash parameters.

• source (mandatory) is the path to the swf file. ('url' is an allowed alias for the 'source' parameter's name.)
• width and height ( mandatory) are the dimensions of the flash object in pixels.
• params (optional) is either an associative array or a string of parameters to be assigned.
  Note that params can also be passed as name=value pairs in a querystring appended to the source URL.
  The default parameters in object notation form are { allowFullScreen:'true', allowScriptAccess:'always', loop:'false', quality:'autohigh', scale:'exactfit', wmode:'opaque' } or, equivalently as an options string, 'allowFullScreen:true allowScriptAccess:always loop:false quality:autohigh scale:exactfit wmode:opaque' or, as a querystring to be placed on the source path, 'allowFullScreen=true&allowScriptAccess=always&loop=false&quality=autohigh&scale=exactfit&wmode=opaque'
  (Please see http://helpx.adobe.com/flash/kb/flash-object-embed-tag-attributes.html for a complete list of available flash parameters.)
• node is an optional parameter that can be a DOM element (normally a span or div) or the string id of an element. If given, the flash object will be inserted inside the referenced node. If 'node' is not provided, the flash object is created immediately above the script element that is executing the fb.flashObject function. The node's current HTML will be used as the alternate content source for browsers that don't have a usable Flash plugin.
• An id can be assigned to the flash object using the optional 'id' parameter. An id is useful if you need to interact with the Flash object using scripted controls.
• altContent can be used to assign an HTML string to be shown for client agents that don't have the Flash plugin installed and active. It's probably easier to have that HTML reside directly in the target node (assuming there is a target node) and not assign it here.
  If no altContent is provided, the default altContent will be a short message of "Flash Player is required to view this content", presented in the localized language of the user's browser, and followed by a link to the Flash download page.
• Use minVersion to specify the minimum Flash version required to show the swf content. The version string must include major version, and can include minor and revision levels. E.g., '8' or '8.1' or '8.1.2'.
  If the minimum version requirements are not met, the alternate content will be shown.
• success and failure are callback functions that will be fired after fb.flashObject has added its HTML to the document. 'success' will be called if the requested Flash object is present and 'failure' will be called if the alternate content is shown. These two callback functions can be provided as true functions or as strings of javascript code.

A simple example:

fb.ajax ( {
     source: strURI,
     updateNode: node,
     postData: form | formID | formName | object | string,
     success: function( xhr ),
     failure: function( xhr ),
     finish: function( xhr ),
     timeout: msecs,
     cacheable: boolean,
     async: boolean,
     headers: { name: value [, name: value] }
} )

The fb.ajax function is an XMLHttpRequest object wrapper that provides AJAX functionality for dynamic content and data fetches using a simple and flexible function call. Both GET and POST requests are supported, a page element can be updated directly with the returned content, callback functions are available for more complex handling requirements, and both synchronous and asynchronous calls are supported.

• The source parameter is mandatory (the others are optional). This is the URI of the page you are fetching the ajax content from. ('url' is an allowed alias for the 'source' parameter's name.)
  Note that ajax calls cannot go across different domains and that the source parameter must reference a resource that's on the same domain as the current page. For this reason, it's best to use relative URIs in your ajax calls (leave out the "http://someDomain.com" part).
• If the updateNode parameter is present, the element referenced by that parameter will be updated with the request's response text from the server.
  Use this to automatically populate a div on your page with content from your ajax call.
  updateNode can be either a DOM element object or the id of an element.
  If there are anchors in the fetched content that are marked up for floatbox behaviour (i.e., have class="floatbox" on them), or there is other floatbox content such as cyclers or tooltips, that content will be automatically activated by fb.activate after the update.
  Any script elements in the incoming content will be reliably executed.
• If the postData parameter is present, a POST request will be made to the server. If postData is not present (or is empty), a GET request will be made.
  The postData parameter is versatile: it can accept a parameter string of encoded name=value pairs separated by ampersands, an associative array (JSON object), a form DOM node, a form's id, or a form's name.
  If postData points to a form, the form values will be properly serialized and the resultant encoded parameter string will be sent with the POST request.
  Similarly, a JSON object will be serialized to an encoded parameter string.
  Note: If you are passing a string directly and any of the name or value components might contain interesting characters, those names and values should be encoded using encodeURIComponent before being concatenated.
• The success, failure and finish functions, if present, will be executed when the ajax request has completed.
  The single parameter passed to these functions is the XMLHttpRequest object which can be used to access response values such as xhr.status, xhr.responseText and xhr.responseXML.
  The success function will fire only if the request succeeds, failure> will fire only in the event of a failure, but finish will always fire (after success or failure).
  For legacy support, 'callback' is an allowed alias for the 'finish' parameter name.
• The timeout parameter is used to place a limit on how long to wait for a response and is given in milliseconds.
  If the request does timeout, neither 'success' nor 'failure' will fire, but the 'finish' callback will. The finish function can determine that a timeout occurred by checking if xhr.status is 0.
• The cacheable parameter defaults to true and is a suggestion to browsers that they can retrieve the content from their local cache if they have it there. If 'cacheable' is set to false, the source URL will have an additional query string parameter called "no_cache" added to it, and this parameter will be set to a unique numeric string. This 'no_cache' parameter ensures that the ajax source cannot be fetched from browser cache.
• The async parameter defaults to true. If set to false, javascript processing is suspended until the AJAX fetch completes. The XMLHttpRequest object is returned by the fb.ajax call and can be used to retrieve the status and response of the completed AJAX fetch.
• The headers parameter takes an object of name:value pairs of custom request headers that are to be used in the ajax call.
  Headers for caching, posting ('Content-Type'), and 'X-Requested-With' are already provided by the ajax function.
  An fb.ajax call with custom headers might look like this:
  fb.ajax({ source:'xyz.php', headers:{ 'Content-Type':'text/xml;charset=utf-8', 'X-My-Header':'MyValue' } });

Here's an example that updates the contents of a div called "contents" and puts the time of the update into a span element using Floatbox's ajax support:

Back to Index