Floatbox v7.4 - Instructions

floatboxjs.com

Index

Quick-start

Floatbox has a lot of depth and versatility, but it's quite simple to install and get the basic functionality operational. The following three steps are all that's needed to get started.

  1. Install — Open the downloaded zip file and drag or copy the entire floatbox_xxx folder from that zip file to the web site's root folder (or other folder, if preferred), or push the whole floatbox folder and its contents up to a hosted site.
  2. Include — Add the floatbox.css and floatbox.js files to pages with two lines similar to the following, usually placed in the <head> section:
    <link rel="stylesheet" href="/floatbox_123/floatbox.css" />
    <script src="/floatbox_123/floatbox.js"></script>
    Of course, the folder paths in those two include lines have to match the folder name and location where the Floatbox package was placed.
  3. Use — Links to image and video content, such as the following, will now automatically open the linked content in Floatbox (thanks to the activateMedia option defaulting to 'true'):
    <a href="myPic.jpg">click me</a>
    (See the "Activating elements" section immediately below for how to mark up links to HTML content and gallery sets.)

The above gets the basics in place and operational. To implement more than the basics, it is necessary to read the rest of this 'instructions' document and the options reference to learn what Floatbox can do and how to make it do it. Anyone interested in scripting with Floatbox needs to review the programmer's API reference before tearing into writing code, and everyone should familiarize themselved with the license terms under which Floatbox is released. All these reference materials are in the docs folder of the downloaded zip file and are also online on the floatboxjs.com site. (The online reference materials always pertain to the latest floatbox version and are not to be relied upon when using an older release of the software.)
Reviewing the demo page is a great way to see the scope of what Floatbox can do, complete with markup and code snippets showing how it is done.

Using WordPress? See the WordPress section of these instructions for an easy way to use Floatbox in a child theme.

"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 a level or two 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.

Any modern browser's developer tools and console can be a great assistance in tracking down errors such as missing files or mismatched path references.

Back to Index

Activating elements

The 'Quick-start' section above gets standalone images and videos (plus Flash and PDF) displayed in a floatbox, without the need for additional markup such as the 'floatbox' class name (described in this section). Other content types, such as HTML and gallery sets (described below), can be referenced by the href attribute of <a> and <area> links, and marked for Floatbox behaviour by assigning the 'floatbox' class.

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

To illustrate:
Here's 3 links on a page. The first two open as standalone images in a floatbox (because they are media) and the third navigates to a new page (because it is not media and does not have a 'floatbox' class name assigned)...

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

The HTML link to credits.php could be instructed to also display in a floatbox by assigning the 'floatbox' class to it...

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

The first example above that shows only the images in a floatbox can be replicated using a containing element and the 'floatbox' and 'nofloatbox' classes like this...

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

And the second example that opens all 3 links in a floatbox could be setup with an inherited 'floatbox' class like this...

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

The power of using a containing element with the 'floatbox' class on it, and the real reason for setting things up like this, is to assign option settings to each contained link without needing to repeat those options on each individual link, or to light up multiple links to HTML content without repeating the 'floatbox' class on each one.
For example, here we are configuring a gallery set of 3 items (2 images and one HTML content page) by grouping them with options assigned to a parent div...

<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 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 on a page that have the 'floatbox' class - either implied, inherited, or directly assigned - get floatbox display behaviour assigned to them by the Floatbox library's internal activation routinethat is automatically fired at page load time. Any links that get dynamically added to a 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 attribute settings placed directly on a 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. fbOptions javascript objects (associative arrays) defined on the host page. These settings apply to all floatboxed links on the page.
  3. fbOptions.js file which will be automatically fetched at page load and applies to floatboxed items across the entire site.

The fbOptions data structure supports the ability to assign options based on content type and class names assigned to initiating links. Additionally, all option-setting contexts include the ability to assign 'mobile' overrides, which will be applied to small-screen devices only and which give the ability to customize floatbox appearance and behaviour specifically for mobile phones.

Option preferences can be organized based on the scope those options are to be applied to. For example, a specific link pointing to HTML content may have a 'width' option set directly on it, while setting 'boxCornerRadius' for all image content might best be done in the type section of the fbOptions.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. See the 'Enhanced tooltips' and 'Context boxes' sections below for details about setting their options. (It's a little bit different than for standard floatboxed links.)

Option names and values are case-sensitive. Options defined in an option string need to have any values that contain 'special' characters wrapped in a pair of back-quotes (`) or tilde (~) characters in order to parse correctly. The special characters are the ones used as delimiters in option strings and consist of : = & ; , and space.

For example:

Details of the various option-setting methods follow. Don't overlook reading the options reference to get the best understanding of the numerous Floatbox options available.

Back to Index

Setting options directly on links

Options for a particular link get set in a 'data-fb-options' attribute on that link, 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...">

For backward compatability (or just less typing), using the rev attribute is equivalent, but a 'rev' attribute will not validate as compliant HTML5. 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 link 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 links 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 link 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 link target should not be part of that slideshow set, and no navigation controls should be shown in the floatbox. (The 'afterSlideshow' and 'navType' options in this example are not required to get the slideshow functionality, but are present just to illustrate customization of the slideshow.)

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 links, 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 link. Use an fbOptions javascript object to assign option settings to all items on a page. The fbOptions object uses the same structure and sections as does the fbOptions.js file, so take a look at that file to see how to build the fbOptions object. fbOptions is defined in a <script> element placed in the primary page's <head> or <body> section. (It 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.)

This example sets a shadow type, animation values and navigation type for all floatbox items on a single page, and assigns a couple of overrides for small-screened mobile devices:

<script> fbOptions = { global: { shadowType: 'halo', resizeTime: 0.6, transitionTime: 0.6, overlayFadeTime: 0.2, navType: 'both' }, mobile: { shadowType: 'none', navType: 'button' } }; </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.

Note that a standard Floatbox options string, such as would be used in a data-fb-options attribute, can be used in any option setting context that accepts javascript objects. So we could write the above as:

<script> fbOptions = { global: 'shadowType:halo resizeTime:0.6 transitionTime:0.6 overlayFadeTime:0.2 navType:both', mobile: 'shadowType:none navType:button' }; </script>

The configurator (described below) can be used to assist in building the global section of fbOptions.

The per-page fbOptions object uses the same data structure as seen in the per-site fbOptions.js file, enabling use of 'type' and 'className' sections to assign options to certain types or classes on the current page. See the fbOptions.js file for syntax and available types.

When running floatbox in a hierarchy of iframed pages, the page-specific fbOptions object 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.

For compatibility with prior Floatbox versions, the old fbPageOptions, fbTypeOptions and fbClassOptions will still be picked up if the corresponding section is not found in an fbOptions definition.

Back to Index

Setting site-wide options

Global option preferences apply to all pages on a site that are using Floatbox, and are defined in the fbOptions.js file located directly in the Floatbox install folder. fbOptions.js does not have to be explicitly fetched by a <script> element. It will be automatically fetched by the Floatbox code. (fbOptions.js can be manually appended to floatbox.js to elminate one network fetch is so desired.)

There are four sections in the fbOptions.js file which allow targetting options to subsets of content.

Unlike the 'global' and 'mobile' sections, the 'type' and 'className' sections are heirarchical in the sense that options are not assigned directly to these objects, but rather assigned to sub-objects labelled with the type or class names. Take a look at fbOptions.js to see this structure in action.

An option string, as might be used in a data-fb-options attribute, can be used anywhere in the fbOptions definition where a javascript object of settings is used. See the page-specific section immediatley above for examples.

Back to Index

Setting mobile-specific options

It is sometimes desirable to options differently for small-screened mobile devices than for large-screened tablets and desktops. That's where 'mobile' options come into the picture. They define option overrides to be applied to devices with, generally, screens smaller than 8 inches. (Measuring the screens from javascript is not an exact science.) For example, the 'mobile' section in the fbOptions.js file

Mobile options are are merged into what could be considered the 'parent' set of options if a small screen is detected, and are ignored for larger-screened devices. For example, the 'mobile' section in fbOptions.js gets merged into the 'global' section and removes some clutter from the floatbox frame area along with a couple of other touch-friendly settings.

A set of mobile device options can also be assigned as a 'mobile' option sub-set in other contexts, such as className option sets, data-fb-options attributes, and a couple of others. An example of assigning a mobile setting based on content type can be found in the fbOptions.js file as follows:

type: { ... pdf: "mobile:`newWindow:true`", ... },

The above example was set from a string of option definitions. Javascript object syntax can be used instead:

type: { ... pdf: { mobile: { newWindow: true } } ... },

Individual className option sets can have a 'mobile' section structured very much like the 'pdf' type example above. Individual items receive mobile options as a setting in the host link's data-fb-options attribute, set using the string syntax (because element attributes are strings) and surrounded by `back-quotes` (or ~tildes~) because the option string contains separator characters.

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 global section of fbOptions by selecting default setting overridess from a form. For some, this can be quicker and less error-prone than manually typing in option settings directly.

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

The Configurator cannot write to a file system. It presents the text of a 'global' settings object which can be copied and pasted into the floatbox/fbOptions.js file or into fbOptions defined in script elements on individual pages. Other sections of fbOptions, such as 'mobile' or 'className' settings, need to be manually edited and are not generated the the configurator (although the global options listed by the configurator could be judiciously pasted into those other sections of fbOptions).

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 (a nag message shown in a floatbox). A license key can be acquired from the Floatbox registration page. Registration of a production web site grants rights for legal usage of Floatbox on the registered site, and installation of the obtained license key that matches the production site's domain will prevent the nag screens from appearing.
The floatbox package is complete and fully functional without a license key and registration is not required for development or evalution work.

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

global: { licenseKey: ""

The key goes between the quotes.
fbOptions.js 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 in an 'fbOptions' javascript object (see the "Setting page-specific options" section of these instructions). A bare-bones fbOptions definition with a licenseKey looks like this:

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

The configurator can help build the global section of fbOptions.

The license key can be tested by viewing a page that is using Floatbox and then running fb.key() from the browser's developer console.

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

The licenseKey field can accept multiple keys separated by a space or comma. This can be useful when 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.

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

File & content types

Floatbox determines what kind of content is being requested based on the file extension from a link's href attribute. It may sometimes be necessary to over-ride the extension-based determination and specify a content type directly. Content type over-ride is always required when loading AJAX, and can also be needed when a .php or .aspx page is serving images.

By default, .php and .aspx urls will be loaded as iframes. To make them load as images, set "type:image" on the link's data-fb-options attribute. If fetching AJAX content to be shown in a floatbox, a "type:ajax" over-ride is required in the options to prevent that AJAX content from being shown as an iframe.

Examples:

<div class="floatbox"> <a href="getPix.php?pic=29" data-fb-options="type:image">Pic 29</a> <a href="contact.html" data-fb-options="type:ajax">Contact Form</a> </div>

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 links (<a> or <area> elements) 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 link elements in that div. Also note that links used to define gallery set members do not have to have clickable content such as a thumbnail image or text. The anchor elements 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 link 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 from a separate file using AJAX, set the link's href to reference the AJAX source URL and put "type:ajax" in the link's data-fb-options attribute. To load content from an inline div, give that div a unique id and reference that id in the link'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. As an example, a plain text tooltip source would need to include a wrapping element, such as <p>Eat a Peach</p>.

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.

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.

iframe:

<a href="mypage.html" class="floatbox" data-fb-options="width:400 height:530 contentScroll:false" > Iframe page </a>

ajax:

<a href="myajaxpage.html" class="floatbox" data-fb-options="type:ajax width:400" > AJAX page </a>

inline div:

<a href="#divID" class="floatbox">Div content</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

Video presentation is a core strength of Floatbox, offering easy setup, an intuitive interface, functionality on a broad range of desktop and mobile browsers, and auto-starting and ending of videos on devices that support that. Videos can be added to gallery sets for display of a series of videos, including slideshow capability to auto-advance through the series as each video reaches its end.

HTML5 video player

Floatbox's integrated HTML5 video player (with Flash fallback) 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 HTML5 video. For older browsers that cannot, the Flash-based Flowplayer will be invoked and the .mp4 video will be shown using that Flash player. By default, Flowplayer will be loaded from the jsdelivr.net content distribution network. A local version of Flowplayer can be obtained, placed within the local site content and used from there by changing the reference in floatbox/video.html, but most Floatbox users will obtain no benefit from doing so.

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

YouTube & Vimeo

Floatbox provides an excellent and simple environment for presenting and viewing videos from YouTube and Vimeo on any device supported by those services. This includes all modern desktop and mobile browsers, but does not include old Internet Explorer (prior to version 9, and support and functionality for 9 and 10 is fading).
Check out the examples (with markup) on the "Video+" tab on the demo page.

Here's some pointers on setting things up:

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. These, along with 'base', 'bgcolor', 'menu', 'play' and 'salign', can be over-ridden 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" > Flash: not quite dead yet </a>

If a flash object needs flashvars to be set, the flashvars can be placed 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 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 using the document's /embed/ path from that service. The scribd service 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 content's styles, and then let Floatbox measure the height. When no height is specified for these HTML content types, the height will be measured and the floatbox size adjusted appropriately. Note that the maxWidth option, if specified as a %, is a good way to restrict the size of the content on smallScreen devices.

A large majority of Floatbox's HTML measurements are correct, but not all. In the rare cases where size detection is wrong, it may be necessary to fiddle with the styling or perhaps surrender completely and assign an explicit height in the options. Cross-domain iframe content cannot be measured by script; consequently, box height cannot be automatically matched to content height for cross-domain iframe content. Nor can video be measured, but height can be specified as a % of the width (height:xx%w) to maintain correct aspect ratio. This is done in fbOptions.js for type:video and sets a default of widescreen 16/9 proportions.

Back to Index

Cycling images and thumbnails

Floatbox includes the ability to display a set of images or thumbnails that will fade, zoom 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.

Cycler sets can show a 'Ken Burns' style zoom effect on images in between transitions. The cycleZoom, cycleEasing and cycleInflection control this zoom effect, with "cycleZoom:0" disabling it. See the Options Reference for more detail. (Note: the cycleZoom effect will not be shown in IE 7 & 8.)

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 "cyclePauseOnClick:true" to enable pause and resume on click, "cycleShowControls:false" to hide the controls, "cycleControlsPos:__" (fill in the blanks) 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 is also a 'cyclePauseOnHover' setting which should probably be avoided as the triggered behaviour is mouse-only with no corresponding touch interaction.

CSS can be used to style up the play/pause control and alter 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;">
The 'height' style is needed only if the images in the cycler set vary in height. In this case, setting height to the tallest image value prevents unsightly layout changes when new images are shown. The optional 'data-fb-options' attribute can be used to assign desired option preferences.

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"/>
We can 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. Where validation of img elements with no src attribute is a concern, 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. Without further styling, 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. Instead of using 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" style="height:100px;" data-fb-options="group:cycle1" > <a href="image1.jpg"><img src="thumb1.jpg"/></a> <a href="image2.jpg"><img data-fb-src="thumb2.jpg"/></a> <a href="image3.jpg"><img data-fb-src="thumb3.jpg"/></a> etc... </div>

Notice that all but the first 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. For example:

<a href="image4.jpg"> <img data-fb-src="thumb4.jpg" title="this is caption 4"/> </a> <a href="image5.jpg"> <img data-fb-src="thumb5.jpg"/> <span>this is caption 5</span> </a>

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 an interval of 4.5 seconds for the cycler set and a different per-image interval for one set member:

<div class="fbCycler" style="height:420px;" data-fb-options="cycleInterval:4.5 altAsCaption:true" > <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 or touch 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', 'showOnce', 'delay', 'arrowColor', and 'arrowSize'.

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 the className section of an fbOptions object, or site-wide by being assigned to the 'fbTooltip' class in fbOptions.js.

Be nice to users of touch devices and don't put tooltips on link (<a>) elements. They will never see the tooltip but instead will invoke the link action when tapping the link. Combine a tooltip and a link by placing the tooltip on an inert element (perhaps a <span> or <img>) and the link inside the tooltip content. The first touch will open the tooltip revealing the link that can be followed by a second touch.

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

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 className section of fbOptions.js or in the corresponding section of an fbOptions 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. Many browsers have an advanced configuration setting that individual users can set to either make their browser always show the context menu or to ignore right-click mouse actions altogether. It is recommended that 'contentMouseButton' not be set to 'right' outside of environments that don't have control of all the browsers being used.

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

Back to Index

Popup thumbnails

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

An 'fbPop*' link can also be a standard floatboxed link 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 link, is clicked. Without a class of "floatbox" assigned, the link will navigate to its href as normal when clicked. To have a popup link 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*' link, 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 link a larger version of the second image. On mouseover, the thumbnail will appear to expand to the larger size.

As might be expected, there's samples to be found in the 'Tooltip+' 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 a link'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.

Two captions can be shown on the same item by assigning the second caption to the 'caption2' option in the same manner as the first one on the 'caption' option.

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 link's title attribute or that of a thumbnail img element in the link. Captions can also be taken from the alt attribute of img elements by setting 'altAsCaption' to true. Be aware that browsers display a link's title as a tooltip when the user mouses over the link. To avoid triggering this browser tooltip, set the caption using the caption option (or the alt attribute) rather than placing it in the title attribute.

Here's two examples:

<div class="floatbox"> <a href="boogers1.jpg" data-fb-options="caption:`This is the first caption` caption2:`And this is the second caption`" > boogers! </a> <a href="boogers2.jpg" title="This is both a tooltip and a caption" > more boogers! </a> </div>

Floatbox captions can be built from, or contain, HTML elements. There's two ways to get HTML into captions. The first is to put the 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>
(Told you it could get messy.)

If a caption is set to the string "href", the displayed caption will be the value of the filename component of link's href attribute. This might be useful when displaying iframed content or to display the 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, with or without text (see the 'showControlsText' option). An alternate close button is available. It's not shown by default, but is used in some of the builtin className option sets. 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'. To always use the outerClose button and not the traditional close button in the floatbox frame area, set both 'showClose:false' and 'showOuterClose:true' in the global section of fbOptions.js.

Back to Index

Built-in class options

Options assigned to class names are a great way to define a re-usable set of options for multiple floatboxed links. There are five pre-defined className option sets defined in the fbOptions.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:modern' )

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

Back to Index

Info box for secondary content

There are occasions when it is helpful to display additional information about 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 that can be set in a link'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. This default text can be over-ridden 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

A link 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 in the demo page's 'Options' section.

Back to Index

Print contents

If "showPrint:true" is set in a floatboxed link'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.

The 'printCSS' option can be used to add CSS styling to the print window contents. If printCSS is a URL path to a .css file, that css file will be attached to the print window. Alternatively, CSS assignments can be specified directly in printCSS as a string 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...`".

The print window does its best to import styles from the original page and so it's not normally necessary to add specific printing CSS, however, the capability is there if needed.

Floatbox's default 'mobile' options sets 'showPrint' to false for small-screen devices because these devices typcially can't print. Also, cross-domain iframes (iframe content coming from a different domain) cannot be manipulated, hence cannot be printed, and the "Print..." option will not be displayed.

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

Back to Index

Open in a new window

There may be content or circumstances where it is helpful to offer site visitors a way to open the current floatbox content in its own new window or tab. Do this by setting 'showNewWindow' to true in a link's option string (rev or data-fb-options attribute), or perhaps in className settings assigned to various items. This will place a link in the floatbox frame that can be clicked to open the current content in a 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. 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 (avoiding a huge list of numbered links for a gallery set of 479 pictures).

Five other options affect index links.
Setting showIndexThumbs to false turns off the thumbnail popups within the index links.
The maxIndexThumbSize option can be used 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 link 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 link's linked image.
The location of the index links within the floatbox frame area is set by the indexPos option. (See the "Layout" section of these instructions for details.)

Index links can be seen in action in the 'Images' section of 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 consist of icon font graphics and may optionally include text labels localized to the user's language (see showControlsText in the Options Reference).

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 >> graphic, with or without text, in the box frame outside of the content. The 'navType' options is used to specify either or both of these navigation controls. Most people will find that Floatbox makes pretty good choices about when to show which type of navigation, and that 'navType' doesn't normally need to be fiddled with.

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:

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, the close button and navigation controls. Placement of these items can be specified 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-right, etc.
Note that the 'tc' and 'bc' positions are not guaranteed to be truly centered. It can be too expensive in terms of wasted space to enforce strict centering when there are other things displayed in the left or right positions.
Note also the availabilty of the 'header' and 'footer' options and components to display something outside of the floatbox: above or below it.

Back to Index

Appearance and Colors

Many of Floatbox's options are for configuring the floatbox's appearance. Colors of various components, round corners, border sizes, display of controls, shadow effect, transparencies and various animation effects are controlled through configuration options. See the options reference for details on the use of these (and other) options.

Floatbox has 6 pre-configured color themes: white, black, blue, silver, red and yellow. When no colorTheme option is specified, Floatbox defaults to black for images, white for HTML content, and blue for video and flash. The 'colorTheme' option can be set globally, per page, or per item, and assigned to specific classNames or content types, to override the per-type defaults.

Colors of various Floatbox components can be specified directly using color options. In addition to colorTheme, the following are available: boxColor, overlayColor, innerBorderColor, outerBorderColor, textColor, strongTextColor, contentBackgroundColor and arrowColor. 'strongTextColor' sets the caption color and the highlighted color of the other text items and controls when they are mouse-hovered. 'contentBackgroundColor' sets the background color inside the floatbox content area and is useful if the displayed content has transparent areas. 'arrowColor' is used exclusively by enhanced tooltips for their little pointer arrows.

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 className entry fbOptions and placing that class name on the floatboxed links. See the Instruction sections on setting page-specific and site-wide options for details.

Back to Index

Language localization

Floatbox includes language localization files for 40 languages. The strings in these files are used as text labels on the various controls, tooltiped keyboard hints on those controls, the "image x of y" display, the text displayed on "Info..", "Print..." and showNewWindow links, and the strings shown when a required multimedia plugin is not present. The default English language strings are provided directly in the javascript code. Use the 'language' option to request non-English versions of Floatbox's strings that match the language used for the web site content.

Back to Index

Auto-start and exit tasks

A floatbox can be automagically started directly at page load time by using the autoStart option. Put "autoStart:true" into the data-fb-options attribute of the floatbox-enabled item to be shown at startup. As soon as the page loads, floatbox will start with this item displayed. Setting "autoStart:once" will load the requested item only on the first page load of the current browser 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. Set "autoDelay" to a number of seconds to make Floatbox wait that long after page load before auto-starting the floatbox.

Auto-starting 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 a link 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 link'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 the floatboxed content has modified some back-end content and the host page needs to be refreshed to reflect the changes. If loadPageOnClose is set 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. When loadPageOnClose is set to a url inside an option string, it is often necessary to surround the url with backquotes (`) so as not to break parsing of the option string.

When closing floatbox by calling the API fb.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 'Images' 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

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 links. 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 the fb.ajax function. However, a generic AJAX content insertion may be in use - something like this:

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

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

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

This clears the existing inventory of linked content and then re-inventories the entire document, including the freshly added new content, and 'lighting up' the newly added links.

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', $:'myXhrDiv' } );

For an ASP.NET UpdatePanel, a callback function may be set to fire the floatbox activation after the panel has finished updating. Like this...

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, the new links could be setup with their own onclick action instead of giving them a class of "floatbox". For example, the following link 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>

Options can be added to the above sample anchor in the usual way by adding the desired data-fb-options (or rev) attribute settings. The options can be passed in as a second string parameter to the fb.start function as well - see the API Reference for details.

Back to Index

Page interaction while loading

Slow-loading pages may present an opportunity for the user to click on links early while the page is still loading and before Floatbox activation has assigned its click handlers. Thus the user can inadvertently navigate away from the page.

This early navigation can be prevented by placing the floatbox.js include line in the <head> of the document (not down at the end of the <body>). When floatbox.js loads, it temporarily places a 'floatbox' class name on the <html> element. At the bottom of floatbox.css there is a line which disables pointer events on floatboxed links while that html class name is present. When the document is ready and Floatbox can proceed with its activation, the 'floatbox' class name is removed from the <html> element and pointer events become available.

There may be links that don't use the 'floatbox' class but that should nonetheless ignore pointer events until the page is ready. These links could be for media that will be auto-activated due to Floatbox's 'activateMedia' option, or other links not related to Floatbox. To disable all links on the page during loading, change that pointer rule in floatbox.css to html.floatbox a { pointer-events: none }. To allow all links during loading, simply remove that entire pointer-events rule from the floatbox.css file.

Users of IE version 10 or earlier: we're sorry, but your browser doesn't understand pointer-events and you can always navigate those links early during page load.

Back to Index

Upgrading

When upgrading to a newer version of Floatbox, consider the browser cache implications for site visitors. The Floatbox distribution .zip file has the version number included as part of the floatbox folder name. Retention of this version component is recommended so that cache conflicts will not occur when upgrading to new Floatbox versions. Of course, the folder component will appear in the paths for the include links that load floatbox.js and floatbox.css, and so these include lines will need to change on each page when upgrading.

If upgrading a minor version release but within the same major version family, the previous fbOptions.js file can usually be copied into the new folder as a way of retaining any customized settings (or license key) from the prior version.
Upgrading to a new major version always entails manually editing the new fbOptions.js file and prior fbOptions can not be carried over into new major version installs.

There may also be option and API changes between major versions that might require changes to the floatbox markup on a page. Check the changelog entries for all versions that have come after the old version that is being upgraded for changes that might affect Floatbox usage and markup.

Back to Index

Serving GZIP files

Best practice for a fast-loading web site is to serve compressed gzip files whenever possible.

If serving a site from IIS, gzip compression is enabled and configured in the IIS configuration. A search on "gzip iis" will find detailed information on this.

For use on sites served from Apache, There is a 'gzip' folder in the Floatbox distribution zip file that contains gzipped version of Floatbox's js, css and html files. To use these compressed files, copy them out of the 'gzip' folder and into the main floatbox folder one level up. Add something like the following to .htaccess at the site's root to get Apache to serve the gzip files.

### Enable gzip files, from Floatbox <IfModule mod_headers.c> <IfModule mod_rewrite.c> RewriteEngine On Options -Multiviews RewriteCond %{REQUEST_FILENAME}.gz -f RewriteCond %{HTTP:Accept-encoding} gzip RewriteRule ^(.+)$ $1.gz [L] <FilesMatch "\.gz$"> Header set Content-Encoding gzip </FilesMatch> <FilesMatch "\.js\.gz$"> ForceType text/javascript </FilesMatch> <FilesMatch "\.css\.gz$"> ForceType text/css </FilesMatch> <FilesMatch "\.html\.gz$"> ForceType text/html </FilesMatch> </IfModule> </IfModule> ### End - Enable gzip files, from Floatbox

fbOptions.js is not provided in gzip format because it is intended to be edited and modified appropriately for each web site. Once fbOptions.js is stable with no more modifications to it expected, it can (and should be) compressed with a tool such as UglifyJS Online and then either gzipped by itself, or appended to floatbox.js and re-gzipping that modified file. 7-Zip can generate gzip files, as can the more compact console program from GNU.org.

Back to Index

Serving a single Floatbox install to multiple web sites

If running Floatbox on multiple sites, having each of those sites load the Floatbox files from a single instance installed on one site is a great way to simplify installation, configuration, upgrading and life.

Floatbox version 7 uses icon fonts instead of background images for the graphical component of various controls. Most modern browsers require an 'access-control' header to be present in any font file served from a foreign domain before they will fetch and use that file. (See https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS.)

The required CORS header can be added to Apache by copying the following directive into .htaccess in the web site's root folder.

### Enable x-domain font access, from Floatbox <IfModule mod_headers.c> <FilesMatch ".(eot|ttf|otf|woff2?)(\?|$)"> Header set Access-Control-Allow-Origin "*" </FilesMatch> </IfModule> ### End - Enable x-domain font access, from Floatbox

To prevent leeching, the origin "*" in .htaccess can be changed to list only the sites that are permitted to access the font files remotely.

If serving from IIS, custom headers can be added by navigating to the floatbox/resources folder in IIS Manager, and adding a custom HTTP response header from there. Alternatively, the headers can be set in a web.config file.

Back to Index

WordPress integration

Create a WordPress child theme to include and use Floatbox on all your site's pages. The minimal requirements for a child theme are two files, functions.php and style.css, in a sub-folder under the 'wp-content/themes/' folder. The 'style.css' file needs a commented header section which describes the child theme to the WordPress admin pages, but it doesn't need any actual css rules. Here's a sample style.css file:

/* Theme Name: Floatbox Child Theme Description: Add the power and beauty of <a href='https://floatboxjs.com/'>Floatbox</a> to an active WordPress theme. Author: admin Version: 7.4.1 Template: your_parent_template_name */

The 'functions.php' file contains the code which adds floatbox.js and floatbox.css to your theme's pages, and possibly does a couple of other small tasks that may be required for your particular theme.

<?php // include floatbox.js and floatbox.css function get_floatbox() { wp_enqueue_script( 'floatbox', '/../floatbox/floatbox.js', // change to actual path array(), '7.4.1', // cache control true ); wp_enqueue_style( 'floatbox', '/../floatbox/floatbox.css', // change to actual path array(), '7.4.1', // cache control 'all' ); } add_action( 'wp_enqueue_scripts', 'get_floatbox' ); // May need to turn off parent theme's built-in lightbox // by putting 'noLightbox' class on the body. function no_lightbox_class( $classes ) { $classes[] = 'noLightbox'; return $classes; } // add_filter( 'body_class', 'no_lightbox_class' ); // Need to enqueue parent and/or child theme style.css // only if there are active style rules in those files. function enqueue_theme_styles() { $parent_style = 'parent-style'; wp_enqueue_style( $parent_style, get_template_directory_uri() . '/style.css' ); wp_enqueue_style( 'child-style', get_stylesheet_directory_uri() . '/style.css', array( $parent_style ), wp_get_theme()->get( 'Version' ) ); } // add_action( 'wp_enqueue_scripts', 'enqueue_theme_styles' ); ?>

Use the WordPress admin pages to make the new child theme active. Floatbox's default 'activateMedia' functionality will now show all image and video links as floatbox content. To show other content types, or to setup cyclers, tooltips, context boxes and popup thumbs, or to add data-fb-options to some links, modify the page's HTML directly in the WordPress editor using the "Text (HTML)" view or tab. HTML markup added this way should persist through theme updates.

The tasks required to get Floatbox going on web pages are the same everywhere, including other non-WordPress templated systems: get floatbox.js and floatbox.css on the page, and either let Floatbox's 'activateMedia' option light up links to images and videos, or edit the HTML markup directly with the desired Floatbox bits. And have fun...

Back to Index

Using the library functions

Floatbox exposes an API to many of its internal functions that allows it to 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, event handling, CSS selector interface, lazy-load page bootstrapper, animations, form processing, an image preloader, some helpful DOM manipulation routines, and more. For a complete list of available Floatbox functions, please see the API reference.

Back to Index