Floatbox v3.12 - Options

randomous.com



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 page for information on how these options can be configured in the javascript code, in page-specific config functions, on particular <a> elements, via user-preference session cookies, or in a url's query string.

General Options

theme - 'auto'|'black'|'white'|'blue'|'yellow'|'red'|'custom'
Color theme. 'Auto' will use the black theme for images, white for iframe content, and blue for flash and quicktime. Custom is for defining your own styles in the css without overwriting existing themes.

padding - pixels
Width of the area between the floatbox content and the outer floatbox edges.

panelPadding - pixels
Gap above and below the lower panel content (caption and controls), provides the spacing between the main content, panel content, and lower border.

outerBorder - pixels
Width of the outside border around the edge of floatbox.

innerBorder - pixels
Width of the inside border around the edge of the main content.

overlayOpacity - 0-100
Opacity of the full-screen page overly. 0 is fully transparent, 100 is fully opaque.

upperOpacity - 0-100
Sets the opacity of the controls that appear in the transparent overlay on top of image content. These controls are the prev/next navigation buttons if upper navType is set, and the resize button in the top left corner if showResize is set.

dropShadow - true|false
Enables a 3D drop shadow effect on the right and bottom sides of the floatbox.

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

autoSizeOther - true|false
If set to true, html and multimedia content will be resized down to fit the screen if it's initially too large.

resizeImages - true|false
If resizeImages is set to true, images that have been autoSized to fit the screen and images that are displayed larger than the current screen size can be resized using the resize tool.

resizeOther - true|false
If resizeOther is set to true, html and multimedia content that has been autoSized to fit the screen 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.

showCaption - true|false
Controls display of the caption shown in the lower left of floatbox. This just turns it on or off. See the "caption" option down below for details on how to set the 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.

hideFlash - true|false
If true, flash objects on the host page will be hidden before floatbox loads. This is generally a good idea as some flash objects will appear on top of the floatbox display if not hidden. Flash objects using the default wmode of "window" have this problem (feature?). Flash with a wmode of "opaque" or "transparent" will not appear over top of all the other content.

hideJava - true|false
Just like hideFlash 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.

enableCookies - true|false
If true, session cookies can be used to set and remember option preferences. You'll want to set this to false if you are setting up floatbox and testing option changes, otherwise the old options will get stuck in the cookies and you won't see the effect of your changes without a browser restart. Set this to true if you have a cookie-based way for users to select display preferences on your pages.

cookieScope - 'site'|'folder'
Determines if options set via session cookies will apply across your entire site or only to the folder (and its subfolders) containing the floatboxed page. Note that if you have a framed or iframed page heirarcy that pulls content in from different folders, you will need the 'site' option to have the cookies take effect in each frame.

Navigation Options

navType - 'upper'|'lower'|'both'|'none'
Sets the type of navigation controls to display. 'upper' is the "Prev/Next" image overlay.' 'lower' gives "<<prev||next>>" on the lower panel. Upper navigation is not available for html and multi-media content, just for images.

upperNavWidth - 0-50
Sets the width in percentage of each of the left and right transparent upper 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 enable 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 to resize.

upperNavPos - 0-100
When the mouse is active over an image with navType 'upper' 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 pushes them off the bottom of the image.

showUpperNav - 'always'|'once'|'never'
Controls display of the upper 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 upper nav graphics are turned off upper 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 the upper nav graphics are turned off, the lower 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.

Animation Options

doAnimations - true|false
Shorthand for resizeDuration=0, imageFadeDuration=0 and zoomImageStart=false.

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 the anchor when closed. If false, floatbox will start and end from the center of the screen.

startAtClick - true|false
If true (and resizeDuration is not 0) floatbox will expand out from the clicked anchor and shrink back to the 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.

Slideshow Options

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.

pauseOnResize - true|false
If set to true, the slideshow will pause when the current content is resized through use of the resize tool.

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.

Configuration Options

The options in this section can only be set or changed directly in the floatbox.js code. They have no effect if set through rev attributes or the page-level setFloatboxOptions function.

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.

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 it's 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.

urlGraphics
This is the path to the floatbox graphics folder and is used to find the 404 image and the custom cursors for the resize tool. If you install floatbox somewhere other than the default install location you will need to change this setting to the new path. Use an absolute path so that it will work regardless of where on your site your floatbox enabled content page resides.

urlLanguages
This is the path to the floatbox languages folder and is needed so that floatbox can find its language json files. If you install floatbox somewhere other than the default install location you will need to change this setting to the new path. Use an absolute path so that it will work regardless of where on your site your floatbox enabled content page resides.

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. These options are intended to be set from the rev attribute of a floatbox enabled <a> element, or from the page-specific setFloatboxOptions() function in the head section of the host page.

doSlideshow - true|false
If set to true, images in a gallery collection will be launched as a slideshow even if their rel attributes describe them as belonging to a gallery collection.

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

type - 'img'|'flash'|'quicktime'|'ajax'|'inline'|'iframe'
Floatbox auto-detects content type based on the href file extensions, 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. Another possibility is flash content that does not have the .swf file extension and so needs the "type:flash" option set.

caption
To display a caption in floatbox, you can use the title attribute of an <a> element or set a 'caption' option in its rev attribute. Setting it as a rev option allows you to have a different or no tooltip for the anchor mouse-overs, 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`"

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

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. The 'back' option can be used in conjunction with autoStart:true to present a floatbox display that returns to its origin when complete. 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.

width, height - pixels
Width and height set in the rev tags of iframe items control the size of that iframe content. These are pixel values - percentages are not supported. A typical rev tag holding dimension info might look like this: rev="width:360 height:240". For compatability, you can also use the css-like syntax of rev="width:360px; height:240px;" or the querystring-like syntax of rev="width=360&height=240". One or both of width and height can be set to 'max' to fit the user's browser's current window width and/or height. Note that the width and height options can apply to images, but they're intended for iframe 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.

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 for more details.

infoOptions - option string
Used in conjunction with the info option, this allows assigning configuration options to the info box using standard rev tag option syntax. Wrap the infoOptions in backquotes for correct parsing and see the instructions for more details.

infoText - string
Replaces the default text "Info..." (or the translated equivalent) used for the info box link with text of your choice.