Options

 

There are a number of options available, which can be set on per-Dock basis.
None of the options are mandatory.

Example:

Option Default Type Description
active1.6 -1 integer

This designates one of the menu’s elements to be fully expanded when the dock is initialised. The option takes a zero-based index of the position of the desired menu element (image) within the dock – so if you want the 4th of 6 images to be expanded, set active:3.

Data attribute2.0.0 : data-jqdock-active

Warning : There are consequences to using this option, which might possibly only become apparent when you try it. I have provided it because it has specifically been requested, but … if you set a mid-menu image initially active, and the user then enters the dock at either end, it is quite likely that the dock will simply collapse to its ‘at rest’ state because the resultant animation takes the mouse off the dock!

align ‘bottom’ string

Values : ‘top’, ‘middle’, ‘bottom’, left’, center’, ‘right’.

Fixes the horizontal/vertical main axis, and direction of expansion.

For a horizontal menu:

  • ‘top’ : fixes the top edge of the dock, so that images expand down
  • ‘middle’ : fixes the middle of the images, so that images expand up and down equally
  • ‘bottom’ : fixes the bottom edge of the dock, so that images expand up

For a vertical menu:

  • ‘left’ : fixes the left edge of the dock, so that images expand right
  • ‘center’ : fixes the center of the images, so that images expand left and right equally
  • ‘right’ : fixes the right edge of the dock, so that images expand left

Data attribute2.0.0 : data-jqdock-align

bias1.7 50 integer

Percentage bias on middle and center alignment expansions.

Prior to v1.7 – and still by default – the expansion of a ‘middle’ or ‘center’ aligned menu is 50/50 out from the mid-point. The bias option allows you to change that ratio by specifying the percentage of the expansion (0-100) to be allocated to the leading edge. (For align:’middle’, the leading edge is the top edge; for align:’center’, it’s the left).

For example, specifying options of {align:’center’, bias:75} would result in 75% of any expansion of a menu item being to the left of the vertical mid-point of the Dock. Similarly, options of {align:’middle’, bias:25} would place 3/4 of any expansion below the horizontal mid-point of the Dock.

A couple of points to note:

  1. Bias only has any effect when the align option is set to either ‘middle’ or ‘center’
  2. Bias has a range of 0-100, but a value of 0 (or less) or 100 (or more) will automatically change the middle/center alignment as follows (because they are exact equivalents) …
    • {align:’middle’, bias:0} => {align:’top’}
    • {align:’middle’, bias:100} => {align:’bottom’}
    • {align:’center’, bias:0} => {align:’left’}
    • {align:’center’, bias:100} => {align:’right’}

Data attribute2.0.0 : data-jqdock-bias

capSizing2.0.0 false boolean

Set this if you want the size and sizeMax options to behave as a ‘cap’ instead of an absolute value (which is the default behaviour). A ‘cap’ is only applied when the value being tested (a dimension) is greater than the target value (the value of the option). The default behaviour simply sets the test value to the target value regardless.

Data attribute2.0.0 : data-jqdock-cap-sizing

coefficient 1.5 number

Attenuation coefficient. This controls the relationship between the distance from the cursor and the amount of expansion of any affected image within that distance. A coefficient of 1 makes the expansion linear with respect to distance from cursor; a larger coefficient gives a greater degree of expansion the closer to the cursor the affected image is (within distance).

Data attribute2.0.0 : data-jqdock-coefficient

distance 72 integer

Attenuation distance from cursor, ie the distance (in pixels) from the cursor that an image has to be within in order to have any expansion applied. Note that attenuation is always calculated as if the Dock was ‘at rest’ (no images expanded), even though there may be expanded images at the time.

Data attribute2.0.0 : data-jqdock-distance

duration 300 integer

The duration (in milliseconds) of the initial ‘on-Dock’ expansion, and the ‘off-Dock’ shrinkage.

Data attribute2.0.0 : data-jqdock-duration

fadeIn1.3 0 integer

The amount of time (in milliseconds) for the initial fade-in of the Dock after initialisation. By default this is set to 0 (zero), which means that the Dock is displayed in full as soon as it can be ( = show() ).
There may be occasions when a ‘softer’ presentation of the Dock is desirable, and setting fadeIn to, for example, 400 would fade the Dock in over that period.

Data attribute2.0.0 : data-jqdock-fade-in

fadeLayer1.4 empty string

Values : ‘wrap’, ‘dock’.

By default the fade-in effect (see fadeIn above) is applied to the original target menu element. By specifying either ‘wrap’ or ‘dock’ here, the fade-in element can be switched to the child or grand-child (ie. div.jqDockWrap or div.jqDock, respectively) of the original target menu element. This option only has any effect if fadeIn is set, and is really only useful for cases where, for example, background colours have been styled on the original menu element or div.jqDock, and you don’t want them to be faded in.

Data attribute2.0.0 : data-jqdock-fade-layer

flow1.5 false boolean

If set, this alters the default dock behaviour such that the Dock is not auto-centered and the wrap element (.jqDockWrap, which is relatively positioned) expands and collapses to precisely contain the Dock (.jqDock); this allows elements positioned around the docked menu to adjust their own relative position according to the current state of the docked menu.

Data attribute2.0.0 : data-jqdock-flow

Warning : Unless you provide your own mechanism for centering the Dock, there may consequences to using this option which might only become apparent when you try it : with flow enabled, if you aim your mouse at a specific menu option you will probably find that quite often you don’t stay on that option without having to move the mouse again!

idle1.5 0 integer

The period of time (in milliseconds) after the mouse has left the menu (without re-entering, obviously!) before the Dock attempts to go to sleep. Please read – and be sure that you understand – the Advanced documentation before setting a value for this option.

Data attribute2.0.0 : data-jqdock-idle

inactivity1.3 0 integer

The period of time (in milliseconds) after which the Dock will shrink if there has been no movement of the mouse while it is over an expanded Dock.

Data attribute2.0.0 : data-jqdock-inactivity

labels false boolean or string

Values : true, ‘tl’, ‘tc’, ‘tr’, ‘ml’, ‘mc’, ‘mr’, ‘bl’, ‘bc’, ‘br’.

This enables/disables display of a label on the current image. Allowed string values are 2 characters in length: the first character indicates horizontal position (t=top, m=middle, b=bottom) and the second indicates vertical position (l=left, c=center, r=right). So ‘br’ means bottom-right!

If simply set to true, jqDock will use its default positioning for the label, which is ‘tl’ (top-left) for any align setting other than ‘top’ or ‘left’. The defaults for ‘top’ and ‘left’ alignment are ‘br’ (bottom-right) and ‘tr’ (top-right) respectively.

To determine the text for the label, jqDock looks firstly for text in the image’s ‘title’ attribute; if not found, it will then look for text in the ‘title’ attribute of the parent link – if there is one – and use that if found.

Please be aware that enabling this option with one of the middle/center label positions (eg. ‘ml’, ‘bc’, etc) may have a slight effect on the performance of the Dock, simply due to the additional processing required to position the label correctly.

Data attribute2.0.0 : data-jqdock-labels

loader depends on jQuery version & browser string

Values : ‘image’, ‘jquery’.

This overrides the default image loader used by jqDock. Depending on the browser, jqDock uses an image loader based on either “new Image()”, or the jQuery HTML constructor “jQuery(‘<img />’)…”. If your Dock is not being displayed, and you have triple checked all your image paths, try setting this option to ‘image’ or ‘jquery’ to override the default loader.

Note: As of jQuery v1.9, support for $.browser has been removed. As a consequence, if you are using jQuery v1.9 or later, loader will always default to ‘jquery’ (regardless of browser).

Data attribute2.0.0 : data-jqdock-loader

noAntiFlutter2.0.0 false boolean

If you set this, jqDock will bypass (skip) the code that attempts to reduce the impact of ‘flutter’ that can occur.

‘Flutter’ is caused by an oscillation between calculated dimensions, where a change to a small dimension affects a larger dimension, which then causes the smaller dimension to be re-calculated to a very slightly different result! jqDock attempts to overcome this by checking for repeats of calculated results, but on large menus this checking may have an adverse impact so I have provided the ability to disable it.

Data attribute2.0.0 : data-jqdock-no-anti-flutter

noBuffer1.6 false boolean

By default, while the dock is asleep the most recent mouse event is buffered, and when the dock is nudged awake that buffered event is used and acted upon – before any other mouse event that might occur subsequent to the ‘nudge’. Setting the noBuffer option to true will prevent buffering of the mouse events.

Data attribute2.0.0 : data-jqdock-no-buffer

onReady1.5 zero function or boolean false1.9

Function called after jqDock has completed initialisation and is ready to reveal the Dock. The called function is given the scope (this) of the original menu element, and may return false to prevent the Dock being revealed. Please refer to the Advanced documentation.

As of v1.6, the function is passed a single string argument of ‘ready’1.6; prior to v1.6, the function receives no arguments.

As of v1.9, a boolean value of false can supplied to the option, which is merely a convenience shortcut to a jqDock internal function that always returns false.

Data attribute2.0.0> (only if setting false!) : data-jqdock-on-ready

onSleep1.5 zero function or boolean false1.9

Function called when the Dock is about to go to sleep. The called function is given the scope (this) of the original menu element, and may return false to prevent the Dock going to sleep. Please refer to the Advanced documentation.

As of v1.6, the function is passed a single string argument of either ‘sleep’1.6 or ‘freeze’1.6, depending on how the dock was put to sleep; prior to v1.6, the function receives no arguments.

As of v1.9, a boolean value of false can supplied to the option, which is merely a convenience shortcut to a jqDock internal function that always returns false.

Data attribute2.0.0 (only if setting false!) : data-jqdock-on-sleep

onWake1.5 zero function or boolean false1.9

Function called when the Dock is about to wake up from sleep. The called function is given the scope (this) of the original menu element, and may return false to prevent the Dock waking up. Please refer to the Advanced documentation.

As of v1.6, the function is passed a single string argument of either ‘wake’1.6 or ‘thaw’1.6, depending on how the dock was put to sleep; prior to v1.6, the function receives no arguments.

As of v1.9, a boolean value of false can supplied to the option, which is merely a convenience shortcut to a jqDock internal function that always returns false.

Data attribute2.0.0 (only if setting false!) : data-jqdock-on-wake

permanentLabels2.0.2 false boolean

If you set this, jqDock will initially show, but never hide, any labels you may have set up.

Data attribute2.0.0 : data-jqdock-permanent-labels

setLabel1.5 zero function Function for transforming label text (ie. title) when initially building the label. This is provided so that if a label requires HTML, this transform function can set it rather than having to put it in the title field and thereby make the markup invalid. The function is called once per option (ie. image) during setup, is given scope (this) of the original menu element, and is passed a number of arguments:

  • string : the default text for the label, derived from the image or anchor element’s title
  • integer : the zero-based index of the option within the menu
  • element1.6 : the DOM element, div.jqDockLabel

For v1.5, the function was expected to return a text/HTML string (possibly empty) which would then be created within a div.jqDockLabelText wrapper (within div.jqDockLabel, which did not exist at the time the setLabel function was called!).

As of v1.6, the function can still return a text/HTML string as above. Alternatively, the function can return false which will prevent the creation of the div.jqDockLabelText inner wrapper. And using the supplied div.jqDockLabel DOM element, the function can manipulate the label’s content however it needs to.

size 48 integer

This is the maximum value (in pixels) of the minor axis dimension for the ‘at rest’ images. For example, an image of natural dimensions 90×120 (width x height), placed in a horizontal Dock (say, ‘align’ = ‘bottom’) would, by default, be sized down to 36×48. This is because height is the minor axis in a horizontal Dock, and to keep the presentation of the ‘at rest’ images neat and tidy it is the height that is governed by the size option. Conversely, in a vertical Dock it would be the width that was capped at the size value, with height being set proportionately.

This value – whether by default, or set specifically – should be smaller than your image’s natural size, otherwise you will not see any expansion effect when the image is hovered over!

Data attribute2.0.0 : data-jqdock-size

sizeMax2.0.0 0 integer

This is similar to size above, but it applies to the maximum expanded size in the image (still in the minor axis dimension). So if, for some reason, you have one (or more) very large images in your menu and you don’t want them to expand to their full natural size, you can use this option to set a maximum dimension (width or height, depending on alignment) for the menu.

Data attribute2.0.0 : data-jqdock-size-max

source zero function

Function for providing an alternate large image source path. For instances where you are either unable, or do not want to put the large image’s path in the IMG’s ‘alt’ attribute, but you still want to have a small and large image for clarity, this function may be useful.

If provided, it is called once per image during setup, and is given the scope of the image element and passed the index of the image within the current Dock; it is expected to return a valid image path, or false/null to continue using the defaults (‘alt’ or ‘src’).

step1.3 50 integer

The timer interval (in milliseconds) between each animation step of the ‘on-Dock’ expansion, and the ‘off-Dock’ shrinkage.

Data attribute2.0.0 : data-jqdock-step

For Options

See also the Options for Images documentation.

Data attribute : data-jqdock-

Share
 Posted by at 4:30 pm

  2 Responses to “Options”

Comments (2)
  1. This may sound very basic. How do you adjust the space between icons?

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">

(required)

(required)