Jump to content

Guides

ips.utils.position

Description

Dealing with element positioning - getting current positions, working out new positions, and so on - is a common task in a web application such as IPS4. This utility aims to make that easier by providing some methods to do the calculations for you.

 

Methods

object getElemPosition( mixed elem )

Returns various positioning information for the provided element.

  • elem
    DOM element or jQuery object containing the element to work with

Returned object:

  • absPos
    • left
      Absolute left position
    • right
      Absolute right position (i.e. left + width)
    • top
      Absolute top position
    • bottom
      Absolute bottom position (i.e. top + height)
  • viewportOffset
    • left
      Viewport left offset (i.e. left offset - left scroll postion)
    • top
      Viewport top offset (i.e. top offset - top scroll position)
  • offsetParent
    Reference to the element's offsetParent. That is, the closest element that has a non-static position.
    • fixed
      true if the element has any ancestors which have fixed positioning or have one of the table display values.

 

object positionElem( object options )

Returns positioning values, allowing the calling method to appropriate position the element with a best-fit on the screen. This method does not apply the positioning values to the element itself.

  • options
    • trigger
      The trigger element for this popup; that is, the element that the popup should be 'attached' to
    • target
      The element to be positioned
    • targetContainer
      The element that contains the element to be positioned. Assumed to be body if not provided.
    • center (boolean)
      Specifies whether the method should attempt to position the target centered relative to the trigger.
    • above (boolean)
      Specifies whether the method should attempt to position the target above the trigger. By default, a best fit is attempted.

Returned object:

  • top
    Ideal top position, in pixels
  • left
    Ideal left position, in pixels
  • fixed
    Whether the element should have fixed positioning applied (because an ancestor does)
  • location
    • horizontal
      Best horizontal location for the element; either center, left or right
    • vertical
      Best vertical location for the element; either bottom or top

 

boolean hasFixedParents( mixed elem )

Returns true if any of the element's descendants have fixed positioning or have one of the table display classes (e.g. table-row).

  • elem
    The element whose ancestors are being checked for fixed positioning. Either a DOM node or a jQuery object.

 

object getElemDims( mixed elem )

Returns current dimension information for the element.

  • elem
    The element whose dimensions are being returned. Either a DOM node or a jQuery object.

Returned object:

  • width
    Current width in pixels
  • height
    Current height in pixels
  • outerWidth
    Current outer width of the element; that is, the width plus border and padding
  • outerHeight
    Current outer height of the element; that is, the width plus border and padding

 

number nautralWidth( mixed elem )

Returns the natural width of the provided element (which should be an img element). The natural width is the original width of the image not accounting for any resizing done by CSS or HTML attributes.

  • elem
    The element whose natural width is being returned. Either a DOM node or a jQuery object.

 

number nautralHeight( mixed elem )

Returns the natural height of the provided element (which should be an img element). The natural height is the original height of the image not accounting for any resizing done by CSS or HTML attributes.

  • elem
    The element whose natural height is being returned. Either a DOM node or a jQuery object.

 

number lineHeight( mixed elem )

Attempts to return the computed line-height, in pixels, of the provided element. There are edge cases where this result won't be reliable, such as CSS styling <span> tags inside the element differently to the element itself. Test your use case.

  • elem
    The element whose line-height is being returned. Either a DOM node or a jQuery object.

  Report Guide


×