ch.Positioner (Class)

Documentation updated on Fri May 18 2012 12:47:10 GMT-0300 (GMT-03:00), generated by JsDoc Toolkit 2.4.0

Overview

Positioner is an utility that centralizes and manages changes related to positioned elements, and returns an utility that resolves positioning for all UI-Objects.

• Constructor name: ch.Positioner(conf)
• View source on GitHub.

Summary

Classdetail

Parameters

• conf: Object. Configuration object with positioning properties.
• conf.element: String. Reference to the DOM Element to be positioned.
• conf.context: String, Optional. It's a reference to position and size of element that will be considered to carry out the position. If it isn't defined through configuration, it will be the viewport.
• conf.points: String, Optional. Points where element will be positioned, specified by configuration or centered by default.
• conf.offset: String, Optional. Offset in pixels that element will be displaced from original position determined by points. It's specified by configuration or zero by default.
• conf.reposition: Boolean, Optional. Parameter that enables or disables reposition intelligence. It's disabled by default.

Returns

• Object

Requires

• Viewport
• ch.Viewport

// An Element centered into the Viewport (default behavior)
ch.positioner({
    element: "#element1",
});

// An Element positioned relative to a Context through defined points
// The Element left-top point will be the same as Context right-bottom point
ch.positioner({
    element: "#element2",
    context: "#context2",
    points: "lt rt"
});

// An Element displaced horizontally by 10px of defined position
ch.positioner({
    element: "#element3",
    context: "#context3",
    points: "lt rt",
    offset: "10 0"
});

// Repositionable Element if it can't be shown into viewport area
ch.positioner({
    element: "#element4",
    context: "#context4",
    points: "lt rt",
    reposition: true
});

Properties detail

$element (private, jQuery Object)

Reference to the DOM Element to be positioned.

changing (private, Boolean)

Reference that allows to know when window is being scrolled or resized.

CLASS_MAP (privateconstant, Object)

Map that references the input points to an output friendly classname.

context (private, Object)

It's a reference to position and size of element that will be considered to carry out the position. If it isn't defined through configuration, it will be the viewport.

contextIsNotViewport (private, Boolean)

Reference that allows to know if context is different to viewport.

friendly (private, Boolean)

Friendly classname relative to position points.

lastCoordinates (private, Object)

Reference that stores last changes on coordinates for evaluate necesaries redraws.

offset (private, X and Y references determined by "offset" configuration parameter.)

Offset in pixels that element will be displaced from original position determined by points. It's specified by configuration or zero by default.

// Moves 5px to right and 5px to bottom
ch.positioner({
    element: "#element1",
    offset: "5 5"
});
// It will be worth:
offset[0] = 5;
offset[1] = 5;

// Moves 10px to right and 5px to top
ch.positioner({
    element: "#element1",
    offset: "10 -5"
});
// It will be worth:
offset[0] = 10;
offset[1] = -5;

parentIsBody (private, Boolean)

Reference to know if direct parent is the body HTML element.

points (private, String)

Points where element will be positioned, specified by configuration or centered by default.

// Element left-top point = Context right-bottom point
ch.positioner({
    element: "#element1",
    points: "lt rt"
});

// Element center-middle point = Context center-middle point
ch.positioner({
    element: "#element2",
    points: "cm cm"
});

relativeParent (private, Object)

It's the first of context's parents that is styled positioned. If it isn't defined through configuration, it will be the HTML Body Element.

reposition (private, Boolean)

Configuration parameter that enables or disables reposition intelligence. It's disabled by default.

// Repositionable Element if it can't be shown into viewport area
ch.positioner({
    element: "#element1",
    reposition: true
});

that (private, Object)

Reference that saves all members to be published.

Methods detail

addCSSproperties (private)

Position "element" as fixed or absolute as needed.

changesListener (private)

Listen to LAYOUT.CHANGE and VIEWPORT.CHANGE events and recalculate data as needed.

draw (private)

Checks if there are changes on coordinates to reposition the element.

getContext ()

Defines context element, its size, position, and methods to recalculate all.

Returns

• Context Object

getCoordinates (private)

Calculates left and top position from specific points.

var foo = getCoordinates("lt rt");

foo = {
    left: Number,
    top: Number
};

Parameters

• points: String. String with points to be calculated.

Returns

• Offset measures

getPosition (private)

Gets new coordinates and checks its space into viewport.

Returns

• Offset measures

init (private)

Constructs a new position, gets viewport size, checks for relative parent's offset, finds the context and sets the position to a given element.

position (public)

Control object that allows to change configuration properties, refresh current position or get current configuration.

// Sets a new configuration
var foo = ch.positioner({ ... });
    foo.position({ ... });

// Refresh current position
    foo.position("refresh");

// Gets current configuration properties
    foo.position();

Parameters

• o: Object, Optional. Configuration object.
• "refresh": String, Optional. Refresh current position.

Returns

• Control Object

triggerScroll (private)

Checks if window is being scrolled or resized, updates viewport position and triggers internal Change event.

Events detail

change (private)

Triggers when window is being scrolled or resized.