type: utility

release: 1.8

status: complete

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

todos: http://bugs.jqueryui.com/report/10?P=position

1 - Description:

Utility script for absolutely positioning any widget relative to the window, document, a particular element, or the cursor/mouse. 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 parent 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 parent, 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 parent, 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 positioned centered vertically and horizontally within the window.
• photoviewer: (current photo's center at window's center; next photo's left center at window's right center offset horizontally by -10px (or better yet, 10% of the photo's width) The current photo should be centered in the window, with the next photo slightly visible on the right edge of the screen.

Positioning system:

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

• Both positioned element (eg. menu or tooltip) and parent element (eg. link or button) have 9 positions that map to the corners and centers of the object
• For these positions, we can use a CSS-style naming convention to horizontal (left, center, right) and vertical (top, center, bottom).

• 

   

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

  

   

• By combining the parent 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 (eg. left or top), the positioned object's positioning can
• flip to the opposite side (eg. right or bottom) and the collision detection is run again to see if it will fit. If it won't fit in either position, the center option should be used as a fall back
• fit so the element keeps in the desired direction, but is re-positioned so it fits
• 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.  

  

Want to play with these diagrams?

Download the Illustrator CS3 source file: positionTo_23oct2009.ai

2 - Visual Design:

There is no visual design needed for this plugin.

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)
• 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)
• of (jQuery)
• element to position against
• offset (String)
• add those left-top values to the calculated position, eg. '50 50' (left top)
• a single value such as "50" will apply to both
• collision (String, values: "flip", "fit", "none"; default: "flip")
• when the positioned element overflows the window 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"
• using (Callback)
• whens specified the actual property setting is delegated to this callback
• 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
• bgiframe (Boolean, default: true)
• Applies the bgiframe utility when set to true. Only applies when stackfix is acutally loaded, nothing happens otherwise.

Examples:

$('#bar').position({ my: 'left top', at: 'left bottom', of: '#foo' });

$('#bar').position({ my: 'left top', at: 'left bottom', of: '#foo', using: function(to) {

  $(this).animate(to);

});

// menu

$(".menu").position({ my: "left top", at: "left bottom", of: ".menubutton" });

// tooltip

$(".tooltip").position({ my: "left bottom", at: "center top", of: ".hovered-element" });

// dialog

$(".dialog").position({ my: "center", at: "center", of: window });

// photoviewer, position next photo at the right of the screen, just barely visible, then animate to the center

$(".next-photo")

    .position({ my: "left center", at: "right center", of: window, offset: "-10 0" })

    .position({ my: "center", at: "center", of: window, using: function(to) {

        $(this).animate(to);

    }});

4 - Markup & Style:

Not applicable, this plugin only changes the position of an existing element.  There are no markup, style or accessibility concerns.

5 - Latest version of plugin:

http://jquery-ui.googlecode.com/svn/trunk/demos/position/default.html

6 - Open issues being discussed 

• Supporting percentages in place of top/bottom/left/right/center would provide even more flexibility.  This could be implemented in a future version if necessary.
• Same for offset, eg. position this element's left center at the windows right center, and offset it by 10% (of its width) to the left
• If the element being positioned and the target element have differnet scroll parents, the element being positioned will need to be moved in the DOM to allow the elements to scroll together. The plugin will not handle that (for now), so the user has to do the DOM movement when necessary.