type: utility

release: 1.8

status: complete

demo/docs: http://jqueryui.com/demos/position/

1 - Description:

Utility script for positioning any widget relative to the window, document, a particular element, or the pointer. This utility could be used on its own, but should also be used by all plugins that require positioning elements.  A few examples are:

• menus: (menu's left top at left bottom of menu button) A standard menu opens directly below the bottom left corner of the target and the menu itself would be aligned top left.
• tooltip: (tooltip's left bottom at center top of element/cursor) If the link or element is the target, you'd probably want to have the left edge of the tooltip centered horizontally above the element.  If a tooltip uses the current cursor position as the target, this will cause the tooltip to be place just above and to the right of the cursor, since a cursor occupies a single pixel.
• dialog: (dialog's center at window's center) A dialog usually is centered vertically and horizontally within the window. 

Positioning system:

We can use a simple system to define how the positioned element (e.g., menu or tooltip) should be placed in relation to the target element (e.g., link or button).

• The positioned element and target element both have 9 positions that map to the corners and centers of the objects.
• For these positions, we can use a CSS-style naming convention for horizontal (left, center, right) and vertical (top, center, bottom) values.

To describe the relationship between the target and positioned element, we can specify a pair of these positions: 

By combining the target and positioned elements together, we arrive at 81 possible positioning combinations.

Collision detection

• If the positioned object will not safely fit in the specified horizonal or vertical position, the positioned element can:
• flip to the opposite side.
• fit so the element stays in the desired direction, but is re-positioned so it is fully visible.
• flip and fit.
• not do collision detection.
• These collision detection options should be set independently for horizontal and vertical settings.
• A user/plugin can get the collision detection to re-run when the window is resized by simply calling the plugin again with the same options in a window resize event handler.

2 - Visual Design:

N/A

3 - Functional Specifications/Requirements: 

The element being positioned must support relative, absolute and fixed positioning.  If the element's position style is set to static, it will be set to relative when being positioned.

Parameters:

• options
• my (string)
• defines which position on the element being positioned to align with the target element: "horizontal vertical" alignment
• a single value such as "right" will default to "right center", "top" will default to "center top" (following CSS convention)
• the horizontal and vertical values may also include offsets, e.g., "right+10 left-25%" 
• at (string)
• defines which position on the target element to align the positioned element against: "horizontal vertical" alignment
• a single value such as "right" will default to "right center", "top" will default to "center top" (following CSS convention)
• the horizontal and vertical values may also include offsets, e.g., "right+10 left-25%" 
• of (jQuery, DOMElement, selector, event)
• element to position against
• when using an event, the event must have pageX and pageY properties 
• collision (string, default: "flip")
• when the positioned element overflows the within element in some direction, move it to an alternative position; as specified above
• similar to my and at, this accepts a single value or a pair for horizontal/vertical, eg. "flip", "fit", "fit flip", "fit none"
• "flip" will use the mirror position, e.g., "left" instead of "right", if flipping results in less of the element being visible, the original position will be used
• "fit" will shift the element until it is fully visible, if it cannot become fully visible, then it will shift until it reaches maximum visibility
• "flipfit" will apply flip collision followed by fit collision
• "none" will not apply any collision handling
• within (jQuery, DOMElement, string; default: window)
• element to use for collision detection
• using (function)
• when provided, the calculated position values will be passed to the callback and the element will not actually be positioned
• receives a single parameter which is a hash of top and left values for the position that should be set
• this is useful for actions such as animating the positioning of the element

4 - Markup & Style:

N/A

5 - Latest version of plugin:

http://view.jqueryui.com/master/demos/position/default.html

6 - Open issues being discussed