Floatbox v3.54 - Options
Floatbox provides versatility in how it can be configured and used through numerous configuration options and a variety of ways and locations to set those options. This page gives information about the configuration options. See the instructions for information on how these options can be configured in the javascript code, in page-specific settings, and on particular <a> elements.
General Options
padding - pixels
Width of the area between the floatbox content and the outer floatbox edges.
panelPadding - pixels
Gap above and below the info and control panels. Provides the vertical spacing between the floatbox outer edge, panel content, and main content.
overlayOpacity - 0-100
Opacity of the full-screen page overly. 0 is fully transparent, 100 is fully opaque.
shadowType - 'drop' | 'halo' | 'none'
Set 3D shadow effect.
'drop' sets a 2-sided shadow on right and bottom.
'halo' sets a 4-sided shadow on all sides.
shadowSize - 8 | 12 | 16 | 24
Sets the size in pixels of the 3D drop or halo shadow.
roundCorners - 'all' | 'top' | 'none'
Enables round corners on all corners, on just the top two, or 'none' disables all round corners (and you get square ones).
cornerRadius - 8 | 12 | 20
When round corners are enabled, this defines the corner radius in pixels.
roundBorder - 0 | 1
With round corners, you can have a 1px border around the outside box edge if roundBorder is set to 1.
outerBorder - pixels
When round corners are turned off (roundCorners: 'none'), this defines the width of the border around the outside edge of the square box.
innerBorder - pixels
Width of the inside border around the edge of the main content.
autoFitImages - true | false
If set to true, large images will be proportionately scaled down to fit the current browser window dimensions before being displayed.
Use this in conjunction with the resizeImages and resizeTool options.
resizeImages - true | false
If resizeImages is set to true, images that have been autoSized to fit the screen, that have been resized with drag-resizing, or are displayed larger than the current screen size can be resized using the resize tool.
autoFitOther - true | false
If set to true, html and multimedia content will be resized down to fit the screen if it's initially too large.
resizeOther - true | false
If resizeOther is set to true, html and multimedia content that has been autoSized to fit the screen, that has been resized with drag-resizing, or is displayed larger than the current screen size can be resized using a small button in the top left corner.
resizeTool - 'cursor' | 'topleft' | 'both'
Sets the tool used when resizeImages is true.
The cursor tool enables clicking on the image to resize and displays a magnifying glass to show when resizing is allowed.
The topleft tool is a small semi-transparent button in the top left corner of the image.
Resizeable non-image content always uses the top-left button.
captionPos, caption2Pos, infoLinkPos, printLinkPos, newWindowLinkPos, itemNumberPos, indexLinksPos - 'tl'|'tc'|'tr'|'bl'|'bc'|'br'
These options control the positioning of the various widgets that can appear in the floatbox border area.
See the 'layout' section of the instructions for more detail if required.
Values are short-hand for top-left, top-center, top-right, bottom-left, bottom-center and bottom-right.
controlsPos - 'tl' | 'tr' | 'bl' | 'br'
Sets the positioning of the control panel in the floatbox frame.
The control panel is the grouping containing control widgets like the close button, <<prev||next>>, etc.
Values are short-hand for top-left, top-right, bottom-left and bottom-right.
centerNav - 0-100
The controls are positioned in one of the boxes corners. Usually the < prev || next > controls are right beside the close button.
With this option you can move the nav controls to the center of the top or bottom border area, away from the close button.
colorImages, colorHTML, colorVideo, color - 'black' | 'white' | 'blue' | 'yellow' | 'red' | 'custom'
Default color scheme to use for the different content types. Defaults are black for images, white for html content, and blue for video.
Custom is for defining your own styles in the css without overwriting existing the other color schemes.
You can override the default color scheme for all content types by setting the 'color' option either in an anchor's rev options or in the page-specific fbPageOptions or fbClassOptions definitions.
boxLeft, boxTop - 'auto' | pixels | '[-]xx%'
By default, the main floatbox frame will be centered in the viewable browser screen area (with a little offset toward the top).
The boxLeft and boxTop options can be used to override this default positioning.
If set to simple integers, those integers will be taken as pixel values to place the floatbox at.
These pixel values are relative to the browser window, like fixed positioning, and not to the underlying document.
These options can also be set to percentage values such as '-50%'.
This will cause the floatbox frame to shift position that portion of the available free space.
For example, a boxLeft setting of '-50%' will move floatbox half way to the left edge of the browser window.
To use default centering, set boxLeft and boxTop to 'auto'.
enableDragMove - true | false
If true, floatbox can be dragged around the screen by holding down the left mouse button on the floatbox frame outside of the main content area.
stickyDragMove - true | false
In sets of multiple floatbox items (galleries), if strickyDragMove is false the dragged location is not retained when navigating to the next item.
Floatbox will return to its centered position with each new item.
When stickyDragMove is true, floatbox remembers its new screen position acress item change-overs.
enableDragResize - true | false
If true, a small resize widget will be shown in the bottom right corner that people can drag with the mouse to resize the box.
Note that multimedia items (direct flash, etc.) will not show the resize widget because these items do not resize with the box window.
stickyDragResize - true | false
As with stickyDragMove, stickyDragResize instructs floatbox to remember dragged size change between different items in a gallery.
draggerLocation - 'frame' | 'content'
The widget that is shown when enableDragResize is true can be placed either in the bottom right corner of the floatbox frame
or the bottom right corner of the actual content by setting this option.
minContentWidth, minContentHeight - pixels
Restricts the minimum size that a box can be dragResized to, because really tiny boxes just look dumb, and if it goes all the way to 0x0 the box can fall apart.
centerOnResize - true | false
When set to true, floatbox will reposition itself toward the center of the screen when the browser window is resized.
titleAsCaption - true | false
True by default, the instructs floatbox to display an anchor's title attribute as its caption when no caption value is explicitly set.
Turn this behaviour off by setting titleAsCaption to false.
See the 'caption' and 'caption2' options down below for details on how to set caption content.
showItemNumber - true | false
Controls display of the 'image/page x of y' text that appears below the caption.
Note that the text displayed is configured in the imageCount and iframeCount language localization options.
showClose - true | false
Enables/disables display of the close button in the bottom right corner.
showNewWindowIcon - true | false
This works in conjunction with the showNewWindow option that is described below.
Set showNewWindowIcon to false to disable display of the small icon beside the 'Open in new window' text.
closeOnNewWindow - true | false
When set to true, floatbox will end (close) when the newWindow link (described below and in the instructions) is clicked.
cacheAjaxContent - true | false
If you are loading floatbox content via ajax and that content is static, you can speed up performance of subsequent gets by setting cacheAjaxContent to true.
hideObjects - true | false
If true, objects and embeds (flash, quicktime, silverlight, etc.) on the host page will be hidden before floatbox loads.
This is generally a good idea as most objects will appear on top of the floatbox display if not hidden.
Flash objects using the default wmode of 'window' have this problem (feature?).
If you set your flash obejcts to have a wmode of 'opaque' or 'transparent' they will not appear over top of the other content
and you won't need to enable hideObjects.
hideJava - true | false
Just like hideObjects but for Java applets.
disableScroll - true | false
If true, floatbox will use fixed positioning.
Fixed positioning locks floatbox in a fixed screen location that will not move in response to scrollbar actions.
Because scrolling is not available when fixed positioning is used, it is not set if the current displayed content is larger than the available screen dimensions.
Note that fixed positioning is always set for iframe and quicktime content in firefox 2 (if it fits the screen) to workaround some display issues with that browser,
and it is never set for IE6 because IE6 can't do it.
randomOrder - true | false
Gallery sets of multiple items normally are ordered by their position in the html document they come from.
By setting randomOrder to true, you can shuffle your gallery sets to a random order.
This can be a nice touch for some slideshows.
printCSS - css text | css filepath
When showPrint is enabled (see below), you may need to provide some css to format the print content the way you like.
You can provide css settings directly as text. For example, printCSS:`h3 {color: red;} a img {border: 2px solid black;}`.
Or you can set printCSS to the path of an external css file and this will be applied to the print window contents.
E.g., printCSS:myPrint.css.
preloadAll * - true | false
If true, floatbox will aggressively preload all images that are referenced by floatboxed anchors.
This makes floatbox quite responsive as images are available and can be displayed as soon as the site visitor clicks on or navigates to one.
If you wish to lighten your server load, you can set preloadAll to false.
In this event, the first image found will be preloaded and the next image in a group will be loaded right after the display of the current image, but the others will not be fetched.
The site visitor may then have to wait for the loading of clicked item.
autoGallery * - true | false
AutoGallery is used to turn a page of links to images into a floatbox gallery without setting the class="floatbox" attribute on each anchor.
To exclude one or more image links from the autoGallery group, put a rel attribute on the anchor elements of rel="nofloatbox",
or assign a class of "nofloatbox" to the anchor.
Activate auto-gallery functionality by setting autoGallery to 'true' in the floatbox.js default options section
or by using the fbPageOptions javascript object in your page's head section.
This would look something like:
<script type="text/javascript">
fbPageOptions = {
autoGallery: true,
autoTitle: 'Optional title (caption) to appear on every image in the floatbox gallery set'
};
</script>
autoTitle * - 'string'
When autoGallery is enabled, you can set a floatbox caption for all images on the page by assigning a string to the autoTitle option.
(Existing title attributes on anchors take precedence over the autoTitle.)
language * - 'auto' | 'en' | ... (see the languages folder)
Floatbox provides international localization through the json files in the languages folder.
When the language option is set to 'auto', floatbox will detect the visitor's browser language preference and use that language for its tooltips and other text.
You can force a particular language by seeting it here.
Doing this will set that language for everyone visisting your site, regardless of where they are coming from.
graphicsType * - 'auto' | 'international' | 'english'
graphicsType is closely related to the language option.
When set to 'auto', visitors with localized English language browsers will see the floatbox control graphics that contain English text such as "close" and "next"
while non-English browser users will see graphics-only controls without the English text on them.
You can force all browsers to see the graphics-only controls by setting graphicsType to 'international', or force English controls with the 'english' option.
* The 5 options marked with asterisks in the section above can not be set from rev or data-fb-options values in an anchor. They can be set only from the floatbox.js code or a page-specific fbPageOptions javascript object.
Animation Options
doAnimations - true | false
Setting doAnimations to false is a short-hand way of setting resizeDuration, imageFadeDuration and overlayFadeDuration all to 0.
resizeDuration - 0-10
Controls the speed at which animated resizing occurs.
0 = no resize animation, 1 is fast, 10 is slooow.
These are unit-less numbers, and don't equate to a fixed time period.
Larger size changes will take longer than smaller size changes.
imageFadeDuration - 0-10
Controls the speed of the opacity fade-in for images as they come into the display.
0 = no image fade-in, 1 is fast, 10 is slooow. These too are unit-less numbers.
overlayFadeDuration - 0-10
Controls the speed of the opacity fade-in and fade-out for the translucent overlay which covers the host page.
0 = no overlay fading in or out, 1 is fast, 10 is slooow. Unit-less.
startAtClick - true | false
If true (and resizeDuration is not 0) floatbox will expand out from the clicked anchor and shrink back to that anchor when closed.
If false, floatbox will start and end from the center of the screen.
zoomImageStart - true | false
If true (and resizeDuration is not 0) images will expand out from the clicked thumbnail on start and collapse back to the thumbnail on exit.
liveImageResize - true | false
If true (and resizeDuration is not 0) images will remain displayed while they are being resized.
If false they will be hidden during a resize and the "loading" gif displayed in their place.
splitResize - 'no' | 'auto' | 'wh' | 'hw'
Default animated resizing of floatbox resizes width, height, top and left simultaneously.
The settings other than 'no' give sequenced animation where the X and Y dimensions are resized seperately.
The two options 'wh' and 'hw' force either width or height to always go first.
The better splitResize option is probably 'auto'. This will always do the smallest dimension first.
Using a splitResize of auto prevents unaesthetic resize behaviour of initially bloating up in the larger dimension.
cycleInterval - seconds
The number of seconds between each turnover of the displayed image in a set of cycling images or thumbnails.
cycleFadeDuration - 0-10
Controls the speed of the fade in/out of the images in a set of cycling images or thumbnails.
1 is really fast, 10 is slow. Unit-less.
Navigation Options
navType - 'overlay' | 'button' | 'both' | 'none'
Sets the type of navigation controls to display.
'overlay' is the "Prev/Next" image overlay.'
'button' gives "<<prev||next>>" in the controls area of the floatbox frame.
Overlay navigation is not available for html and multi-media content, just for images.
navOverlayWidth - 0-50
Sets the width in percentage of each of the left and right transparent overlay nav panels that provide navigation through mouse clicks on the displayed image.
If set to 50, each panel will be half the image width and so will meet without a gap in the middle.
40 leaves a 20% gap between panels, etc.
If image resizing is enabled and you're using the cursor tool, you'll want to leave a gap between the nav panels so that there's somewhere to click for resizing.
navOverlayPos - 0-100
When the mouse is active over an image with navType 'overlay' or 'both' set, small prev/next graphics are displayed.
This setting is the percentage height from the image top that these graphics will appear.
0 puts them right at the top, and 100 places them at the bottom of the image.
showNavOverlay - 'always' | 'once' | 'never'
Controls display of the overlay navigation prev and next graphics.
If set to 'once', these graphics will be displayed only for the first image shown, after which they are turned off.
When the overlay nav graphics are turned off overlay nav still works, it is just not displayed.
The idea is that once people are told what the mouse does over the image, they don't need to keep seeing the prev/next graphics continuously.
When both the overlay and button nav types are enabled, the button nav controls will highlight as the mouse moves over active image areas.
showHints - 'always' | 'once' | 'never'
Controls display or mouseover tooltip messages for the nav and control buttons.
These tooltips are intended to be used to inform users about keyboard navigation shortcuts.
If set to 'once', each tooltip will deactivate after it has been displayed for sufficient time to be read.
They will also be deactivated if the user navigates with the associated keyboard shortcut.
enableWrap - true | false
Enables gallery wrapping so that selecting 'next' on the last item wraps to the first, and selecting 'prev' on the first item wraps to the last.
Because gallery viewing can start anywhere in a series of images, it is probably a good idea to leave this set to true in most circumstances.
But if you are displaying something like a series of instructions that always starts with item #1 you may want to turn wrapping off.
The enableWrap option affects only mouse and keyboard navigation.
Even when enableWrap is set to false, a slideshow will wrap if started with an item other than #1 or if the slideshow endTask is set to 'loop'.
enableKeyboardNav - true | false
Enables or disables the keyboard handler for prev, next, pause/play, resize and close actions.
If you disable keyboard nav you should also set showHints to 'never' or change the default text displayed in the hints.
outsideClickCloses - true | false
If set to true, floatbox will exit when the user clicks on the page overlay outside of the floatbox display.
imageClickCloses - true | false
If set to true, floatbox will exit when the user clicks on the displayed image.
When the navigation overlay is active (navType = overlay or both), the click-to-close space is the space left between the left and right navigation areas.
numIndexLinks - number
Index links are a grouping of numbered links that will jump floatbox to the selected item when clicked.
They look like this: "1 2 3 4 5 ..."
If set to 0, no index links will be shown.
If set to -1 or to a number greater than the number of items in a gallery group, all index links will be shown - one for each item in the gallery group.
If set to a positive integer less than the number of gallery items, only that number of links will be shown.
For example, if maxIndexLinks = 9 for a 99 item gallery you get something like
"1 ... 12 13 14 15 16 17 18 ... 99"
showIndexThumbs - true | false
Controls the display of popup thumbnails in the indexLinks group.
If true, thumbnail popups will be displayed when an index link is hovered.
maxIndexThumbSize - pixels
The popup thumbnails used in the index links are taken from the img elements inside the associated anchor on your base page.
These thumbnails may be larger than you would like to see for the index links popup thumbnails.
You can limit the popup size by setting maxIndexThumbSize to the pixel size you want the thumbnail's largest dimension restricted to.
If maxIndexThumbSize is 0, the index link thumbnails will be shown at their native size.
Slideshow Options
doSlideshow - true | false
If set to true, images in a gallery set will be launched as a slideshow.
slideInterval - seconds
This is the number of seconds to display each image in a slideshow before moving on to the next one.
endTask - 'stop' | 'exit' | 'loop'
Describes what to do when all images in a slideshow have been seen.
Note that if a slideshow was started on other than the 1st image, it will wrap around until all images have been seen before acting on the endTask directive.
showPlayPause - true | false
Turns display of the slideshow play & pause controls on or off.
startPaused - true | false
If true, a slideshow will start in a paused state. If false, the slideshow will auto-play on start.
pauseOnPrev - true | false
If set to true, the slideshow will pause when a 'prev' contol is clicked or when the corresponding keyboard action (left arrow) is fired.
pauseOnNext - true | false
If set to true, the slideshow will pause when a 'next' contol is clicked or when the corresponding keyboard action (right arrow) is fired.
pauseOnResize - true | false
If set to true, the slideshow will pause when the current content is resized through use of the resize tool.
Other
Options in this section are not available to be set in the floatbox.js code because they don't make sense as global or default settings. The ones marked with an asterisk* can be set only in the rev or data-fb-options attribute of a floatbox enabled <a> element. Options without an asterisk can be set on the individual anchors or in an fbPageOptions (or fbClassOptions or fbChildOptions) definition.
group * - string
Anchors that have the same group option set on them will form a gallery set that can be navigated with the prev/next buttons or shown as a slideshow.
width, height * - pixels | 'xx%' | 'max'
Width and height set in rev tags control floatbox content size.
All floatboxed links that load anything other than a standard image should have width and height defined.
Plain integers are the size in pixels.
If a percentage is given, like "85%", floatbox will be sized to that portion of the available browser display area.
One or both of width and height can be set to 'max' to size the content to the current browser display width and/or height.
A typical rev tag containing dimension settings might look like this: rev="width:360 height:240" or rev="width:55% height:max".
For compatability with pages already configured for other lightbox clones, you can also use the css-like syntax of rev="width:360px; height:240px;".
Note that the width and height options can apply to images, but they're intended for html and multimedia content.
You are better off autoSizing images as that will maintain the correct proportions.
scrolling * - 'auto' | 'no'
The scrolling option applies only to iframe content and controls the display of the scroll bars in the iframe.
If no scrolling value is present, the default of 'auto' is used, which presents scrollbars if they are required and leaves them off if they are not.
Setting "scrolling:no" in the rev tag will disable scrollbars for that iframe content, whether that content fits its window or not.
caption, caption2
To display a caption in floatbox, you can use the title attribute of an <a> element when titleAsCaption is set to true,
or you can set a 'caption' option in the anchor's rev attribute.
Setting it as a rev option allows you to have a different or no tooltip for the anchor mouse-overs, lets you use html markup in your caption, and is the recommended approach.
In the rev option, the text of the caption option must be surrounded by backquote characters (`) so as not to break parsing of the option string.
Example: rev="caption:`This is my kool kaption`"
A second caption can be assigned to a floatbox item by setting 'caption2' in the same manner as 'caption'.
type * - 'ajax' | 'img' | 'inline' | 'iframe' | 'flash' | 'quicktime' | 'wmp' | 'silverlight'
Floatbox auto-detects content type based on the href file extension, but there are occasions where auto-detection can't work.
One example is content that is to be loaded via AJAX. To load AJAX content, you need to set "type:ajax" in the anchor's rev attribute.
You may also need to set the type option for images that do not have a standard image file extension but are delivered by mime type.
showThis * - true | false
An element with "showThis:false" in its rev attribute will not be added to a gallery, slideshow or iframe collection.
However, other options set in the rev tag will take effect.
The showThis option is there primarily to enable a clickable link to display a gallery as a slideshow.
Such a link would have at least the following in its rev tag: rev="showThis:false doSlideshow:true".
sameBox * - true | false
The default behaviour when floatboxed content is invoked from inside an existing floatbox is to display the new content in a new secondary floatbox over top of the existing one.
Use sameBox:true to cause the new content to replace the existing content within the existing floatbox.
info * - url
Assigning a url to the info option will make floatbox display an "Info..." link that will load url in a new secondary floatbox.
See the instructions and demo for more details.
infoOptions - option string
Used in conjunction with the 'info' option, this allows assigning configuration options to the secondary info floatbox using standard rev tag option syntax.
Wrap the infoOptions in backquotes for correct parsing and see the instructions and demo for more details.
infoText - string
Replaces the default text "Info..." (or the translated equivalent) used for the info link with text of your choice.
For example, if you're displaying EXIF information through the info option, you may want to set infoText to "EXIF..."
showPrint - true | false
If showPrint is set to true, a "Print..." link will be shown in the floatbox border area.
This print link invokes a print dialog that will print just the floatbox contents, not the underlying page.
(The "Print..." text is translated/regionalized in the language files.)
See the printCSS option above for how to pass css stylings to the print content.
showNewWindow - true | false
If showNewWindow is set to true, a "Open in a new window" link will be shown in the floatbox border area.
Clicking this link will open a new browser window or tab with the floatbox content loaded as an ordinary page.
("Open in a new window" is translated/regionalized in the language files.)
Use the showNewWindowIcon and closeOnNewWindow options described above in conjunction with showNewWindow.
href * - url
An "href:`...`" option set in the rev tag will override the href defined on the anchor.
Floatbox will use the rev tag href, while browsers with javascript disabled will load the 'real' href.
This can be used to provide alternate content for javascript-disabled clients.
There's an example in the instructions.
sizeRatio * - 'width/height'
The sizeRatio option allows you to show an item at the maximum size that will fit in the browser window
while also retaining proportional width and height ratios. For example: "sizeRatio:4/3"
proportionalResize * - true|false
When enableDragResize is true, images always resize proportionally. This option allows you to set proportional resizing on non-image items as well.
autoStart * - 'once' | true | false
If you place "autoStart:true" in the rev attribute of a floatbox enabled <a> element the associated image or iframe will be automatically started on host page load without the user clicking on any content.
An autoStart setting of 'once' will cause that item to auto-display in floatbox only on the first load of the host page per browser session.
Note, you can also set autoStart in the page's query string as described in the instructions.
loadPageOnClose - 'self' | 'back' | url
This controls browser behaviour when floatbox closes.
If set to the string 'self', the host page will be refreshed on exit.
If set to 'back', the previous page in the browser's history list will be loaded.
(Please see the 'Auto-start and exit tasks' section of the instructions for details of a Firefox bug which can interfere with 'loagPageOnClose:back'.)
If loadPageOnClose is set to a string other than 'self' or 'back', that string 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.
minFlashVersion - version string
When direct-loading flash, you can require that a minimum version of flash is installed on the visitor's browser.
If the required version is not present, floatbox will show a language-localized message to that effect and present a link for getting the latest flash version.
The version string must include the major version number and may include the minor and revision numbers.
For example, '10', '10.0' and '10.0.22' are all valid version strings.
afterFBLoaded, beforeBoxStart, afterBoxStart, beforeItemStart, afterItemStart, beforeItemEnd, afterItemEnd, beforeBoxEnd, afterBoxEnd, beforePrint, afterPrint - function
These are callback functions that you can define in fbPageOptions or as rev/data-fb-options values. See the API reference for details.