jQuery/JS Common - Object Structures - positionConfig

This object is passed to the position configuration option of a widget that overlays the main screen (LoadPanel, Popup, Popover, and Toast).

The positionConfig object may contain the following fields: my, at, of, offset and collision. Look at the following sentence to see how to use these fields to position the required element against the target element.

"Place my 'left' side at the 'left bottom' corner of the '#targetElement'." The italic quoted phrase located after each option name within the sentence represents a value of the appropriate option.

The at option can take on an object containing the x and y fields, which specify horizontal and vertical position specifier respectively, or a string value consisting of horizontal and vertical position specifiers separated by a space (e.g., "left top"). The default value for each position specifier is "center". If you assign the "left" value to this option, it will be converted to the "left center" value.

position: { at: 'left bottom' };

When using a widget as an ASP.NET MVC Control, specify this option using the HorizontalAlignment and VerticalAlignment enums in the following manner.

@(Html.DevExtreme().WidgetName()
    .Position(p => p
        .At(HorizontalAlignment.Right, VerticalAlignment.Bottom)
    )
)

@(Html.DevExtreme().WidgetName() _
    .Position(Sub(p)
        p.At(HorizontalAlignment.Right, VerticalAlignment.Bottom)
    End Sub)
)

All collisions are computed against the element passed to this option. By default, widgets use the window object as a boundary element.

This option is used to resolve collisions. If the specified offset from the specified target leads to a collision with the window's boundary, the boundaryOffset value is used to position the element near the place of collision.

This option accepts an object containing the x and y fields which specify horizontal and vertical offset respectively, or a string in the following format: "5 -10", where the first number is a horizontal offset and the second number is a vertical offset in pixels.

When you configure a widget as an ASP.NET MVC Control, this option accepts two values of the double type.

@(Html.DevExtreme().WidgetName()
    .Position(p => p
        .BoundaryOffset(5, -10)
    )
)

@(Html.DevExtreme().WidgetName() _
    .Position(Sub(p)
        p.BoundaryOffset(5, -10)
    End Sub)
)

A string passed to this option should contain a collision handler name, or a pair of names separated by space. If the string consists of a single collision handler name, it is applied to both horizontal and vertical axes. If you pass a pair of names separated by space, the first collision handler will be applied to the horizontal axis, the second to the vertical axis.

// a string containing horizontal and vertical
// collision handlers separated by space
collision: "flip fit";

You can also specify different collision handlers for horizontal and vertical axes in one of the following ways.

// an object containing 'x' and 'y' fields
collision: {
    x: "flip", // horizontal collision handler
    y: "none" // vertical collision handler
}

The available collision handler names are:

• none
  Collisions do not affect widget position.
• flip
  Moves the widget to the opposite side of the target element if it allows more of the widget to be visible.
• fit
  Shifts the widget from outside of the screen to fully display the widget.
• flipfit
  Applies the fit collision handler after flip.

When using a widget as an ASP.NET MVC Control, specify this option using the PositionResolveCollision enum in the following manner. This enum accepts the following values: Fit, Flip, FlipFit and None.

@(Html.DevExtreme().WidgetName()
    .Position(p => p
        .Collision(PositionResolveCollision.Fit, PositionResolveCollision.Flip)
    )
)

@(Html.DevExtreme().WidgetName() _
    .Position(Sub(p)
        p.Collision(PositionResolveCollision.Fit, PositionResolveCollision.Flip)
    End Sub)
)

The my option can take on an object containing the x and y fields, which specify horizontal and vertical position specifier respectively, or a string value consisting of horizontal and vertical position specifiers separated by a space (e.g., "left top"). The default value for each position specifier is "center". If you assign the "left" value to this option, it will be converted to the "left center" value.

position: { my: 'left' };

When using a widget as an ASP.NET MVC Control, specify this option using the HorizontalAlignment and VerticalAlignment enums in the following manner.

@(Html.DevExtreme().WidgetName()
    .Position(p => p
        .My(HorizontalAlignment.Right, VerticalAlignment.Bottom)
    )
)

@(Html.DevExtreme().WidgetName() _
    .Position(Sub(p)
        p.My(HorizontalAlignment.Right, VerticalAlignment.Bottom)
    End Sub)
)

The option accepts one of the following values.

• A native CSS selector, or a jQuery selector if you use jQuery

  position: { of: '#targetElement' };

• A jQuery wrapper

  position: { of: $('#targetElement') };

• A DOM element

  position: { of: document.getElementById('#targetElement') };

• The Window object

  position: { of: window };

• A jQueryEvent or dxEvent object.

  The widget is positioned against the event.pageX and event.pageY coordinates. In the following example, the Popover widget is positioned against a clicked point on the "targetElement".

  $("#targetElement").click(function (event) {
      $("#popover").dxPopover("option", "position.of", event);
      // ...
  })

This options accepts an object containing the x and y fields which specify the horizontal and vertical offset respectively, or a string consisting of horizontal and vertical offset values separated separated by a space (e.g., "5 -10").

position: { offset: '5 -10' };

When you configure a widget as an ASP.NET MVC Control, this option accepts two values of the double type.

@(Html.DevExtreme().WidgetName()
    .Position(p => p
        .Offset(5, -10)
    )
)

@(Html.DevExtreme().WidgetName() _
    .Position(Sub(p)
        p.Offset(5, -10)
    End Sub)
)