The slim highly flexible jQuery plugin to calculate element's position and overflow.
by Tobias LindigPositionCalculator calculate the position of an element relative to another element or event. It has also functionality to handle collision within the viewport of a given container.
This plugin will not manipulate any CSS settings or DOM-trees, it only calculate values. To be more exact, it calculates the difference of current position to target position and the overflow over boundary. Thus you are all paths open to implement the positioning according to your requirements. You can apply the new position by using top and left or using the css3 transform function or by setting margin. It is up to you.
It is also possible to use the result of PositionCalculator as input for additional calculation.
With PositionCalculator it is absolute easy to implements an "inView" functionality. Take a look to the "Examples" section below.
PositionCalculator takes away the complicated calculation taking account of preferred orientation, reference points and boundary.
With PositionCalculator it is more easy to implement components like tooltip, popover, popup, sticky navigation, dynamic placed toolbars and so on. You don't need waste your time with implementing calculation for positioning a item near by a target element and for collision handling. Just use the PositionCalculator.
Try out all the options and see the result instantly. All options are described in a table in section below.
Below you can see a yellow square. That is the item that will be positioned.
To see the collision handling live (flip and stick) you can check the checkbox in the green rectangle and move it with the mouse. The colored triangle shows the initial chosen reference point from item and target (itemAt, targetAt).
Initial placement of reference point.
The colored triangle shows your decision.
Collision handling strategy.
Prevent overflow of boundary. Select the edge where item shall stick on.
Flip reference point from target, from item or from both.
Return value of .calculate():
Properties, read from DOM:
| Name | type | default | description |
|---|---|---|---|
| item | selector | jQuery | DOM node | null |
Required. Given value will be called with
|
| target | selector | jQuery | DOM node | null | null |
"selector" means a
If no element match or |
| boundary | selector | jQuery | DOM node | null | window |
"selector" means a If no element match, overflow will not calculated. |
| itemAt | string | "top left" |
Placement of reference point on the item
Space separated combination of |
| targetAt | string | "top left" |
Placement of reference point on the target
Space separated combination of |
| itemOffset | Object | { y:0, x:0, mirror:true } |
Additional offset for position of specified reference point from item. Properties: |
| targetOffset | Object | { y:0, x:0, mirror:true } |
Additional offset for position of specified reference point from target. Properties: |
| flip | string | boolean | 'both' |
Specify the strategy to prevent that item overflows the boundary.
Allowed as value is: |
| stick | string | boolean | 'all' |
Will keep the item within it's boundary by sticking it to the edges that normally would overflow.
Specify sides you'd like to control (space separated |
PositionCalculator is a JavaScript class added to the jQuery object. It can be instantiated by calling the constructor.
Create and initializes a new instance of PositionCalculator. Options are described in section "Options".
var myCalculator = new jQuery.PositionCalculator({ item: '#idItem', target:'#idTarget' });
All methods of PositionCalculator return the instance itself to allow chaining, except the method shall explicit return special value.
Calculate the distance between reference point of item and reference point of target and handle overflow in the specified matter.
Current position of elements (item, target, boundary) will be read from DOM.
Return a CalculationResult object.
var result = myCalculator.calculate();
Exported helper method. Calculate the resulting position only for the given placement. That will not handle flip and fit. Current position of elements (item, target, boundary) will be read from DOM.
Arguments item_at and target_at have to be an object with
string property x and y.
Allowed values for x are "left", "center" or "right".
Allowed values for y are "top", "middle" or "bottom".
Return a CalculationResult object.
var result = myCalculator.calcVariant();
Update intern stored values depending on size and position of elements (item, target, boundary). Should be called if dimensions of an element changed.
Return this instance itself to allow chaining.
myCalculator.resize();
CalculationResult| Name | type | example | description |
|---|---|---|---|
| moveBy | Object | { y:10, x:-20 } |
Calculated distance between resulting reference points of target and item as pixel values. Properties: |
| itemAt | string | "top left" |
Resulting placement of reference point on the item
Space separated combination of |
| targetAt | string | "top left" |
Resulting placement of reference point on the target
Space separated combination of |
| distance | {null|Object} |
{
top:51,
left:22,
bottom:171,
right:375,
overflow: ["top", "left"]
}
|
Calculated distance of item to the viewport of boundary. Properties: |
PositionCalculator do not trigger events.
All this components want show an additional element (item) at a special target position. And may be you want also ensure that the new item is shown without clipping by the viewport.
The new position will be given to you by the PositionCalculator, you have only to set the css properties.
In this example, PositionCalculator is used to figure out if an element is shown in viewport. If so, a special class will be added.
In this example, PositionCalculator is used to add auto position feature to the dropdown menu from Bootstrap.
The first dropdown, has the default behavior of dropdown from bootstrap, but the second, got the add a auto flipping feature.