Floatbox v3.54 - Programmer's API Reference

randomous.com

Index

Variables and Properties

fb

Floatbox's primary object is the global var "fb". All properties and functions are members of the fb object.

If you are running floatbox in a hierarchy of iframes, the fb objects in each child window are references to the fb object on the top document. (i.e., there is only one fb object even though there are multiple window objects.) An iframe displayed by floatbox that does not have floatbox.js included on its document will not have the global fb var in its window's scope. To programmatically use fb from such a child iframe, fetch it from the parent window by referring to it as "parent.fb".

fb.lastChild

Floatbox can display multiple boxes at one time, such as when displaying an info box over top of a displayed image. fb.lastChild always points to the top most box (the last one loaded). If there is only one box (or none displayed yet), fb.lastChild === fb.

fb.parent

For any given box, .parent points to the box immediately below it. For example, if 3 boxes are stacked up, fb.lastChild.parent will point to the middle box. fb.parent (fb always being the primary, bottom, first-loaded box) is identical to fb.

fb.children

fb.children is an array of pointers to however many stacked child boxes are currently open. When two boxes are open, fb.children will have length = 1 and fb.children[0] === fb.lastChild. The primary box, fb, does not have an entry in the .children array.

fb.anchors

fb.anchors is an array that holds associative arrays of information about anchors that have been "tagged" for handling by floatbox. If you need to clear out fb's memory of anchors it has seen, set fb.anchors.length = 0. You may want to do this if you are dynamically updating content on your page, want to run fb.tagAnchors (described below) to re-inventory the page, and don't want to keep old, now-removed, anchor information in the floatbox working set.

fb.fbContent

fbContent is the node (element) holding the content that is displayed by 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 div html content. Use the 'children' pointers to get to the fbContent element for secondary (stacked) floatboxes - e.g. fb.lastChild.fbContent.

fb.loadPageOnClose

loadPageOnClose is just one of floatbox's many options (see the options reference for a full list). It is mentioned here because it can be quite useful in programming active floatbox content, specifically, for refreshing the base page or navigating to a new page on floatbox exit. Details about loadPageOnClose can be found in both the options reference and the 'auto-start and exit tasks' section of the instructions. Example usage: fb.loadPageOnClose = 'somePage.html';.

Back to Index

Functions

fb.start( { href: strURL, rev: strOptions, title: strTitle, html: strHTML } )
fb.start( strAnchorID )
fb.start( anchorNode )

fb.start is how you programmatically launch a floatbox without the need for a user's onclick action. fb.start is overloaded. You can pass it an associative array, an anchor's id, or an anchor DOM element.

To launch an existing anchor in floatbox from script, pass the anchor or its id to fb.start().
fb.start('someAnchorId');
A dynamically added anchor might launch itself in floatbox with:
<a href="image1.jpg" onclick="fb.start(this); return false;">click me</a>
The anchor does not need a floatbox class and does not have to be pre-tagged by fb.tagAnchors().

You can define floatbox content directly without having a corresponding anchor on your page by passing an associative array to fb.start.
fb.start({ href:'someUrl.html', rev:'option1:value1 option2:value2' }).
As an alternative to the href url parameter, you can direct load a string of html markup by passing that html as a name:value pair named "html". Either "href" or "html" must be present. "rev" and "title" are optional. Hint: use the option "sameBox:true" in the rev: string to load new content in an existing floatbox without invoking a new box.

fb.end( )

Call fb.end() to close a running floatbox. With multiple stacked boxes, only the top-most floatbox will close regardless of which box's end function was called. To close all stacked boxes at once, call fb.end(true).

fb.tagAnchors( node )

When you dynamically add floatbox-enabled anchors to a page - through AJAX or any other method - you need to run fb.tagAnchors against the new content. Doing so adds the new anchors to floatbox's inventory, and sets the onclick action for those anchors.

It is more efficient to pass a node that contains the new content to tagAnchors to avoid re-crawling the entire document: fb.tagAnchors('myDiv'). But there is no harm done if you re-tag the entire document with fb.tagAnchors(). The node parameter can be an actual DOM element or a string that is the classname of an existing DOM element. If you call fb.tagAnchors with no parameter, it will default to tagging the document.

You can clear pre-existing anchor records out of floatbox's inventory with fb.anchors.length = 0 prior to making the tagAnchors call. See the AJAX section near the bottom of the floatbox instructions page for examples of using fb.tagAnchors in a javascript AJAX fetch and in an ASP.NET UpdatePanel.

fb.tagOneAnchor( node )

tagOneAnchor is overloaded. The "node" parameter can be a true anchor node or its id, or it can be an associative array that mimics an anchor's attributes. Example: You could dynamically add a new member to a grouped set of floatbox items with the following:
fb.tagOneAnchor( { href:'someImage.jpg', rev:'group:myGroupName' } );

fb.resize( width, height )

Resizes the top-most running floatbox to the new requested dimensions. Width and height are the new content dimensions in pixels, not including the box decoration around the content.

fb.pause( bool )

fb.pause(true) pauses a running slideshow and fb.pause(false) resumes a paused one.

fb.showPrevious( )
fb.showNext( )

Displays the previous or next item in a gallery set (group) of items. If you're already showing the first or last item in a set, wrap behaviour is determined by the 'enableWrap' option.

fb.showItem( index )

Displays item number 'index' from a currently loaded gallery set. The first item in a set has an index of 0.

fb.goBack( )

If a previous item has been displayed in the top-most running box, either because a gallery set is running or you have updated content with fb.start and sameBox:true, fb.goBack will reload the item displayed immediately prior to the current item.

fb.getIframeDocument( node )
fb.getIframeWindow( node )

These functions return an iframe's document object and window object respectively. Node is an optional parameter. If provided, it must be an iframe node. If node is not passed, fb.lastChild.fbContent is assumed and the document or window object for that top-most iframe is returned. Example: If three stacked boxes are open and you need to talk to the middle one, you can get its document with var doc = fb.getIframeDocument(fb.lastChild.parent.fbContent). Or, more simply, to get the document object for an iframe in the only running floatbox, var doc = fb.getIframeDocument( ).

Back to Index

Event Callbacks

Floatbox will look for callback functions that you define for the following events:
afterFBLoaded, beforeBoxStart, afterBoxStart, beforeItemStart, afterItemStart, beforeItemEnd, afterItemEnd, beforeBoxEnd, afterBoxEnd, beforePrint, afterPrint.

Javascript code is assigned to options of those names in the standard options setting manner of putting them 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 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. Be careful when using an eval'd string as a before* callback because the return value will be the value of the last statement executed. So an eval'd callback function of "abc = 42; xyz = false;" can cancel a floatbox action whereas "xyz = false; abc = 42;" will not. It's cleanest and safest if your eval'd statement is a simple call to a proper javascript function defined elsewhere on the page.

The afterFBLoaded callback is a handy place to put code to run at page startup. When that callback fires, both the DOM and the Floatbox code with its callable library functions have loaded, but window.onload has most likely not yet fired. Use afterFBLoaded as your DOMContentLoaded hook.

Example - A function callback in the page options: function myFunc() {
  alert( 'eat a peach' );
  return true;
}
fbPageOptions = {
  beforeBoxStart: myFunc
};

And a string callback in an anchor's rev options: <a href="xyz.php" class="floatbox" rev="afterItemEnd:`myFunc();`">talk about fruit</a>
(Don't forget the back-quotes. They're required for correct parsing.)

Hint: the loadPageOnClose option is an easy way to navigate to a new page when the floatbox closes. It's described in the instructions and the options reference.

Back to Index

Library Functions

In addition to the floatbox functions described above, the fb object exposes a number of useful generic functions that allow you to use floatbox as a small javascript library. These library functions are used internally by floatbox, but are not things you would call to do floatboxy things with. You would use these functions as a convenience in your own code for your own purposes. It is important to note that the fb object does not exist until your page's document is loaded. To use the library functions at page startup, attach your startup code to the 'afterFBLoaded' callback event in fbPageOptions.

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

fb.getElementsByClassName( className, node )

Returns an array of elements within 'node' that have a class name of 'className'. The 'node' parameter is optional and will default to document.body if not given.

fb.getStyle( node, property )

Returns the cascaded or computed (currently active) style for a given element. The 'property' parameter is any css property. You can use either the css or camelCase property syntax (i.e., 'font-size' or 'fontSize'). For example, var size = fb.getStyle('someId', 'font-size')

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

Use these two functions to attach or remove an event handler to a node. These are wrapper functions for the browser-specific functions addEventListener, attachEvent, removeEventListener and detachEvent. The 'action' parameter is the event you want to target and does not include the 'on' prefix used by IE (e.g., use 'load' and not 'onload'). Example:
fb.addEvent( 'someId', 'click', function() { alert('Hey! You clicked me!'); } )

fb.stopEvent( ev )

fb.stopEvent is a cross-browser way to stop normal execution (bubbling, propagation) of an event. Pass the event you want to block as the only parameter. The return value is the boolean false which 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 would look like this:
function(e) { alert('Hey! You clicked me!'); return fb.stopEvent(e); } )

fb.getScroll( )

Returns the browser's current scroll-bar positions in pixels. Return value is an associative array with named values of 'left' and 'top'.
Example usage: var scroll = fb.getScroll( );
alert('horizontal scroll is ' + scroll.left + ' pixels');
alert('vertical scroll is ' + scroll.top + ' pixels');

fb.getDisplayWidth( )
fb.getDisplayHeight( )

Returns the current browser screen width or height in pixels.

fb.getDisplaySize( )

fb.getDisplaySize combines getDisplayWidth and getDisplayHeight into a single call with return value of an associative array containing the two named values 'width' and 'height'.
Example usage: var displaySize = fb.getDisplaySize( );
alert('browser screen is ' + displaySize.width + ' wide and ' + displaySize.height + ' high' );

fb.preload( src )

You can borrow floatbox's image preloader if you like. Pass fb.preload the source path for the image to preload as a string.

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 decode &apos; to a single quote and decodes numbered entities like &#222; to their character equivalents.

fb.getOuterHTML( node )

Not all browsers support the outerHTML property. 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. If direct assignment of innerHTML works, it is used (it's a lot quicker). If setting of innerHTML is rejected, DOM insertion methods are used.

fb$( id )

The fb$ function is short-hand for 'document.getElementById', with minor extensions. 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 an element, that element will be returned. Note that the function name is fb$, NOT fb.$ with a dot.

fb.ajax( { url: strURL, updateNode: node, callback: function(xhr), postData: strParams, cache: boolean, headers: {name:value[, name:value]} } )

The fb.ajax function is an XMLHttpRequest object wrapper which provides AJAX functionality for dynamic gets and posts using a single line of script.

fb.ajax always issues asynchronous requests. If you call fb.ajax more than once in rapid succession, requests will be queued and will be sent out as soon as the preceeding request completes.

Here's an example which updates the contents of a div called "contents" and puts the time of the update into a span element using floatbox's ajax support:
<script type="text/javascript">
  // this is the callback function that will be used to add the update time to the page
  function updateTime(xhr) {
    fb.setInnerHTML('time', (new Date()).toTimeString());
  }
  // this is the onclick action that will fire the ajax request
  function click() {
    fb.ajax({ url: 'ajax.php', updateNode: 'contents', callback: updateTime });
  }
</script>

<input type="button" onclick="click();" value="get ajax" />

<div id="contents"></div>
last update at: <span id="time"></span>

Back to Index