Floatbox v3.54 - Instructions

randomous.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.
  2. Include - Add the following two lines to the <head> section of the pages where you want to use floatbox.
    <link type="text/css" rel="stylesheet" href="/floatbox/floatbox.css" />
    <script type="text/javascript" src="/floatbox/floatbox.js"></script>
  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>
  4. There is no step 4. You're done. But to get the most out of floatbox and 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 pages. These reference materials are in the docs folder of the downloaded zip file and also online on the randomous.com site. The online reference materials always pertain to the latest floatbox version.

Back to Index

Basic options

Floatbox's appearance and behaviour is controlled by setting various options. More detailed information about setting these options is given below, but here's some basic information about the most common options.

You assign option values to a particular anchor by placing them in either a "rev" or a "data-fb-options" attribute on the anchor. The options you really want to know about are "group", "width", "height" and "scrolling".

To group a collection of floatbox anchors into a navigable gallery set, assign a common group string to each anchor in the set. (Gallery sets are usually comprised of images, but you can use any and all content types in your sets.)
An example: <a href="myPic.jpg" class="floatbox" rev="group:pics">click me</a>
If you have other anchors that also have a group string of "pics" (or any other arbitrary but matching string), those anchors will be shown as a gallery set.

If you are showing something other than images in floatbox, you will want to set "width", "height" and possibly "scrolling" on those anchors. Width and height are self-explanatory. Setting scrolling to "no" will turn off scrollbars in the floatbox. So, for example, a form could be loaded into floatbox with an anchor like the following (this example is using the "data-fb-options" attribute, but it could use the "rev" attribute instead to the same effect):
<a href="myForm.html" class="floatbox" data-fb-options="width:450 height:350 scrolling:no">the form</a>

Back to Index

Installation alternatives

(You don't need to read this section if you are using the standard install location.)

The quick-start instructions above have you copying the floatbox folder to the root of your site. Some folks prefer to place the floatbox package within another sub-folder. This is fine. You just have to adjust the given include lines for floatbox.js and floatbox.css so that they match the location of the files. For example, if you place the floatbox files in the folder /includes/floatbox/, the two include lines in your <head> section would need to be:
<link type="text/css" rel="stylesheet" href="/includes/floatbox/floatbox.css" />
<script type="text/javascript" src="/includes/floatbox/floatbox.js"></script>

There are many supporting files included in the floatbox download. They are nearly all needed for correct functioning. Floatbox is modular. It loads its modules and css files on demand as required, but it needs to find these modules and css files in order to do so. It is highly recommended that you keep the floatbox folder intact and not try to separate the components out to different folder locations. If you keep the install folder intact, floatbox will auto-detect its modules, graphics and css locations. If you break up the install into different locations (not recommended), you will need to explicitly set the "installBase", "jsModules", "cssModules", "languages", and "graphics" paths in floatbox's options - either in a fbPageOption definition (see below) or in the preferences section of the floatbox.js. You will also need to update floatbox.css and the css files in the modules folder with the correct relative paths to the background images. (Really, just leave the floatbox folder structure intact. Everyone will be happier.)

Floatbox locates its modules by scanning the include line in the head section for the floatbox.js file path. If you rename floatbox.js to something else, as you might do if you are almagamating all your javascript into one file, you will need to set those path options described in the preceding paragraph.

If you are developing your site on a local file system rather than working from a web server, the root of your "site" will be the root folder of your drive. If you're on C: drive on a Windows system, the floatbox files should be in the C:\\floatbox\\ folder. Alternatively, you may want to use relative paths for your include paths such as src="floatbox/floatbox.js" or src="../floatbox/floatbox.js", etc., depending on where the files are relative to the page the include lines are on. (It's easier to develop on a real web server and just use the same absolute paths everywhere.)

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 you will be legally entitled to deploy the floatbox software to your production 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 your license key by locating the licenseKey.js file in your floatbox install folder. Open that file in any text editor, and paste your license key in between the quotes. It looks like this:
fb.licenseKey = "Your Key Goes Here";

The license key can also be set directly in the options section at the top of floatbox.js and framebox.js, or you can set it directly on your page with the "fbPageOptions" script object (see "Setting page-specific options" below). Using fbPageOptions looks like this: <script type="text/javascript">
fbPageOptions = {
  licenseKey: 'abcd1234'
};
</script>
 You can test your license key by loading a page that has floatbox included and then running javascript:fb.key() from your browser's address bar.

License keys are matched to the production domain they are deployed to. If you are a publisher of multiple web sites and you have registered those sites for licensed floatbox usage, you have the option of generating a multi-site "master" key for all your registered domains. This is a single license key that will be valid on each of your registered domains. Using such a multi-site license key can simplify deployment by allowing you to use a single distribution source and not have to match individual keys to individual deployments.

Back to Index

Upgrading

Upgrading to a new version of floatbox entails replacing the entire contents of your existing floatbox folder. The javascript modules, css files, graphics and languages can all change between versions and all the components need to be in sync. When you upgrade to a new version, you may need to edit the options section at the top of floatbox.js to set your default preferences if you want your defaults to be different than as shipped. If you have a license key installed in either the licenseKey.js file or the floatbox.js file, make sure you transfer your license key into the new version.

If you are upgrading floatbox from a version prior to v3.50, you will notice a few changes in floatbox's operation and configuration. Previous versions used the rel attribute to activate anchors and to define behaviours such as slideshows and gallery groupings. The newer versions of floatbox prefer using the class attribute (class="floatbox") to mark anchors for activation, and use rev options such as doSlideshow and group for setting behaviours. Also, some configuration options have had name changes. Floatbox is fully backward-compatable with the previous version's way of doing things and all the old style markup, functions and options will continue to work without modification.

If you are moving from lytebox to floatbox, you do not need to change the markup of your anchors if you don't want to. Floatbox will recognize your existing lytebox rel attributes. However, you will probably want to change your markup to take advantage of the many capabilities and configuration options that can be set.
The following rel attributes and the traditional extensions of them with group names where applicable, are recognized:
floatbox, gallery, slideshow, iframe, lytebox, lightbox, lyteshow and lyteframe.
For compatability with pre-existing lytebox pages, the css-like syntax for the rev options is recognized:
<a href="mypage.html" rel="lyteframe" rev="width: 400px; height: 530px; scrolling: no;">...</a>

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

IE 8 rendering mode

The rendering engine in Internet Explorer 8 is extremely slow and inefficient at javascript animations such as element resizing and opacity fades. IE7 was not great in this respect, but IE8 is very poor. There is some code in floatbox to significantly speed up IE8 animations, but the trade-off is that this results in choppiness. To get the best effects in all browsers, it is highly recommended that all pages that show animated floatbox content include the header to set IE8 into IE7 compatability mode. You can do this by adding a meta tag to your page's <head> section: <meta http-equiv="X-UA-Compatible" content="IE=7" />. Or, from php, you can send the header directly with header('X-UA-Compatible: IE=7');

Back to Index

Configuring options

Don't overlook reading the options reference. You'll get the best understanding of floatbox options from there.

There are 3 different ways to set configuration options for floatbox. In order of precedence, options can be set from:

  1. the clicked link's rev attribute
  2. fbPageOptions (and fbChildOptions & fbClassOptions) javascript objects defined on the host page
  3. the defaultOptions (and childOptions) object at the top of floatbox.js

When setting your global preferences (i.e., not anchor-specific), the best approach may be to use the fbPageOptions definition on your pages rather than modifying the defaults in floatbox.js. This way, when you upgrade or redeploy floatbox you don't have to remember to go back in and re-edit your changes. The small downside to using fbPageOptions is that it has to be placed on each page where you wish to use floatbox. Editing the settings in the top section of floatbox.js is certainly a viable approach and has the advantage of applying those preferences to all pages that include the floatbox.js file.

Details of the various option-setting methods follow. (Note that option names and values are case-sensitive.)

Back to Index

Setting options directly on anchors

Probably the most useful of floatbox's options setting techniques is the ability to configure the behaviour of specific anchors. 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, width is per item whereas cornerRadius applies to the whole set.
Syntax is: <a href="xyz" class="floatbox" rev="option1:value1 option2:value2 etc.">.
There's lots of examples of options set in rev tag markup on the demo page and there's a detailed example below where starting a slideshow is discussed.

The proposed HTML5 standard deprecates the anchor's "rev" attribute. To get a jump on HTML5 compliance, floatbox allows you to place the option information on a "data-fb-options" attribute in place of the rev attribute. (data-* attributes are "legal" under the current proposal and are intended for uses exactly such as this.) Your HTML5 compliant anchors might look like this:
<a href="xyz" class="floatbox" data-fb-options="option1:value1 option2:value2 etc.">.

Back to Index

Example: Start a slideshow from a link

If an anchor has "doSlideshow:true" set on its rev attribute then, when clicked, the corresponding grouped images (or other content) will be shown as a slideshow. This allows for setting up a gallery with a dedicated link to viewing that gallery as a slideshow. When you do this, you would normally want to include the option "showThis:false" so that the activating link itself is not included in the invoked slideshow.

An anchor element that enables a slideshow could look something like this:
<a href="" class="floatbox" rev="doSlideshow:true group:myShow showThis:false endTask:exit autoFitImages:true navType:none">Slideshow</a>
The images that will be included in the slideshow are those from activated <a> element's that have the same "group" value in their rev attributes. If the href in the slideshow anchor matches one in the gallery set, the slideshow will start with that image.

Back to Index

Setting page-specific options

All the default options listed at the top of floatbox.js can be overridden for a specific page by placing an object definition called "fbPageOptions" on the page. You could for example set a shadow type, animation values and navigation types for a for a page of floatboxed content with the following page-specific javascript object:
<script type="text/javascript">
  fbPageOptions = {
    shadowType: 'halo',
    resizeDuration: 5.5,
    imageFadeDuration: 4.5,
    overlayFadeDuration: 0,
    navType: 'both'
  };
</script>
 Note the syntax: there are commas after each name:value pair except for the last one. When running floatbox from iframed pages, the fbPageOptions object definition needs to be placed in the top (base) document.

In addition to fbPageOptions, you can also define "fbChildOptions" and "fbClassOptions" in a similar manner. Options defined in fbChildOptions apply to secondary or child floatboxes only. Child boxes inherit option preferences from the parent box, but these can be overridden with fbChildOptions (and with the childOptions defined in floatbox.js).

You can use the fbClassOptions object to assign option preferences to items on your page based on the items' class attributes. The name:value pairs in fbClassOptions are comprised of the classname and an option string identical to what you would assign to an anchor's rev (or data-fb-options) attribute. For example: <script type="text/javascript">
  fbClassOptions = {
    myVideos: 'color:red width:444 height:333 scrolling:no',
    myImages: 'cornerRadius:8 enableDragMove:true showItemNumber:false'
  };
</script>

Back to Index

Using the Configurator to setup page-specific options

The Floatbox package includes a Configurator html page that can be used to generate an fbPageOptions object definition by selecting options settings from a form. This can be quicker and less error-prone than manually typing up your fbPageOptions preferences directly.

Open configurator.html in your floatbox install folder with any browser. Select your option preferences on the form and click the button to generate your fbPageOptions code. The fbPageOptions definition shown will be only those settings that differ from the defaults defined in the defaultOptions section of floatbox.js.

Paste the given fbPageOptions code into a properly formed <script> element on your pages or in your template. It's a good idea to also edit the configurator.html file itself and paste the fbPageOptions code into the head section of that file. This way, when you return to the configurator form, your previous option preferences will be preset in that form.

You can manually add additional settings such as your license key or floatbox callback functions to fbPageOptions on your pages and in the configurator.html file and these will be retained in the generated code.

Back to Index

Auto Gallery creation

The "normal" way to create an image gallery for floatbox is to add a floatbox class and rev attribute group option to each image link you want included in the gallery. You can auto-create a floatbox gallery without adding this markup to your anchors. To do so, include floatbox.js and floatbox.css in the usual fashion (as described above) and set up a fbPageOptions object that contains "autoGallery:true" in it. This will tell floatbox to build a gallery set consisting of each image that is the target of an anchor's href attribute. If you have a few image links that you want excluded from the autoGallery group, you can exclude them by pre-setting a class of class="nofloatbox" on the ones to be ignored. (Note: you can set autoGallery:true in the options section of floatbox.js. This will turn every page that you include floatbox on into an auto-gallery page.)

You can auto-set a title (caption) on each image link as well. Do this by setting the autoTitle option to your desired title string. This title will be shown as a caption in the floatbox display. (Note that existing titles set on individual links will take precedence when the captions are setup.) Also, if you want to include a slideshow link to the auto-created gallery, do so in the normal fashion as described in this example and use a rev attribute grouping option of rev="group:.autoGallery". (The old school rel="floatbox.autoGallery" still works too).

The fbPageOptions object definition for an autoGallery would look something like this:
<script type="text/javascript">
  fbPageOptions = {
    autoGallery: true,
    autoTitle: 'This is a caption on every image'
  };
</script>

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:img" on the anchor's rev tag. If you're fetching AJAX content, you need a "type:ajax" over-ride in the rev tag.

Example:
<a href="getPix.php?pic=29" class="floatbox" rev="type:img">...</a>

Back to Index

HTML content: iFrames, AJAX & inline DIVs

Floatbox handles 3 broad categories of content: images, html and multi-media. This section describes handling html content.

There are 3 ways to load html into a floatbox: as an iframe, using AJAX, and using content from inline hidden DIVs. Standard anchor hrefs that aren't recognized as an image or multi-media type will be loaded as iframe content by default. To load that html content with AJAX, you need to put "type:ajax" in the anchor's rev 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"). See below for examples.

There are three rev options that should be assigned to each non-image anchor: "width", "height" and "scrolling". Width and height are the numeric size in pixels that the floatbox content will be shown at. One or both of width and height can be specified as "max" which will set that dimension to match the current window size. Width and height can also be expressed as percentages and will size to that percentage of the available displayable screen area (e.g, rev="width:90%"). You can also set the "sizeRatio" option to display an item at maximum size while retaining a specific width/height ratio. Scrolling is either "no", for no scrollbars, or "auto" for displaying scrollbars in the iframe if they are required. If no value for scrolling is given, auto is assumed.

When loading content from a hidden div, be aware that it is the innerHTML of that div that gets displayed in floatbox. The implication of this is that any styles applied to the hidden div itself will not be in effect when the content is displayed. Put your styles on a div inside the hidden div content to have those styles transfer in to the floatbox successfully.

When loading content of type:ajax, you can set cacheAjaxContent to true to give a little speed boost to your pages. Do this only if your ajax content is the same each time it is fetched. cacheAjaxContent is false by default so as not to cause problems with changing or dynamic content.

Here's some examples of anchor tags that load html content:
IFrame: <a href="mypage.html" class="floatbox" rev="width:400 height:530 scrolling:no">...</a>
AJAX: <a href="mypage.html" class="floatbox" rev="type:ajax width:400 height:530 scrolling:no">...</a>
Inline DIV: <a href="#divID" class="floatbox" rev="width:400 height:530 scrolling:no">...</a>

The following section gives information about loading multimedia content, either directly or as iframe content.

Back to Index

Multimedia: Flash, Silverlight, QuickTime, YouTube, etc.

Multi-media content type is recognized by floatbox based on the file extension in an anchor's href. .swf files are loaded with the flash plugin, .xap files are loaded using Silverlight, and .mov .mpg .mpeg and .movie extensions will be loaded with the QuickTime plugin. In addition to locally served multi-media files, you can load floatbox content directly from online video services such as YouTube, Yahoo Video, Vimeo, Google Video, Metacafe and many others. If the required plugin is not available on the client browser, floatbox will display a notice (in English) with a link to the plugin download page.

For flash content, floatbox assigns the following parameter default values: wmode=window, allowfullscreen=true, scale=exactfit, play=true, loop=true, quality=high. You can over-ride these plus 'allowScriptAccess', 'bgcolor', 'base', 'menu' and 'salign' by providing new values in the href url's querystring.
e.g., <a href="myflash.swf?wmode=opaque&amp;bgcolor=#ffffff&amp;scale=default" class="floatbox" rev="width:320 height:240 scrolling:no">...</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. And if you require a minimum version of flash to successfully play your content, you can set the minFlashVersion option in your anchor's rev or data-fb-options attribute like this: rev="minFlashVersion:8.1.0"

Quicktime default parameters used are autoplay=true, controller=true, showlogo=false and scale=tofit. These can be overridden with a querystring in the same manner as described for flash.
All Silverlight control parameters are left as defaults and can be set through the querystring.

When loading videos from an online video service such as Youtube or Vimeo, you need to determine the href path to use and the width and height dimensions. For YouTube, Yahoo and Vimeo, you can use the site's page url for the href, or you can use the embed path. For other online video services you must use the embed path.

Most video services show you the embed code directly or have a "share" button that will show this code. This is where you can look up the width and height. The easiest approach is to look at the examples in the Multimedia section of the demo page for the video service you are interested in, modelling your anchors after the ones given there and changing the parameters to point to the videos you are interested in loading.

Additional settings you can place on Youtube querystrings include: fs=0 to disable fullscreen capability, start=xx to start playing xx seconds into the video, ap=%2526fmt%3D18 for hi-quality video, and ap=%2526fmt%3D22 for hi-definition (where available).

It is usually best to direct-load multi-media files. Floatbox direct-load code contains some fixes for troublesome objects in some browsers. You can also load multi-media content as ajax or iframes. There may be times when you want to do this to gain more control over the displayed object. For an ajax load, just bring in the object/embed code (or the required javascript if you're using script to setup your objects). For an iframe load, you will want to have a complete and properly setup html document with a head and body section. Make sure your iframe's document body has no margin or padding: body { margin: 0; padding: 0; } Then set the floatbox width and height to the exact dimensions of your multi-media object and add "scrolling:no" in your rev tag. There's a sample in the html section of the demo page.

Back to Index

Alternate content for javascript-disabled browsers

You may wish to provide alternate content for users who have javascript disabled in their browsers. If your page is setup to display images in floatbox but javascript is disabled, clicking on the image link will simply display that image on a blank page. To provide a more friendly experience in this case, you can set the link's href attribute to point to your friendly non-javascript content and use floatbox's "href" option in the rev attribute to provide the image path to floatbox. A floatboxed link with alternate content might look like this:
<a href="altGallery.html" class="floatbox" rev="href:`myImage.jpg`"><img src="myThumbnail.jpg" /></a>
In this case, when myThumbnail.jpg is clicked floatbox will display myImage.jpg and javascript-disabled browsers will navigate to the altGallery.html page.

Back to Index

Popup thumbnails

You can configure anchors to have a popup thumbnail that appears when the mouse is over the anchor and disappears when the mouse moves off. The popup thumbnails can be clicked to load an associated image in floatbox. Combining popup thumbnails with floatbox's ability to zoom from a thumbnail to an image makes for a nice effect. Popup thumbnails are enabled by assigning a class of "fbPopup" to the <a>nchor element. Here's an example:
<a class="fbPopup floatbox" href="myImage.jpg">clickable text<img src="myThumbnail.jpg" /></a>
Popup thumbnails set with "fbPopup" appear just above the hovered anchor. Use "fbPopdown", "fbPopleft" or "fbPopright" if you prefer the thumbnails to show on those sides of the anchor.

As you might guess, there's samples in the 'Bonus' section of the demo page.

Back to Index

Cycling images and thumbnails

You can use floatbox to display a cycling set of images or thumbnails on your main page that will rotate through a set of images. This can be an effective way to setup a slideshow link or to put a dynamic header at the top of your pages. See examples of this under the "bonus" tab on the demo page. The sample code under those demos are a good way to get started with your own cycle set. Use the cycleInterval and cycleFadeDuration options to control timings. Each item in the cycling set can have its own cycleInterval setting that overrides the default setting and affects that item only.

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

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 start without display. Something like:
<img style="display:none;" 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 also use the longdesc attribute as the alternate src reference if you like.)

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

You can add captions to your cycling images. These captions will be centered below the image. Assign a caption by bundling both the img element and span element together inside a div. Like this:
<div style="display:none;"><img data-fb-src="image3.jpg" /><span>text for image3</span></div>
Note that when adding in the span element the "display:none" setting goes on the div wrapper, not on the img element.

You can put floatbox anchors with thumbnails in your cycle set to have a floatbox gallery or slideshow that is coordinated with the cycling thumbs. Such a set looks similar to the basic cycling image set described above, but instead of putting img elements in the set, you put anchors in. Like this: <div class="fbCycler" style="height:100px;">
<a href="image1.jpg" class="floatbox" rev="group:cycle1"><img src="thumb1.jpg" /></a>
<a style="display:none;" href="image2.jpg" class="floatbox" rev="group:cycle1"><img data-fb-src="thumb2.jpg" /></a>
etc...
</div> Notice that "display:none" goes on the anchors and that the thumbnail img elements are using the "data-fb-src" trick to speed load time.

And finally, you can add caption text to your cycling thumbnails by following your thumbnail img element with a span element. Like this:
<a style="display:none;" href="image3.jpg" class="floatbox" rev="group:cycle1"><img longdesc="thumb3.jpg" /><span>text for thumb3</span></a>

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 rev or data-fb-options attribute. When doing this, you need to surround the caption text 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 anchor's title attribute will be used as the caption. Be aware that browsers display an anchor's title as a tooltip when the user mouses over the anchor. If you don't want the tooltip to occur, set your caption using the caption option rather than placing it in the title attribute.

Here's two examples:

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

The captions can include html styles and elements such as <br /> or even <a>nchors if you like. HTML entity characters (& " < >) in a caption will need to be encoded (&amp; &quot; &lt; &gt;) so that browsers can correctly parse your page.

There's an example of an html styled caption in the 'Bonus' section of the demo page.

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 rev attribute to enable and configure the info box.
1) Assign the url that points to the information source using the rev option "info". E.g., info:myInfoPage.html or info:#myInfoDiv
2) Set floatbox options for the secondary info box using the rev option "infoOptions". E.g., infoOptions:`color: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" rev="info:#myInfoDiv infoOptions:`color: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 rev 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.

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 rev tag 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 syntax directly into this rev option, surrounded by backquotes. For example: rev="showPrint:true printCSS:/css/print.css" or rev="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.

Note that 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

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).

Three other options affect index links. Setting showIndexThumbs to false turns off the thumbnail popups within the index links. 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. And you can control the location of the index links with the indexLinksPos 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 "graphicsType" in the floatbox.js file 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, indexLinksPos 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

There's lots of control over floatbox's appearance. You can set the colors, round corners, border sizes, display of controls, shadow effect, transparencies and various animation effects through the configuration options. Most of the General options, some of the Navigation options, and all of the Animation options are for configuring appearance. 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 5 pre-configured color themes that you can use. You can set the preferred color theme for different content types using the 'colorImages', 'colorHTML' and 'colorVideo' options. In addition to these three color settings, you can set a 'color' option on an anchor or in fbPageOptions which will define the color theme for all content types. Available color themes are white, black, blue, red, yellow and custom.

The 'custom' color setting is for creating and using your own customized color scheme for floatbox. Look for "custom.css" in the modules folder and edit the color and background image settings to your liking. If you are using round corners (and you probably are), you will also need to use a graphics editor to modify the custom corner images in floatbox's graphics folder. The four corner graphics files you'll be interested in are cornerTop_custom*, cornerRight_custom*, cornerBottom_custom* and cornerLeft_custom*. The 'r' and 'b' numbers in those file names correspond to the cornerRadius and roundBorder settings you are using. For example, cornerTop_custom_r12_b1.png is in use for the custom color theme if you are using the default cornerRadius of 12 and roundBorder of 1.

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);
}
 You can place the background directive in an external css file together with the appropriate include in the head section of your page, or you can put it directly inside a <style type="text/css"></style> section 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.

If you use a custom background image you may want to set overlayOpacity to 100, or maybe play with lower values to fade the background image. 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 29 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 corrent 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, but setting graphicsType to "international".

Back to Index

Auto-start and exit tasks

You can have floatbox content appear directly on page load by using the autoStart rev option. Put "autoStart:true" into the rev 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 "http://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 a rev tag option string, you must surround the url with backquotes (`) so as not to break parsing of the option string.

Firefox has buggy history/back button behaviour when iframes are on the page. These bugs prevent loadPageOnClose='back' from working when closing iframe content in Firefox. For this reason, it is recommended that you don't use the 'back' instruction when showing iframe (a normal html page) content. The Firefox history bugs do not occur with ajax content and 'back' will work just fine in Firefox if you load your content as type:ajax.

You can set loadPageOnClose in the usual option setting way (fbPageOptions or rev 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).

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, rev and title 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.

Back to Index

Running in iFramed pages

You can run floatbox from iframed pages if you like, and those iframes can be nested as deep as you want. Floatbox.js needs to be included in the root (top) page and on every page in a nested chain down to and including the last child page that has floatbox content on it. For example, if you have a page with iframes nested two deep and floatbox content only in the deepest iframe, you need floatbox.js included in the deep iframe, the parent of that iframe, and the root document. The floatbox.css file has to be included in the root page, but does not need to be on the child iframe pages. (See the iFrames section of the demo page for an example of a floatbox-enabled page with iframes nested two deep.)

Note that browsers restrict cross-site scripting. Floatbox (and any other lightbox-type script) will not be able to function from within an iframe if the top page and iframed child page do not have identical host name portions of their URLs. (You can use framebox.js in these circumstances. See below.)

Back to Index

Constraining floatbox to a particular iFrame

Floatbox normally occupies the entire browser window when displaying content by attaching itself to the top document. You can, if you like, have floatbox appear only inside a particular iframe and constrain itself to the dimensions of that iframe (or to a frameset child document). To do this, include the file framebox.js, instead of floatbox.js, in the head section of the iframe content document and also include floatbox.css.
<link type="text/css" rel="stylesheet" href="/floatbox/floatbox.css" />
<script type="text/javascript" src="/floatbox/framebox.js"></script>
Framebox.js attaches itself to the current window's document, rather than the top document.

Back to Index

Dynamically loading floatbox content via AJAX or UpdatePanel

When floatbox first loads on a page, it runs its tagAnchors function to inventory all the floatbox-enabled anchors and area maps on the page, and to add the required onclick action to those anchors. If you subsequently dynamically update a portion of your page with content from an AJAX fetch, any floatbox-enabled anchors in that content won't be in floatbox's inventory and won't have the required onclick action attached to them. So what you have to do is to run the tagAnchors function against your new content after it arrives.

Your existing AJAX content insertion might look something like this:
if (xmlReq.readyState == 4) {
  document.getElementById('myXmlDiv').innerHTML = xmlReq.responseText;
}

Light up the floatbox anchors in that dynamic content by adding the following two lines after that insertion:
if (xmlReq.readyState == 4) {
  document.getElementById('myXmlDiv').innerHTML = xmlReq.responseText;
  fb.anchors.length = 0;
  fb.tagAnchors(document);
}
 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.

If you are using an ASP.NET UpdatePanel, you can set a callback function to fire the floatbox tagging after your panel has finished updating. Put this javascript on the page:
function pageLoad(sender, args) {
  if (args.get_isPartialLoad()) {
    fb.anchors.length = 0;
    fb.tagAnchors(document);
  }
}

Or... as an alternative to getting the fb.tagAnchors 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 "tagged": <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 rev attribute settings.

Back to Index

Serving gzip compressed files on Apache

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.

The modules folder contains gzipped versions of the .js and .css files in it. 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 you are using folder aliases, you will need to 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>

The two main files, floatbox.js and framebox.js, are not provided in gzip format because you may want to edit the default options section of these files and set things to your liking. If you want to serve gzipped version of these files, first set your default options and then create gzipped versions from the modified js files. (GNU.org - Gzip for Windows)

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 your flash objects. But there's a demand for this information so perhaps the little bit here will help you.

The generic task to be solved is one of getting a click action on your flash object to fire a javascript function on the host page. The specific floatbox task is then the simple one of getting that javascript function to fire floatbox. There are different ways to approach this. I'm giving just one of those ways here, but I think this is a clean way to do it.

Create a button in your flash object. Give it a name. Let's call ours "button1". Now define a click action on the button. In ActionScript 2, you can set the that click action 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 your layer object.

On your flash layer define an action like the following (this is ActionScript 2):
button1.onRelease = function() {
    getURL("javascript:button1Click()");
};

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:button1Click()");
    navigateToURL(request, "_self");
}
button1.addEventListener(MouseEvent.CLICK, myFunc);

That's it. Now you're all done with your flash object. What we've got now is a button that when clicked will fire a javascript function named "button1Click" on the host page. We just need to define that javascript function in the head of our page to do whatever we want when the flash button is clicked. Here you should refer to the floatbox API reference to learn about launching floatbox from javascript.

But here's a hint. If you've got a standard floatbox anchor setup on the page, and you give that anchor a unique id, like "myAnchor", your button1Click function might look like this:
button1Click = function() {
    fb.start('myAnchor');
};

Or... instead of passing the fb.start function an anchor that's setup for floatbox behaviour, you can use the parameterized syntax of fb.start (see the API reference):
button1Click = function() {
    fb.start({ href: 'somePage.html', rev: 'width:xxx height:yyy someOption:someValue' });
};

It's that easy. One word of warning though: Dont' return anything from your js button1Click function or the page will try to navigate to that return value. There's a couple of samples (done a little differently than described here) in the 'Code' section of the floatbox demo page.

Back to Index

Using the library functions

Floatbox exposes many of its internal functions in a way that allows it be used as a small javascript library. 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. For a complete list of available Floatbox functions, please see the API reference.

Back to Index