readme.md

The $uibPosition service provides a set of DOM utilities used internally to absolute-position an element in relation to another element (tooltips, popovers, typeaheads etc...).

getRawNode(element)

Takes a jQuery/jqLite element and converts it to a raw DOM element.

parameters

• element (Type: object) - The element to convert.

returns

• (Type: element) - A raw DOM element.

parseStyle(element)

Parses a numeric style value to a number. Strips units and will return 0 for invalid (NaN) numbers.

parameters

• value (Type: string) - The style value to parse.

returns

• (Type: number) - The numeric value of the style property.

offsetParent(element)

Gets the closest positioned ancestor.

parameters

• element (Type: element) - The element to get the offset parent for.

returns

• (Type: element) - The closest positioned ancestor.

scrollbarWidth(isBody)

Calculates the browser scrollbar width and caches the result for future calls. Concept from the TWBS measureScrollbar() function in modal.js.

parameters

• isBody (Type: boolean, Default: false, optional) - Is the requested scrollbar width for the body/html element. IE and Edge overlay the scrollbar on the body/html element and should be considered 0.

returns

• (Type: number) - The width of the browser scrollbar.

scrollbarPadding(element)

Calculates the padding required to replace the scrollbar on an element.

parameters

• 'element' (Type: element) - The element to calculate the padding on (should be a scrollable element).

returns

An object with the following properties:

• scrollbarWidth (Type: number) - The width of the scrollbar.

• widthOverflow (Type: boolean) - Whether the width is overflowing.

• right (Type: number) - The total right padding required to replace the scrollbar.

• originalRight (Type: number) - The oringal right padding on the element.

• heightOverflow (Type: boolean) - Whether the height is overflowing.

• bottom (Type: number) - The total bottom padding required to replace the scrollbar.

• originalBottom (Type: number) - The oringal bottom padding on the element.

isScrollable(element, includeHidden)

Determines if an element is scrollable.

parameters

• element (Type: element) - The element to check.

• includeHidden (Type: boolean, Default: false, optional) - Should scroll style of 'hidden' be considered.

returns

• (Type: boolean) - Whether the element is scrollable.

scrollParent(element, includeHidden, includeSelf)

Gets the closest scrollable ancestor. Concept from the jQueryUI scrollParent.js.

parameters

• element (Type: element) - The element to get the closest scrollable ancestor for.

• includeHidden (Type: boolean, Default: false, optional) - Should scroll style of 'hidden' be considered.

• includeSelf (Type: boolean, Default: false, optional) - Should the element passed in be included in the scrollable lookup.

returns

• (Type: element) - The closest scrollable ancestor.

position(element, includeMargins)

A read-only equivalent of jQuery's position function, distance to closest positioned ancestor. Does not account for margins by default like jQuery's position.

parameters

• element (Type: element) - The element to get the position for.

• includeMargins (Type: boolean, Default: false, optional) - Should margins be accounted for.

returns

An object with the following properties:

• width (Type: number) - The width of the element.

• height (Type: number) - The height of the element.

• top (Type: number) - Distance to top edge of offset parent.

• left (Type: number) - Distance to left edge of offset parent.

offset(element)

A read-only equivalent of jQuery's offset function, distance to viewport.

parameters

• element (Type: element) - The element to get the offset for.

returns

An object with the following properties:

• width (Type: number) - The width of the element.

• height (Type: number) - The height of the element.

• top (Type: number) - Distance to top edge of the viewport.

• left (Type: number) - Distance to left edge of the viewport.

viewportOffset(element, useDocument, includePadding)

Gets the elements available space relative to the closest scrollable ancestor. Accounts for padding, border, and scrollbar width. Right and bottom dimensions represent the distance to the respective edge of the viewport element, not the top and left edge. If the element edge extends beyond the viewport, a negative value will be reported.

parameters

• element (Type: element) - The element to get the viewport offset for.

• useDocument (Type: boolean, Default: false, optional) - Should the viewport be the document element instead of the first scrollable element.

• includePadding (Type: boolean, Default: true, optional) - Should the padding on the viewport element be accounted for, default is true.

returns

An object with the following properties:

• top (Type: number) - Distance to top content edge of the viewport.

• bottom (Type: number) - Distance to bottom content edge of the viewport.

• left (Type: number) - Distance to left content edge of the viewport.

• right (Type: number) - Distance to right content edge of the viewport.

parsePlacement(placement)

Gets an array of placement values parsed from a placement string. Along with the 'auto' indicator, supported placement strings are:

• top: element on top, horizontally centered on host element.
• top-left: element on top, left edge aligned with host element left edge.
• top-right: element on top, right edge aligned with host element right edge.
• bottom: element on bottom, horizontally centered on host element.
• bottom-left: element on bottom, left edge aligned with host element left edge.
• bottom-right: element on bottom, right edge aligned with host element right edge.
• left: element on left, vertically centered on host element.
• left-top: element on left, top edge aligned with host element top edge.
• left-bottom: element on left, bottom edge aligned with host element bottom edge.
• right: element on right, vertically centered on host element.
• right-top: element on right, top edge aligned with host element top edge.
• right-bottom: element on right, bottom edge aligned with host element bottom edge.

A placement string with an 'auto' indicator is expected to be space separated from the placement, i.e: 'auto bottom-left'. If the primary and secondary placement values do not match 'top, bottom, left, right' then 'top' will be the primary placement and 'center' will be the secondary placement. If 'auto' is passed, true will be returned as the 3rd value of the array.

parameters

• placement (Type: string, Example: auto top-left) - The placement string to parse.

returns

An array with the following values:

• [0] (Type: string) - The primary placement.

• [1] (Type: string) - The secondary placement.

• [2] (Type: boolean) - Is auto place enabled.

positionElements(hostElement, targetElement, placement, appendToBody)

Gets gets coordinates for an element to be positioned relative to another element.

parameters

• hostElement (Type: element) - The element to position against.

• targetElement (Type: element) - The element to position.

• placement (Type: string, Default: top, optional) - The placement for the target element. See the parsePlacement() function for available options. If 'auto' placement is used, the viewportOffset() function is used to decide where the targetElement will fit.

• appendToBody (Type: boolean, Default: false, optional) - Should the coordinates be cacluated from the body element.

returns

An object with the following properties:

• top (Type: number) - The targetElement top value.

• left (Type: number) - The targetElement left value.

• right (Type: number) - The resolved placement with 'auto' removed.

positionArrow(element, placement)

Positions the tooltip and popover arrow elements when using placement options beyond the standard top, left, bottom, or right.

parameters

• element (Type: element) - The element to position the arrow element for.

• placement (Type: string) - The placement for the element.