Floatbox v6.0 - Instructions

floatboxjs.com

Index

Quick-start

Floatbox is simple to install and use, even though it may appear at first glance to be complex due to its numerous options and capabilities. The following three steps are all you need to get floatbox content lit up on your pages.

  1. Install — Open the downloaded zip file and drag or copy the entire floatbox folder from that zip file to the root folder of your site, or push the whole floatbox folder and its contents up to your hosted site.
  2. Include — Add the following two lines to the <head> section of the pages where you want to use floatbox.
    <link rel="stylesheet" href="/floatbox/floatbox.css"/>
    <script src="/floatbox/floatbox.js"></script>
    (See "Help!!!" below if you are testing from a local file system and not from a web server.)
  3. Use — Create an anchor element with a class of "floatbox" and an href that points to your content. Something like:
    <a href="myPic.jpg" class="floatbox">click me</a>

That's it, you're done. But to get the most out of floatbox, avoid frustration and wasting time, and to use its more advanced features you really should read the rest of these instructions, the options reference, the programmer's API reference, the license terms, and also check out the demo page. These reference materials are in the docs folder of the downloaded zip file and also online on the floatboxjs.com site. The online reference materials always pertain to the latest floatbox version.

"Help!!! Quick-start didn't work for me!! My content just opens on its own page in the browser, and not in a floatbox!"

If you find yourself saying that, it's 99% likely that the problem lies in the path used to reference the floatbox.css and floatbox.js files. Perhaps the floatbox folder is not really at the root of the site, but has instead been placed in a sub-folder one level up from the root. If the floatbox folder is in a sub-folder, that sub-folder name will need to be included in the path references.

Whatever the particular circumstances of your test server, the paths to the floatbox files must be valid in the context of that test server. Almost all cases of "it just does not work" result from a mismatch between the include lines for the floatbox files and their actual location on the site.

Special challenges arise with path names when developing on a local file system instead of a proper web server platform. (DreamWeaver typically uses the local file system.) The best approach on a local file system seems to be to use all relative paths, and not absolute paths. The downside of relative paths is that references to the same resource will be different depending on how deep in the folder structure the referring page lies. Relative floatbox include lines might look like this:

<link rel="stylesheet" href="floatbox/floatbox.css"/>
<script src="floatbox/floatbox.js"></script>
Notice the absence of the leading "/" character on those paths.

Back to Index

Activating elements

Floatbox behaviour can be assigned to <a> and <area> elements. In this section we will refer to those two element types as links. To display the content referenced by a link's href attribute in a floatbox, assign a class name of 'floatbox' to the link.

The 'floatbox' class can be assigned directly to each link in its class attribute or can be inherited from the class attribute of a containing parent element. Typically, the parent element might be a <div> for anchor elements and might be the <map> element for a collection of area links, but any element type can be used. A link can be excluded from inheriting the floatbox class from a parent element by assigning a class name of 'nofloatbox' to that link.
Both of the following have the same effect...

<a class="floatbox" href="pic1.jpg">Wallace</a>
<a class="floatbox" href="pic2.jpg">Gromit</a>
<a href="credits.php">Credits</a>

...and...

<div class="floatbox">
  <a href="pic1.jpg">Wallace</a>
  <a href="pic2.jpg">Gromit</a>
  <a class="nofloatbox" href="credits.php">Credits</a>
<div>

Links that inherit the floatbox class from a parent element will also inherit any floatbox options set on that parent element. (Assigning floatbox options is covered in the 'Configuring options' section below.) Here's the above example with the addition of inheriting a couple of option settings along with the floatbox class:

<div class="floatbox" data-fb-options="group:1 colorTheme:silver boxRoundCorners:none">
  <a href="pic1.jpg">Wallace</a>
  <a href="pic2.jpg">Gromit</a>
  <a class="nofloatbox" href="credits.php">Credits</a>
<div>

Note that a class attribute can hold more than one class name by separating the names with spaces: class="myclass floatbox" is perfectly legal and effective in all browsers.

Links with floatbox class names get floatbox display behaviour assigned to them by the Floatbox library's internal activation routines. Activation will be automatically applied to the page elements at page load time. Any links that get dynamically added to the page after page load time must be explicitly activated using the javascript fb.activate() function as described below in the section titled "Dynamically loading Floatbox content via AJAX, script or UpdatePanel".

In addition to the core floatbox display, the Floatbox library includes capabilities to show cycling image sets, enhanced tooltips, context boxes, and popup thumbnails. These additional capabilities are also enabled by assigning class names to elements. Please see the relevant sections of these instructions for details.

Back to Index

Configuring options

Floatbox options are used to set appearance preferences, size the floatbox, group items into sets, assign captions, etc. There are 3 different ways to set configuration options for floatbox. In order of precedence, options can be set from:

  1. data-fb-options or rev attribute settings placed directly on an anchor (link), or inherited from a containing 'floatbox' classed element (see 'Activating elements' above). These apply only to the item(s) they are assigned to.
  2. fbPageOptions, fbTypeOptions & fbClassOptions javascript objects (associative arrays) defined on the host page. These settings apply to all floatboxed anchors on the page.
  3. globalOptions set in the floatbox/options.js file apply to floatboxed items across the entire site.

If you have a number of different floatboxed items on your site, it's a good idea to organize your option preferences based on the scope you want those options applied to. For example, a specific anchor pointing to HTML content may have a 'width' option set directly on it, while setting 'boxCornerRadius' for all image content would best be done in the typeOptions section of the globally applied floatbox/options.js file.

Enhanced tooltips and context boxes are really just instances of the standard floatbox. As such, they will accept almost all the options that apply to floatboxes, and will respond to those option settings with the same results. Starting with version 5.4.0, tooltips and context boxes can have options assigned through class names set on the host element and corresponding class options defined in fbClassOptions or the classOptions section of options.js, as described below.

Details of the various option-setting methods follow. Don't overlook reading the options reference. You'll get the best understanding of the numerous other floatbox options from there. (Note that option names and values are case-sensitive.)

Back to Index

Setting options directly on anchors

Options for a particular anchor get set in that anchor's data-fb-options or rev attribute, or are inherited from options set on a containing div. (Be sure to read the "Activating elements" section of these instructions.)

The general syntax for setting options is:

<a href="xyz" data-fb-options="option1:value1 option2:value2 etc...">

Using the rev attribute is equivalent. ('data-fb-options' validates on HTML5 and 'rev' validates on earlier doctypes.) All the documentation samples and the demo page use the data-fb-options attribute, but there is no problem if you have a preference for placing options on the rev attribute instead. rev="option1:value1 option2:value2 etc..."

When running a series of floatboxed items such as a gallery set or a slideshow, many of the options from the clicked anchor will apply globally to all items in the set. Some other options apply on a per item basis. It should usually be apparent from context which options are per item. For example, caption and contentBackgroundColor are per item whereas boxCornerRadius and colorTheme apply to the whole set.

There's lots of examples of options set on anchors over at the demo page. One example that some people might find useful in its own right, and that should give a good sense of how options can be used, is the following anchor which will start a slideshow:

<a href="" class="floatbox" data-fb-options="doSlideshow:true group:myShow showThis:false afterSlideshow:exit navType:none">Slideshow</a>

Here we are telling floatbox to start a slideshow, to use the gallery set that is defined with the group string 'myShow', that the current anchor should not be part of that slideshow set, images should be scaled down to fit the screen, and no navigation controls should be shown in the floatbox. (Not all the assigned options in this example are required to get the slideshow functionality, and if you're copying this example for use on your own pages you will no doubt remove some options, maybe add some others, and set things to the way you want them to be.)

The option string syntax is quite flexible. Name:value pairs can be separated by spaces, semi-colons, commas or ampersands. The delimiter between a name and its value can be a colon or an equals sign. Pixel values can be given with or without the 'px' suffix.
"colorTheme:red width:200", "colorTheme:red; width:200px;", "colorTheme:red, width:200" and "colorTheme=red&width=200" are all allowed and equivalent.

Note that options assigned directly on anchors, or as parameters to the fb.start API function, override or replace the same options assigned by the more global methods described below. To cancel an inherited option without setting a value for it, assign 'null' to the option.

Back to Index

Setting page-specific options

The majority of floatbox's options are not item-specific and can be defined per page or globally rather than repeated on each anchor. Use fbPageOptions to assign option settings to all items on a page, fbTypeOptions for settings to be applied to items of a particular type, and fbClassOptions for settings applied to all items on a page that have a particular class name assigned to them. Each of these sets of options are defined by a javascript object placed in the primary page's <head> or <body> section. (They will have no effect if placed on a framed child page, either in an active floatbox or as an iframe element on the main page.)

fbPageOptions
This example sets a shadow type, animation values and navigation type for all floatbox items on a single page:

<script>
  fbPageOptions = {
    shadowType: 'halo',
    resizeTime: 0.6,
    transitionTime: 0.6,
    overlayFadeTime: 0.2,
    navType: 'both'
  };
</script>

Note the syntax: there are commas after each name:value pair except for the last one. A comma after the last one will break IE.
A standard Floatbox options string can also be used as an alternate syntax for defining fbPageOptions. E.g.:

<script>
  fbPageOptions = 'shadowType:halo resizeTime:0.6';
</script>

The configurator (described below) can be used to assist in building fbPageOptions.

Use fbTypeOptions and fbClassOptions to assign settings based on content type or class name. The syntax for these two is a bit different from that for fbPageOptions. Each type or class is assigned a string of name:value pairs in the same format used for an anchor's data-fb-options attribute.

For example, to assign settings to items with a class of 'redThings' and other settings to 'class49':

<script>
  fbClassOptions = {
    redThings: 'colorTheme:red width:444 height:333 contentScroll:false',
    class49: 'contentCornerRadius:8 enableDragMove:true showItemNumber:false'
  };
</script>

And, to set options based on content type:

<script>
  fbTypeOptions = {
    iframe: 'modal:false showNewWindow:true',
    flash: 'width:480 height:385 enableDragResize:true'
  };
</script>

Valid content types are 'image', 'html', 'media', any of the html sub-types 'iframe', 'inline', 'ajax' & 'direct', any of the media sub-types 'video', 'flash', 'quicktime', 'wmp', 'silverlight' & 'pdf', and also 'tooltip' and 'context', although these last two aren't really content types.

When running floatbox in a hierarchy of iframed pages, these page-specific option objects need to be placed on the top (base) document. The settings will apply to content within iframes on the page provided those iframes are sourced from the same domain.

Back to Index

Setting site-wide options

Global option preferences apply to all pages on your site and are defined in the options.js file located directly in the floatbox install folder. In previous Floatbox versions, global options were set by editing the floatbox.js file. This has moved to options.js specifically so that the options settings can be easily imported into subsequent versions after performing a version upgrade.

There are four sections to the options.js file, corresponding to the four places you can place page-specific options as described above. The globalOptions section should be self-explanatory: settings here apply globally across your site. typeOptions assigns settings across the site, but only to items of the assigned floatbox type. See fbTypeOptions above for syntax and a list of available floatbox types. classOptions is similar to typeOptions but assigns settings site-wide to items with a matching class name.

The globalOptions section of options.js also holds the floatbox license key. (See the license key section of these instructions for details.) It is a straight-forward matter to edit options.js with any text editor. You can also use the configurator described below to assist in creating the globalOptions section of options.js.

Back to Index

Using the Configurator to setup global and page-specific options

The Floatbox package includes a Configurator page that can be used to generate the globalOptions section of options.js or an fbPageOptions object definition by selecting option settings from a form. This can be quicker and less error-prone than manually typing up your preferences directly. The Configurator cannot write to a file system. It presents the globalOptions or fbPageOptions code for you to copy and paste into the floatbox/options.js file or into your individual pages. You can of course use a combination of the configurator and editing your options directly with a text editor - whatever works.

Open configurator.html in your floatbox install folder with any browser. Select your option preferences on the form and click one of the buttons to generate your globalOptions or fbPageOptions code. The object definition shown will be only those settings that differ from the floatbox built-in defaults.

Back to Index

License key

The downloaded floatbox package is for evaluation, development and testing and does not have a license key bundled with it. Without a valid license key, floatbox will periodically show a registration reminder. You can acquire a license key from the Floatbox registration page. When you have acquired and installed a license key matched to your production site's domain, you will be legally entitled to deploy the floatbox software to that site and the registration reminders will not occur. You do not need a license key for development or evalution work. The floatbox package is complete and fully functional without a license key.

Install a license key by placing it in the floatbox/options.js file. The location for the licenseKey in options.js looks like this:

globalOptions: {
  licenseKey: "",

The key goes between the quotes.
The options.js file can be edited directly or the configurator.html form can be used to assist.

The license key can also be set directly on a page with the "fbPageOptions" javascript object (see the "Setting page-specific options" section of these instructions). A bare-bones fbPageOptions definition with a licenseKey looks like this:

<script>
fbPageOptions = {
  licenseKey: 'abcd1234'
};
</script>

The configurator can help build fbPageOptions as well as the globalOptions in options.js.

If upgrading from a very old version of floatbox that used licenseKey.js, you will need to copy the license key from that old file into options.js as described above.

The license key can be tested by loading a page that is using Floatbox and then running javascript:fb.key() from the address bar of any browser except Firefox.

License keys are matched to the domain name that the registered site is running under. All checking that the key is valid on that domain is done by the Floatbox code entirely within the browser. There is no check made to a registration db anywhere and no 'phoning-home' of any kind.

As of Floatbox version 5.3.0, the licenseKey field can accept multiple license keys separated by a space or comma. This can be useful if you are serving the Floatbox files to multiple registered sites from a central server, publishing to multiple sites from a standardized content base, or if two or more domain names resolve to the same web site.
For versions prior to 5.3.0, these same multi-site or multi-domain scenarios can be satisfied by using a multi-domain "master" key that can be obtained either from the license key management page (for purchasers of multi-pak registrations) or by request using the contact form on the the Floatbox site.

If you wish to test or develop offline using 'localhost', an ip address, or a local file system and avoid the distraction of the registration reminders, feel free to use the following license key:
ExfZEBCcExvo
If using this offline key, don't forget to obtain a real key for your production site before going live.

Back to Index

Upgrading

When upgrading to a newer version of Floatbox, consider the browser cache implications for your site visitors. It's a good idea to rename the floatbox and add a version or some other unique segment to it. For example, version 6.0.1 of Floatbox could be located in a folder named /includes/floatbox_601/. By changing the folder name at each install you can guarantee that the visitors won't run into trouble by mixing different version files from their cache and from the site. You will of course have to take the trouble to change the paths on the script and link elements that load floatbox.js and floatbox.css.

If upgrading a minor version release but within the same major version family, just drop the new files in place and move your previous options.js file into the new folder if there's any settings (or license key) in there that you want to retain. When upgrading to a new major version, manually edit the new options.js file with your preferred settings. There may also be option and API changes between major versions that might require changes to the floatbox markup on your pages. Check the changelog entry for the 1st release of the new major version and see if any of the interface changes described there will affect you.

Back to Index

Doc Types

Floatbox does not support quirks mode. All pages that include floatbox content need to have a valid doctype declaration at the top of the page which will set the browser to render in standards-compliant mode. If you don't know what doctype to use, the simple HTML5 doctype declaration <!DOCTYPE html> is an excellent choice. Note that for Internet Explorer, if anything at all appears above the doctype declaration, quirks mode will be set. So please don't put an html comment or an xml declaration such as <xml version="1.0" encoding="utf-8"?> at the top of your pages.

Back to Index

File & content types

Floatbox determines what kind of content is being requested based on the file extension from an anchor's href attribute. Sometimes you may need to over-ride that detection and specify a content type directly. Content type over-ride is always required when loading AJAX, and can also be needed when you have a .php or .aspx page serving images.

By default, .php and .aspx urls will be loaded as iframes. To make them load as images, set "type:image" on the anchor's data-fb-options attribute. If you're fetching AJAX content, you need a "type:ajax" over-ride in the options.

Example:
<a href="getPix.php?pic=29" class="floatbox" data-fb-options="type:image">...</a>

Back to Index

Images: galleries and slideshows

Floatbox's default behaviour for showing images is to open a single image by itself. A gallery set can be created by assiging an identical 'group' option to two or more anchors that reference image files. Grouping image references adds navigation to the floatbox that lets the viewer move through the grouped set using 'previous' and 'next' navigation buttons, keyboard arrow keys, and/or index links. (Index links are described below in these instructions.) An 'item number' display also becomes available that will show 'image x of y' in the floatbox's frame area. See the 'Galleries' section of the Options Reference for option settings that control gallery set behaviours.

A gallery set can be shown as a slideshow by setting the 'doSlideshow' option to true. This will cause the gallery set to auto-advance through the images on an interval set by the 'slideInterval' option. See the 'Slideshows' section of the Options Reference for more options that control slideshow behaviour.

The easiest way to setup a gallery set is to take advantage of Floatbox's ability to propagate the 'floatbox' class and option settings from a containing div to the anchor elements in that div. Also note that anchors used to define gallery set members do not have to have clickable content such as a thumbnail image or text. The anchors can be empty. Here's an example:

<div class="floatbox" data-fb-options="group:1 doSlideshow:true">
  <a href="image1.jpg"><img src="thumb1.jpg"/></a>
  <a href="image2.jpg"></a>
  <a href="image3.jpg"></a>
</div>

Back to Index

HTML content: iFrames, AJAX, inline DIVs & direct

There are 4 ways to load HTML into a floatbox: as an iframe, using AJAX, using content from inline hidden DIVs, and using a direct HTML string as the content source. Standard anchor hrefs that aren't recognized as an image or multi-media type will be loaded as iframe content by default.

To load an HTML snippet using AJAX, set the anchor's href to reference the AJAX source URL and put "type:ajax" in the anchor's data-fb-options attribute. To load content from an inline div, give that div a unique id and reference that div's id in the anchor's href attribute preceeded by "#" (e.g., href="#myDiv"). A string of direct HTML can be used as the source parameter to the fb.start() API function. Direct HTML content must include at least one each of '<' and '>' to be recognized as HTML content. Floatbox's default content type is iframe content. Load a page as an iframe in a floatbox simply by setting the anchor's href to the source path of that page. If a URI that points to an iframe content source page includes a #hash id value, the iframe page will scroll to the element that has that id assigned when opened in a floatbox.
See below for examples.

There's lots of useful options that can be assigned to floatboxed HTML content. Please look through the options reference to get an idea of what's available. Good ones to be aware of are 'width', 'contentScroll', 'contentBackgroundColor', 'autoFit', 'showNewWindow', 'showPrint', and the '*Pos' positioning settings. It's also worthwhile to check out the 'Let floatbox set content height' section further down in these instructions.

Here's some examples of floatboxed anchors that load HTML content:
iframe: <a href="mypage.html" class="floatbox" data-fb-options="width:400 height:530 contentScroll:false">...</a>
ajax: <a href="myajaxpage.html" class="floatbox" data-fb-options="type:ajax width:400">...</a>
inline div: <a href="#divID" class="floatbox">...</a>

And one example of direct HTML in an API call:
fb.start( '<span>Eat a Peach</span>', 'width:150 showPrint:true' );

Back to Index

Video: HTML5 player, YouTube & Vimeo

HTML5 video player

Floatbox version 6 includes its own HTML5 player which provides a great way to deploy and view locally served video. To set up a locally served HTML5 video:

Most modern browsers will play the video. For older browsers that cannot, the Flash-based Flowplayer will be invoked and the .mp4 video will be shown with that. The player will be loaded from the flowplayer site. You can obtain your own copy of flowplayer and update the reference in floatbox/video.html to use it if you prefer.

There are three control parameters that can be passed to the video player through a query-string on the href's URI path.

example:

<a class="floatbox" href="/somePath/myVideo.mp4?autoend=0"
  data-fb-options="width:777 height:444 addPlayButton:true"
><img src="/somePath/myThumb.jpg"/></a>

YouTube & Vimeo

YouTube and Vimeo offer video embedding services as iframe content rather than traditional flash-based object/embed elements. This allows delivery of a format suitable for the platform being used - e.g., flash content for desktop browsers that have the plugin, HTML5 video for iPads/Phones and other Flash-free agents. When showing videos from these online services, Floatbox will use the iframe content format, and thus reap the benefits of its flexibility. Floatbox will also query the API services of these video providers and fetch information that can be used to auto-assign captions, determine default video dimensions, and get references to thumbnails that can be auto-inserted into links to the videos.

A quick way to understand Floatbox's video service capabilities, and to learn how to configure and use these capabilities, is to check out the "Video" tab on the demo page. Here are some pointers on setting up video:

Back to Index

Flash content

Floatbox provides smart handling of .swf content files using the browser's installed Flash plugin. If the plugin is not present, floatbox will display a notice (localized to the site visitor's language) with a link to the plugin download page.

Floatbox assigns the following parameter default values to Flash content: allowFullScreen=true, allowScriptAccess=always, loop=false, quality=autohigh, scale=exactfit, wmode=opaque. You can over-ride these, plus 'base', 'bgcolor', 'fullScreenAspectRatio', 'menu', 'play' and 'salign', by providing new values in the href url's querystring.
e.g., <a href="myflash.swf?wmode=direct&amp;bgcolor=#ffffff&amp;scale=default" class="floatbox" data-fb-options="width:320 height:240">...</a>

If your flash object requires flashvars to be set, you can put these flashvars in the href url's querystring. Flash always treats flashvars and querystring vars equivalently and it doesn't matter in which location the settings appear. The 'minFlashVersion' option, described in the Options Reference, can be used to set the version of the Flash plugin that must be present to show the content.

The object element used to show Flash content in a floatbox is assigned an id that is the filename (without extension) of the showing .swf file. For example, the id of the "tetka.swf" example on the Floatbox demo page is "tetka". This id can be used if script access to the object instance is required.

Back to Index

PDF & Scribd.com

PDF content is problematic. The way Floatbox handles .pdf references is to put them up in an iframe and let the browser sort it out as best it can. Many modern browsers will render the PDF document correctly but some require that a PDF Reader Plugin be installed which may not be present. The plugin might not be installed or may not function well. Some browsers will download rather than display PDF documents, and some of these don't even prompt before downloading.

When direct-loading PDF, numerous parameters can be specified as a query string following a hash character on the href path. The PDF sample on the "HTML" tab of the demo page shows the usage of parameters and opens a document that lists and describes the parameters that are available in most browsers.

A better alternative to direct-loading PDF documents is to either convert them to HTML or host the documents on scribd.com and load them from that online service. Floatbox includes some smarts about handling references to scribd documents and the scribd service itself uses a combination of Flash and HTML5 iframe embeds to make the docs viewable in almost all browsers, including mobile devices. See the scribd example on the "HTML" tab of the Floatbox demo page for details on how to setup the links and to test how the scribd viewer works from different platforms.

Back to Index

Let floatbox set content height

Floatbox can measure and set the dimensions for HTML content. It's a good idea to let floatbox do this, especially for height, so that the box dimensions will look correct in different browsers. Different browsers layout content slightly differently from each other, and the right box height in one browser can be too short or too tall in another.

The best approach for AJAX, same-domain iframe, inline and direct HTML is to constrain the content's width either by setting a floatbox width option or defining widths in the HTML styles, and then let Floatbox measure the height. When no height is specified for these HTML content types, the height will be measured and adjusted automatically. Not all content can be successfully measured, but most can. Scrollable and positioned elements in the content are the most likely to measure incorrectly. Also, content that uses a style of 'height:100%' may not measure successfully. Remove that style, set a specific height option for the item, or set the 'measureHTML' option to false for such content. Cross-domain iframe content cannot be measured by script; consequently, box height cannot be automatically matched to content height for cross-domain iframe content.

Back to Index

Cycling images and thumbnails

Floatbox includes a module for displaying a set of images or thumbnails that will fade and cycle through each image in succession. This can be an effective way to show dynamically changing images, setup a slideshow link or perhaps put a dynamic header at the top of a web page. See examples of this under the "Cyclers" tab on the demo page. The sample code under those demos are a good way to get started with your own cycle set.

The cycleInterval and cycleFadeTime options are used to control timings. cycleFadeTime controls how quickly the images fade in and out while cycleInterval sets the time between initiation of the fade to the next image. The cycleInterval includes cycleFadeTime, so if for example they are both set to 3 seconds, they will constantly be fading to the next image.

A cycler set can be configured to pause and resume on mouse click or touch gesture, and to optionally show a small play/pause control over the cycling images. Set "cycleEnableClick:true" to enable pause and resume on click, "cycleShowControls:false" to hide the controls, "cycleControlsPos:__" to place the controls at a particular location over the images, and "cycleStartPaused:true" to begin the cycler set in the paused state at page load time. There are also cyclePauseOnHover and cycleResumeOnHover settings which, if set to true, will either pause or start a cycler div when the mouse is hovered over it.

You can use CSS to style up the play/pause control if you're not satisfied with the default look. Assign the desired styles to ".fbCycler span.fbCyclerControl".

The set of images to be cycled goes inside a div with a class of "fbCycler" assigned to that div.
<div class="fbCycler" style="height:420px;">
It's best to assign a specific height to that div which fits the tallest image in the set, otherwise it might look a little odd as the div grows to accommodate new images that cycle in. The fbCycler div can also contain a 'data-fb-options' attribute to set specific option preferences for the cycle set.

The first image in the cycler set is just a normal image element and will be the only one shown if javascript is disabled: e.g., <img src="image1.jpg"/>

The other images in the fbCycler div are setup a little differently and will start off hidden by floatbox.css:
<img data-fb-src="image2.jpg"/>
Notice that we use the data-fb-src attribute to specify the path to the image file, instead of the normal src attribute. This is done to speed up page loading. If we assigned a src attribute to each of the hidden images, all the images in the set would be loaded at page start time. The floatbox code will move the data-fb-src values into the src attribute one at a time as the images are cycled in. (You can instead use the longdesc attribute for the alternate src reference if you like.) If you're concerned about the img elements with no src attribute failing validation, assign a tiny image like blank.gif as the initial src value.

Add a few more images and close the div and the basic cycle set is finished.

Captions can be added to individual images in the cyler set. These captions will be centered below the image. When the 'titleAsCaption' option is set to true, which it is by default, the caption can be specified in the img element's title attribute. Alternatively, we can set 'altAsCaption' to true and thereby pull the captions from the img element's alt attribute. If you don't want to use either the title or alt attribute for the captions, a caption can be assigned by bundling both the img element and a span element that holds the caption text together inside a div. Like this:
<div><img data-fb-src="image3.jpg"/><span>text for image3</span></div>

The cycling images can be thumbnails within anchor elements marked up for floatbox behaviour, giving a nicely integrated floatbox gallery that will open on thumbnail click. Such a set looks similar to the basic cycling image set described above but, instead of putting img elements in the containing div, we put anchors in and assign both a 'floatbox' and 'fbCycler' class to the div. Like this:

<div class="fbCycler floatbox" data-fb-options="group:cycle1" style="height:100px;">
  <a href="image1.jpg"><img src="thumb1.jpg"/></a>
  <a href="image2.jpg"><img data-fb-src="thumb2.jpg"/></a>
  etc...
</div>

Notice that the thumbnail img elements are using the "data-fb-src" trick to speed load time.

Again, caption text can be added to the cycling thumbnails or images by using the 'title' attribute, the 'alt' attribute, or by following the img element with a span element, as descibed above. Here's a couple of captions for the thumbnail cycler example:

<a href="image3.jpg">
  <img longdesc="thumb3.jpg" title="this is caption 3"/>
</a>
<a href="image4.jpg">
  <img longdesc="thumb3.jpg"/>
  <span>this is caption 4</span>
</a>

(The 'longdesc' parameter is equivalent to 'data-fb-src' and is valid HTML4.)

cycleFadeTime can be set only globally or per page; different cyclers on the same page cannot use different timings. The cycleInterval setting can be assigned globally, per page, in the fbCycler div options, or on a per-image basis giving different display times for different images in the set. Per-image cycleIntervals are assigned in an fb-data-options or rev attribute placed on the individual divs, anchors or images inside the fbCycler div. Here's an example with a default interval of 4.5 seconds for the cycler set and a different per-image interval for one set member:

<div class="fbCycler" data-fb-options="cycleInterval:4.5 altAsCaption:true" style="height:420px;">
  <img src="image99.jpg" data-fb-options="cycleInterval:10" alt="some dumb caption"/>
  etc...
</div>

Back to Index

Enhanced tooltips

Any element on a web page can have an enhanced tooltip associated with it by assigning the element a class of "fbTooltip". The tooltip shown on mouseover of such an element is a non-modal floatbox which can contain any content type and can by styled with all the standard floatbox options.

In addition to the fbTooltip class, the host element needs to have a 'data-fb-tooltip' attribute which provides information about the tooltip to be shown. The only mandatory entry in data-fb-tooltip is 'source', which points to the source content to be shown as the tooltip. Tooltip source content is typical HTML and can come from any of Floatbox's supported HTML content sources: a hidden div, an AJAX fetch, an external page loaded as an iframe, or an encoded string of HTML assigned directly to the 'source' option.

Tooltips will respond to most of the available Floatbox options that are described in the Options Reference. Additional options that apply only to tooltips are described in their own section in that reference as well. The tooltip-specific options are 'placement', 'attachToHost', 'moveWithMouse', 'showOnce', 'delay' and 'mouseSpeed'.

The tooltip options can be specified per element in the data-fb-tooltip attribute, per page by being assigned to to the 'fbTooltip' class in fbClassOptions, or site-wide by being assigned to the 'fbTooltip' class in options.js.

Here's an example showing a span element with an enhanced tooltip:

<span class="fbTooltip" data-fb-tooltip="source:#hiddenDivID moveWithMouse:true">Tooltip will appear when the mouse is hovered over this text.</span>

See the "Tooltips+" tab of the demo page for some live examples with markup shown.

An enhanced tooltip can be assigned to the content shown in a standard floatbox using the 'tooltip' option in the originating anchor's data-fb-options attribute. The value of the tooltip option is the source of the tooltip content. Optional settings for the tooltip can be provided in the 'tooltipOptions' setting.
An example:

<a href="image1.jpg" data-fb-options="tooltip:#myTooltipDivId tooltipOptions:`moveWithMouse:true contentBackgroundColor:#123456`">click me quick</a>

Back to Index

Context boxes

Context boxes are similar to the enhanced tooltips except they are triggered by a left or right mouse button click. They can form an effective replacement for a browser's built-in context menus, can consist of any HTML content, and will respond to mobile device touch gestures as well as mouse interaction.

Assign a context box to any element on a page by giving that element a class name of 'fbContext' and adding a 'data-fb-context' attribute that contains at least a 'source' reference. The context box's content can come from a source of any type, but an inline hidden div is probably the most common and convenient.
For example:

<img class="fbContext" data-fb-context="source:#context1" src="pic1.jpg"/>
(It doesn't have to be an img element. Any element type can host a context box.)

Context boxes will accept and respond to most standard floatbox options (including 'contentClickCloses'). Assign option preferences in the 'data-fb-context' attribute, or in the usual per-page or global manner. Options can be assigned to the 'fbContext' class in the classOptions section of options.js or in an fbClassOptions definition on the host page.

The only option that is specific to context boxes is 'contextMouseButton', which can be set to 'both' (the default), 'left', or 'right' and controls which buttons activate the context box. Please be aware that right-clicking is problematic in some browsers and it will not work everywhere. All versions of Opera prior to 10.5 will show the browser's native context menu over top of our context box, ignoring the instructions sent to it to not display that menu. Other browsers have an advanced configuration setting that individual users can set to either make their browser always show the context menu, just like old Opera, or to ignore right-click mouse actions altogether. Most browsers will respond correctly to a right-click on an fbContext element, but it is recommended that 'contextMouseButton' not be set to 'right' unless you have full control over the environment your pages will operate in. Leave left-clicking available for people who need it.

Examples are on the "Tooltips+" tab of the demo page.

Back to Index

Popup thumbnails

"Popup" thumbnails or images can be attached to an anchor element and will start off invisible, but show on mouse-over or a touch on the anchor content. There are 5 classes that can be assigned to an anchor to give its contained img element popup behaviour: "fbPopup", "fbPopdown", "fbPopleft", "fbPopright" and "fbPopcenter". These classes determine where, in relation to the host anchor, the popped up image will appear.

An 'fbPop*' anchor can also be a standard floatboxed anchor if both class names are assigned. E.g., class="fbPopright floatbox". The hidden thumbnail will appear on mouseover and a floatbox will start from that thumbnail when it, or the host anchor, is clicked. Without a class of "floatbox" assigned, the anchor will navigate to its href as normal when clicked. To have a popup anchor that neither opens a floatbox nor navigates when clicked, leave the 'floatbox' class off and set the href to href="javascript:void 0".

If there are two images in an 'fbPop*' anchor, the first one will get popup behaviour assigned while the second one will always show as normal. Having two thumbnail images can be combined with the 'fbPopcenter' assignment to create a nice expanding thumbnail effect. Make the first image in the anchor a larger version of the second image. On mouseover, the thumbnail will appear to expand to the larger size.

As you might guess, there's samples to be found in the 'Bonus1' section of the demo page.

Back to Index

Captions

The standard way to show a caption in the floatbox frame area is to set the 'caption' option in an anchor's data-fb-options (or rev) attribute. When doing this, the caption text usually needs to be wrapped in backquotes (`) so that the options string will be parsed correctly.

You can show two captions on the same item. To do so, assign the second caption to the 'caption2' option in the same manner as the first caption.

If the 'titleAsCaption' option is set to true (which it is by default) and a caption is not defined, the caption will be taken from the host anchor's title attribute or that of a thumbnail img element in the anchor. Be aware that browsers display an anchor's title as a tooltip when the user mouses over the anchor. If you don't want this tooltip to occur, set your caption using the caption option rather than placing it in a title attribute.

Here's two examples:

Floatbox captions can be built from, or contain, HTML elements. There's two ways to get HTML into your captions. The first is to put your caption's HTML inside a hidden div on the page and reference that div by id in the caption option. Like this:

<a href="image1.jpg" data-fb-options="caption:#myCaptionDiv">...</a>
...
<div id="myCaptionDiv" style="display:none;">
  <span style="color:#123456;">Here's an HTML caption with <a href="//example.com">a link</a></span>
</div>

The second way is to assign the HTML caption directly in data-fb-options. When assigned directly to the caption option all HTML entity characters (& " < >) will need to be encoded (&amp; &quot; &lt; &gt;) so that browsers can correctly parse the page. This can get messy and can be harder to get right than the hidden div approach. For example, the same caption assigned in the hidden div above looks like this when encoded and placed directly in the options:

<a href="image1.jpg" data-fb-options="caption:`&lt;span style=&quot;color:#123456;&quot;&gt;Here's an HTML caption with &lt;a href=&quot;//example.com&quot;&gt;a link&lt;/a&gt;&lt;/span&gt;
`">...</a>
(Didn't I say it could get messy?)

If you set your caption to the string "href", the displayed caption will be the value of the anchor's href attribute. This might be useful when displaying iframed content or if you want to display the path/filename of the current image.

Captions are normally assigned per-item in the data-fb-options attribute (or in fb.start's 'options' parameter). They can, however, be set anywhere that options can be assigned and can apply globally, per page, per type, or per class. Note that HTML placed directly into a caption defined in any of these locations does not need to be encoded. Encoding is only for text in the HTML that is going to be parsed by the browser to render the page.

Back to Index

Header and Footer

The header and footer areas are transparent divs immediately above and below the floatbox frame area. These can be used to display content attached to, but outside of the box, such as alternate captions or any HTML. One possible use is for branding of the floatbox display, or attaching a company logo. See a footer in action in the "lavish" example the "Options" tab of the demo page.

Header and footer can be assigned in exactly the same way as captions, described above - as direct text, encoded HTML, or a reference to a hidden div. The names of the options to set are 'header' and 'footer'. Pulling header and footer content from a hidden div is probably the most common and trouble-free approach. Here's an example:

<a href="somePage.html" data-fb-options="header:#myHeaderDiv">...</a>

Back to Index

Alternate Close button

The traditional Floatbox close button is displayed in the frame area as an 'english' or 'international' control (see the 'controlsType' option). An alternate close button is available but not shown by default. This close button is a round disc with an 'X' in it and is displayed at the top right or top left corner of the floatbox.

To enable this 'outerClose' button, set showOuterClose to true. Which corner it is displayed in is controlled by 'outerClosePos', which can be set to 'tr' or 'tl' and defaults to 'tr'. If you wish to always use the outerClose button and not the traditional close button, set both 'showClose:false' and 'showOuterClose:true' in options.js.

Back to Index

Built-in class options

classOptions are a great way to define a re-usable set of options to be assigned to multiple floatboxed links. There are four pre-defined classOptions defined in the options.js file which can be used to easily assign alternate appearance to a floatbox.

Use these pre-defined class options by assigning the class name to the floatboxed link they should apply to or to a containing element that has the floatbox class on it. The class names can also be passed into an API fb.start call by assigning them to the 'className' option in fb.start's second options parameter.
E.g., <a class="naked floatbox" href=... or fb.start( 'somePage.html', 'className:alt' )

Of course, the classOptions as presented in the options.js file can be tweaked and modified or used as the starting point for another set of classOptions.

Back to Index

Info box for secondary content

There are occasions when it is helpful to display additional information about your floatbox content. For photogrpahs, this might be descriptive text, EXIF information or a popup location map. Forms or other HTML content may have associated help or other information that can be effectively presented in a second floatbox. Floatbox's info box capability addresses this usage. When enabled, a link will appear in the lower left of the floatbox frame which activates the information box.

There are four options you can set in your anchor's data-fb-options attribute to enable and configure the info box.
1) Assign the url that points to the information source using the option "info". E.g., info:myInfoPage.html or info:#myInfoDiv
2) Set floatbox options for the secondary info box using the option "infoOptions". E.g., infoOptions:`colorTheme:white width:400 height:300` (The backquotes are required to enable correct parsing.)
3) By default the link in the floatbox frame will display the text "Info..." or its localized language equivalent. You can override this with the "infoText" option. E.g., infoText:`EXIF data...`
4) Use infoLinkPos to position the info link within floatbox border area. E.g., infoLinkPos:bl

An anchor with an associated info box could look like this:
<a href="myPhoto.jpg" class="floatbox" data-fb-options="info:#myInfoDiv infoOptions:`colorTheme:white width:400 height:300`">click here</a>

Yes, there's an example or two on the demo page (in the 'Bonus' section).

Back to Index

Print contents

If you set "showPrint:true" in a floatboxed anchor's data-fb-options attribute, a "Print..." link will be shown in the floatbox border area. When clicked, this link will invoke a second browser instance that will display just the contents of the floatbox window and will show the print dialog for this new browser instance. The contents that will be printed will be just that from the floatbox display, not the surrounding eye candy and not the host page content. Use the printLinkPos option to control where in the floatbox border the "Print..." link will appear. Use the 'printText' option to change the displayed "Print..." link to any other desired text.

In some circumstances you may find that you want to add css styling to the print window contents. You can do this with the printCSS option. If printCSS is a URL path to a css file, that css file will be attached to the print window. Or, you can just put css assignments directly into this option, surrounded by backquotes. For example: data-fb-options="showPrint:true printCSS:/css/print.css" or data-fb-options="showPrint:true printCSS:`p {font-size: 11px;} etc...`" You often don't need to add any css stuff for printing, but it's there if you need it.

The print link will not appear for Mobile Safari devices (iphones etc.) because handheld devices don't have printers.
Also, printing is not available for iframe content that comes from a different domain than the base page (cross-site script blocking). If you are displaying a cross-domain iframe in floatbox, the "Print..." option will not be displayed.

As usual, see the demo page ('Bonus' section) for an example.

Back to Index

Open in a new window

You may have occasion to offer your site visitors a way to open the current floatbox content into its own new window. Do this by setting 'showNewWindow' to true in an anchor's option string (rev or data-fb-options attribute). This will place a link in the floatbox frame that can be clicked to open the new window.

The string displayed in the new window link is localized in the language files and will be shown in the site visitor's native browser language. If the option 'showNewWindowIcon' is set to true (its default setting), a small new-window icon will be shown alongside the text link. The option 'closeOnNewWindow' (false by default) will cause the current floatbox to end when the new-window link is clicked.

Index links in a gallery set

Galleries of multiple images (or other content) can have a series of simple numbered links shown in the floatbox border area. If there are thumbnails associated with linked images, these thumbnails will be displayed as small popups when the numbered link is hovered with the mouse.

Primary control over the display of index links is done with the numIndexLinks option. If this is zero, index links will not be shown. If it is -1, there is no limit on the number of index links shown - there will be a link for each image in the gallery group. Any positive integer and the number of links shown will be limited to this amount (in case you don't want a huge list of numbered links for your gallery of 479 pictures).

Five other options affect index links.
Setting showIndexThumbs to false turns off the thumbnail popups within the index links.
The pipIndexThumbs default setting of true shows the index thumbs overtop of the current floatbox content image as a 'picture-in-picture' popup in the closest corner. If pipIndexThumbs is set to false, the index thumbs will appear immediately above or below the corresponding index link.
You can use maxIndexThumbSize to scale down large thumbnail popups in the index links so that their largest side does not exceed the given given size.
A thumbnail image other than the thumbnail in the anchor on the main page can be used by setting indexThumbSource in an item's options, or indexThumbSource can be set to 'href' to use the host anchor's linked image.
And you can control the location of the index links with the indexPos option. (See the "Layout" section of these instructions for details.)

You can see index links in action on the "Include Index Links" sample on the demo page.

Back to Index

Navigation and controls

Floatbox includes controls for moving to previous and next items in a group, resizing, playing and pausing a slideshow, and exiting. These controls are graphical and loaded from the graphics folder. If the configuration setting "controlsType" is set to the default "auto", browsers that are configured with a localized language other than English will see graphics-only controls. Localized English browsers will see control graphics that include English words.

There are two sets of previous/next controls for grouped items. "Overlay" navigation displays a small graphics on top of the displayed image when the mouse is over the left or right side of the image. "Button" navigation displays a clickable << prev || next >> (or the international equivalent) in the box frame outside of the content. You can use either or both of these by setting the navType option. My favourite setting is to set navType to "both" and set showNavOverlay to "never". This allows navigation to occur by clicking on the image (or on the button nav control) but does not display the popup graphic over top of the image.

When the floatbox content has been shrunk from its native size to fit the screen, or when it is displayed larger than the current screen size, a resize control will be displayed which can be used to toggle the item's size. The "resizeTool" option controls whether the resize control will be a custom maginfying-glass cursor or a small graphic in the top left corner. If the custom cursor is used and overlay navigation is enabled, click-resizing is active only in the space between the two upper navigation areas. (Opera always gets the graphic in the top left corner because it can't do custom cursors.)

When enableKeyboardNav is set to true, the following keys can be used in place of mouse-clicking the controls:

If the Ctrl key is used together with the left or right arrow, floatbox will jump 5 items ahead or back in the sequence. This is to facilitate quick navigation when using floatbox as a poor-man's PowerPoint.

Back to Index

Layout

There are many things that can appear inside the floatbox frame area: the two captions, an info link, print link, new-window link, item number for gallery sets, index links and the close button and navigation controls. You can control the positioning of these items with the *pos options: captionPos, caption2Pos, infoLinkPos, printLinkPos, newWindowLinkPos, itemNumberPos, indexPos and controlsPos.

The available positions are 'tl', 'tc', 'tr', 'bl', 'bc', and 'br' corresponding to top-left, top-center, bottom-left, etc. You cannot fill all 6 positions. You can use only two positions at the top and two at the bottom. So for example, if you have something assigned to the bottom-left, you can place something else either at bottom-center or bottom-right, but not both. If you make a positioning request that cannot be filled, the frame items will be moved to other locations in the frame.

The close button and navigation controls cannot be assigned to a center position (tc or bc), but you can set the centerNav option to true to move the navigation controls to the center of the frame while leaving the close button off to the side.

Back to Index

Appearance and Colors

There's lots of control over Floatbox's appearance. Many of Floatbox's options are for configuring appearance. You can set the colors, round corners, border sizes, display of controls, shadow effect, transparencies and various animation effects through the configuration options. See the options reference for details on the use of these (and other) options. It's a good idea to play with the "Set Options" form on the demo page to try out the different option settings that are available.

Floatbox has 6 pre-configured color themes: white, black, blue, red, yellow and custom. When no colorTheme option is specified, Floatbox defaults to black for images, white for HTML content, and blue for multi-media. The 'colorTheme' option can be set globally, per page, or per item to override these per-type defaults. Note that if you use the 'custom' colorTheme, you must explicitly load custom.css in an include line on your pages immediately below the include line for floatbox.css.

The 'contentBackgroundColor' option sets the background color inside the floatbox content area and is useful if the displayed content has transparent areas.

Colors of various Floatbox components can be specified directly using color options. In addition to colorTheme and contentBackgroundColor, the following are available: boxColor, overlayColor, innerBorderColor, outerBorderColor, textColor and strongTextColor. These should be fairly self-explanatory from their names, but it is worth noting that 'textColor' applies to the 'item x of y' display, index links, and the 'open in a new window' link, while strongTextColor applies to captions, info and print links, and the new window link when it's hovered. The strongControls option sets the control's (close, prev/next, etc.) background images to their 'on' or hovered state which may help match them against a custom boxColor or textColor settings.

The floatbox frame area can be shown with a color gradient effect by assigning two css colors, separated by '|', to to the boxColor option. For example: boxColor:#123456|#edca98

Setting customized colors through options is best done by assigning the options to a class defined in fbClassOptions or the global classOptions in options.js and then placing that class name on the floatboxed links. See the Instruction sections on setting page-specific and site-wide options for details.

The 'custom' colorTheme setting is for creating and using your own customized color scheme and/or control images via css. The settings are well documented with comments in custom.css and if you know a bit about setting css rules it will be fairly easy to make the desired appearance modifications. The control widget backgrounds such as for the close or prev/next buttons can be replaced with custom background images. If you do this, be sure to change the various control widths and heights in the css as described in the comments.

Back to Index

Custom background image

You can use a graphic as an overlay background image by providing a background-image style for the overlay element. In a css file, it would look something like this:

#fbOverlay {
    background-image: url(bkgrnd.gif);
}

The background-image setting can be placed in an external css file together with the appropriate include in the head section of your page, or it can be placed directly inside a <style> element in the page head. Of course, background-image can also be added to floatbox.css if you want it universally applied, but this will prove to be a pain when you upgrade to a new version.

When a custom background image is used, you may want to also set overlayOpacity to 100, or maybe play with lower values to fade the background. For an example of a custom background and the use of autoStart and loadPageOnClose, check out the APOD slideshow on the demo page.

Back to Index

Language localization

Floatbox includes language localization files for 35 languages. The strings in these files are used as tool tip hints for the floatbox controls, the "image x of y" display, the text displayed on "Info.." and "Print..." links, and the strings shown when a required multimedia plugin is not present. The correct language file will be selected for use based on the localization settings or your site visitor's browsers. You can set floatbox to always use one particular language file by setting the "language" option. But it is recommended that you not do this. By leaving language as "auto", your visitors will get the correct language for themselves.

There are two sets of graphics used for the floatbox controls. One set has English text on the controls ("Close", "Next", etc.), while the other set is purely graphical. In the default setting, the English controls will be served to people with English-localized browsers and all other users will get the non-graphical, international controls. You can use international controls for everybody, including English speaking folk, by setting controlsType to "international".

Back to Index

Auto-start and exit tasks

You can have floatbox content appear directly on page load by using the autoStart option. Put "autoStart:true" into the data-fb-options attribute of the floatbox-enabled item that you want to run automatically. As soon as the page loads, floatbox will start with this item displayed. You can use "autoStart:once" to have that tagged item display only on the first page load of the session. Doing this sets a session cookie when the item is first shown and that item will not be auto-shown again as long as that session cookie is present.

You can also invoke an auto-start through a query string on the url used to invoke the page. For example, a url of "//example.com/mypage.html?autoStart=myimage.jpg" will auto-start myimage.jpg provided there is an anchor on the page that is setup for floatbox and that has that image as its href value. Note that the query string value only has to match the right-hand side of the anchor's href. The given example would match an href of "/images/this_is_myimage.jpg".

Floatbox can automatically load or reload a web page in the browser when it exits. The "loadPageOnClose" option is used to make this happen. Set loadPageOnClose to the string 'self' to refresh the host page on exit. This can be useful if your floatboxed content has modified some back-end content and the host page needs to be refreshed to reflect the changes. If you set loadPageOnClose to the string 'back', the previous page in the browser's history list will be loaded. This is used in the APOD slideshow on the demo page. If loadPageOnClose is neither 'self' nor 'back', it is assumed to be a valid url and the browser will be instructed to load that page. If you set loadPageOnClose to a url inside an option string, you will likely need to surround the url with backquotes (`) so as not to break parsing of the option string.

You can set loadPageOnClose in the usual option setting way (fbPageOptions or the data-fb-options attribute), but you can also set it dynamically with javascript. For example, your script could say fb.loadPageOnClose = 'somePage.html'; (or parent.fb.loadPageOnClose if you're running from a floatboxed iframe page that does not have the floatbox files included on it).

When closing floatbox by calling the API end function, the equivalent to loadPageOnClose can be passed directly as an argument to that function like this: fb.end( 'somePage.html' ).

Be sure to see the API reference for information about the Floatbox callbacks that are available to run custom code on such events as floatbox or item start and end.

Back to Index

Image map areas

Floatbox can work with image map areas the same way it does for standard <a> elements. To do this, set up the class and options attributes as described above, but for image maps these attributes go on the map's <area> elements. There's an example in the 'Bonus' section of the demo page.

In addition to working with image maps on the main page, an image map can be assigned to an image shown in a floatbox. The assigned map will scale with the image if it is resized for any reason. See the 'useMap' entry in the Options Reference for info on how to set this up.

Back to Index

Running in framesets and iframes

Floatbox's standard mode of operation is for the visual components (the shaded page overlay and the floatbox itself) to occupy the entire page area and to fill the browser window. As an alternative, a floatbox can be constrained to display only within the confines of an iframe or a frameset's child frame by using Floatbox's 'framed' mode.

In the case of a frameset document, Floatbox must be constrained to a child frame and cannot appear over top of the whole page. This is because the frameset document itself is incapable of displaying any content directly. A frameset document can contain only child frame documents and it is only these child frames that can show content.

There are two ways to force Floatbox into 'framed' mode:

Note that Floatbox running in a cross-domain frame or iframe (that is, a frame that originates from a different domain than its parent page) will always operate in 'framed' mode regardless of whether the 'framed' option is set or not. Cross-domain pages cannot communicate across domain boundaries and consequently Floatbox is unable to manipulate or display anything in the context of the top document from code running in a foreign-domain frame. In cross-domain contexts, Floatbox will always be constrained to the frame it is running in.

When using Floatbox on a page that has same-domain iframes which contain floatbox-enabled content, the floatbox.js and floatbox.css files need to be included in the root (top) page and on the child iframe page(s). For example, if you have a page with iframes nested two deep and floatbox content only in the deepest iframe, you need the floatbox files included in the deep iframe, the parent of that iframe, and the root document. This is how Floatbox is able to cover the entire top document when showing content originating from an iframe.

Back to Index

Accessible content (Section 508)

Floatbox provides two options, 'altContent' and 'attachTo', that can be used to provide accessible content for people with disabilities. These options designate alternate content for images and iframes and provide correct sequencing or placement of content opened in a floatbox. These capabilities allow floatboxed content to be correctly handled by screen readers, making the Floatbox content compatible with sites intended to meet US Section 508 requirements. This '508' compliance together with Floatbox's proper implementation of keyboard-based 'tab' browsing makes it the only such library that takes presentation of accessible content seriously. 'altContent' is described here and 'attachTo' in the section that follows.

Use 'altContent' to assign a text string of alternate content to specific floatbox items. When set on an image link or start call, the altContent text will be assigned to the 'alt' tag of the floatbox image element. This will be the text read by a screen reader in place of showing the image. When set for iframe content, the text will be assigned to the iframe's 'title' attribute and will also provide the text for a link to the iframe page in the iframe's alternate content.

For example - from a link on the page:
<a href="tulips.jpg" data-fb-options="altContent:`dozens of tulips in a field`">go</a>
results in a displayed img element of:
<img src="tulips.jpg" alt="dozens of tulips in a field"/>

Or, an iframe from an fb.start() call:
fb.start( 'lesson1.html', 'altContent:`tutorial on building accessible sites`' );
results in a displayed iframe element of:
<iframe src="lesson1.html" title="tutorial on building accessible sites"><a href="lesson1.html">tutorial on building accessible sites</a></iframe>
Notice how a link to the lesson1 page is provided for agents such as screen readers that can't display the iframe.

Use of 'attachTo' for correct content sequencing is described below.

Back to Index

Attach to a specific document element

Default behaviour for Floatbox is to attach itself to a page's body element as the last child of the body. The 'attachTo' option can be used to direct floatbox to append itself to a particular element other than the body. There are two reasons why you might want to do this. First, page content needs to appear in the correct sequence to be compatible with screen readers and compliant with US Section 508 accessibility requirements. Second, ASP.NET pages can contain only one form and so any form content presented in a floatbox needs to be attached inside this one form to function correctly.

Set attachTo to 'click' to have the floatbox attach in the document immediately following the clicked item that started the box. This is a good choice to meet accessibility requirements of correct content sequencing. The attachTo option can also be set to the id of an existing element (usually a div or a form) to have the floatbox appended to that element. This is how you would attach a floatbox to an ASP.NET form.

Using attachTo does not make the content appear inline with the host page content. It still appears as normal in the floatbox, but is logically placed at the requested location in the page's document tree. Note that when attaching floatboxed HTML content (other than an iframe) to a document element, the content may inherit some css settings from the parent element that would not be inherited had the floatbox attached directly to the body.

Back to Index

Dynamically loading floatbox content via AJAX, script or UpdatePanel

When floatbox first loads on a page, it runs its fb.activate function to inventory all the floatbox-enabled anchors and area maps on the page, and to add the required onclick action to those anchors. It also activates any cycler sets, enhanced tooltips, context boxes, and popup thumbnails defined in the content. If new content marked up for floatbox behaviour is dynamically added to a page after its initial load, fb.activate needs to be re-invoked to register that new content and assign the event handlers to the new elements.

Floatbox's built in fb.ajax() function will automatically run fb.activate against any new content brought in using that function. However, you may be using a non-Floatbox AJAX content insertion something like this:

if (xhReq.readyState == 4) {
  document.getElementById('myXhrDiv').innerHTML = xhReq.responseText;
}

Light up the floatbox anchors in that dynamic content by adding the following line after that insertion:

if (xhReq.readyState == 4) {
  document.getElementById('myXhrDiv').innerHTML = xhReq.responseText;
  fb.activate();
}

This clears the existing inventory of anchors and then re-inventories the entire document, including the freshly added new content. Now your new floatbox anchors will work.

A jQuery AJAX fetch which launches fb.activate on completion could look like this:

$.get('someURL.php', function(data) {
  $('#myXhrDiv').html(data);
  fb.activate();
});

The simplest AJAX approach is to use floatbox's built-in ajax function and get fb.activate executed for free.

fb.ajax({ source:'someURL.php', updateNode:'myXhrDiv' });

For an ASP.NET UpdatePanel, you can set a callback function to fire the floatbox activation after the panel has finished updating. Put this javascript on the page:

function pageLoad(sender, args) {
  if (args.get_isPartialLoad()) {
    fb.activate();
  }
}

Or... as an alternative to getting the fb.activate function to fire at the right time, you could setup your new anchors with their own onclick action instead of giving them a class of "floatbox". For example, the following anchor will fire up in floatbox when clicked without needing to be activated:

<a href="somePage.html" onclick="fb.start(this); return false;">do it</a>

You can add options to the above sample anchor in the usual way by adding the desired data-fb-options or rev attribute settings.

Back to Index

WordPress and other templated systems

The recommended and supported approach to using Floatbox on a templated site such as WordPress is to directly edit the site's HTML as described in these instructions and shown on the demo page. Doing so gives you access to all of Floatbox's capabilities and support. Floatbox support does not extend to any third-party tools or plugins.

Please see this WordPress post for some getting-started pointers useful for adding Floatbox to the HTML of any template-based site.

Back to Index

Launching floatbox from flash ActionScript

This topic has very little to do with Floatbox, and everything to do with authoring behaviours in Flash objects. But there's a demand for this information so perhaps the little bit here can be some help.

Flash ActionScript can navigate to a URL on a click event, and a URL can be defined as a javascript action. This allows us to launch Floatbox using its javascript fb.start() API function as the target of an ActionScript navigation URL. Let's walk through setting that up.

Create a button in a flash object and give it a name. Let's call ours "button1". Now define a click action on that button. In ActionScript 2, that click action can be set on the button's action panel with on(release) { ... }. However, I think it's cleaner to define all ActionScript on the generic action panel of the layer object.

First, we'll get the click action to simply show a javascript alert. On the layer's action panel, define an action like the following (this is ActionScript 2):

button1.onRelease = function() {
    getURL("javascript:alert(99)");
};

ActionScript 3 does not have a getURL function. For AS3, use the more complex:

function myFunc(event:MouseEvent):void {
    var request:URLRequest = new URLRequest("javascript:alert(99)");
    navigateToURL(request, "_self");
}
button1.addEventListener(MouseEvent.CLICK, myFunc);

The idea of using the simple alert is that we can test that the ActionScript is working first before involving Floatbox. Assuming that it's working fine, let's replace the alert with the fb.start() call to open a floatbox. Checking the API reference we see that the fb.start function takes two string parameters. The first is the path to the content to be shown and the second is any Floatbox options that we want to set for that content.

The AS2 code with the fb.start command will look something like this:

button1.onRelease = function() {
    getURL("javascript:fb.start('gumby.jpg', 'boxRoundCorners:none')");
};

And the equivalent AS3 code would be:

function myFunc(event:MouseEvent):void {
    var request:URLRequest = new URLRequest("javascript:fb.start('gumby.jpg', 'boxRoundCorners:none')");
    navigateToURL(request, "_self");
}
button1.addEventListener(MouseEvent.CLICK, myFunc);

I've used an arbitrary option here just to show where the options go. The options parameter is optional (no pun intended), and the simple fb.start('gumby.jpg') is perfectly legal.

That's it. Providing you've got the Floatbox files properly included on the page and the content reference in the fb.start command points to something that exists, you should have Floatbox opening from a click on a flash button. If it's not working, confirm that the simple alert(99) works from the click action. If it does, then try pasting and running the javascript action directly into a browser's address bar and running it from there. If javascript:fb.start('pathToYourContent') doesn't work from the address bar, you need to look for the reason why.

There's a couple of samples in the 'Hi-Tech' section of the Floatbox demo page.

Back to Index

Serving gzip compressed files on Apache and IIS

Warning: This section discusses modifying your .htaccess file and using mod_rewrite on your Apache server. This is a bit of a black art. What works on one server configuration may not work another. No support or assistance is provided for modifying your .htaccess file or for serving the gzip files.

There is a 'gzip' folder in the Floatbox distribution zip file that contains gzipped version of Floatbox's js and css files. If you want to use them, copy them down into the main floatbox folder and configure your server to use them. The gzip files are a fraction of the size of the original files, but serve exactly the same content to the browser. You can direct your Apache server to serve these gzip files through your .htaccess file. The .htaccess file can be located in the floatbox or modules folder itself if you only want to serve floatbox gzipped files. If you want to enable gzipped files across your site, the .htaccess directives can go in your site's root folder.

Here's the suggested (but unsupported) htaccess directives to enable gzip file serving.

<IfModule mod_rewrite.c>
<IfModule mod_headers.c>

Options -MultiViews
RewriteEngine on
# if folder aliases are in use, set the correct RewriteBase for this folder
# RewriteBase /

<FilesMatch "\.js\.gz$">
ForceType text/javascript
Header set Content-Encoding: gzip
</FilesMatch>

<FilesMatch "\.css\.gz$">
ForceType text/css
Header set Content-Encoding: gzip
</FilesMatch>

RewriteCond %{REQUEST_FILENAME}.gz -f
RewriteCond %{HTTP:Accept-encoding} gzip
RewriteRule ^(.+)$ $1.gz [L]

</IfModule>
</IfModule>

Options.js is not provided in gzip format because it is intended to be edited with your implementation preferences. If you want to serve a gzipped version of this file, first edit (or use the configurator) to set your option preferences and then gzip the modified file. (GNU.org - Gzip for Windows)

IIS does not use the gzip files that are provided in the Floatbox package. Instead, compression is enabled and configured within IIS and IIS will generate its own compressed version of the served files. A search on "gzip iis" will locate information on how to enable and configure compression in IIS.

Back to Index

Using the library functions

Floatbox exposes an API to many of its internal functions that allows it be used as an effective javascript library in contexts beyond the base Floatbox functionality. In many cases, you can avoid loading other libraries such as jquery or mootools and instead use the Floatbox calls that are already loaded on your page. The Floatbox library includes a simple to use, robust and flexible AJAX utility, language translation, event handling, an image preloader, easy flash object creation, some helpful DOM manipulation routines, and more. For a complete list of available Floatbox functions, please see the API reference.

Back to Index