Element.Position

docs

This script concerns itself with positioning elements relative to each other. It's easy to set an element's position to a specific location on the screen, but there's a lot more effort involved if you want to position an element's upper right corner on the upper left corner of another...

.setPosition lets you position an element relative to another one. So if you have an element and you want it next to or on top of another, this extension helps you handle that positioning.

The element you are positioning has to be positioned absolutely, and if you don't specify an element that you're going to make it relevant to, it'll use the document window. Here are some examples:

The default is to position is centered relative to the target:

$('setPositionTarget').setPosition(); //centered in the window

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget') /*centered over a target*/
});

You can also specify a location relative to the relativeTo object:

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'upperRight'
});

There are two ways to specify the position: strings and objects. The strings are combinations of "left", "right", and "center" with "top" (or "upper"), "bottom", and "center". These are case insensitive. These translate to:

• upperLeft, topLeft (same thing) - or upperleft, leftupper, LEFTUPPER whatever.
• bottomLeft
• centerLeft
• upperRight, topRight (same thing)
• bottomRight
• centerRight
• centerTop
• centerBottom
• center

Alternatively, you can be a little more expicit by using an object with x and y values. Acceptable values for the x axis are "left", "right", and "center", and for y you can use "top", "bottom" and "center".

• {x: 'left', y: 'top'} – same as "upperLeft" or "topLeft"
• {x: 'left', y: 'bottom'} – same as "bottomLeft"
• etc.

Using these options you can specify a position for each corner of the relativeTo object as well as the points between those corners (center left, top, right, bottom and the center of the entire object).

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'upperLeft'
});

The above example is the same as this one:

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: {
		x: 'left',
		y: 'top'
	}
});

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'bottomLeft'
});

Same as:

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: {
		x: 'left',
		y: 'bottom'
	}
});

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'bottomCenter'
});

Same as:

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: {
		x: 'center',
		y: 'bottom'
	}
});

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'leftCenter'
});

Same as:

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: {
		x: 'left',
		y: 'center'
	}
});

There's also an offset option:

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'upperRight',
  offset: {x: 20, y: 20} /*move over and down*/
});

Additionally, you can specify an edge option that allows you to align the specified edge of the element relative to the relativeTo element's edge specified in the position argument. This lets you, for instance, position the upper right corner of the element to the bottom left corner of the relativeTo element.

Examples:

/* upperRight of element aligned to upperRight of relativeTo element*/
$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'upperRight',
  edge: 'upperRight'
});

/* bottomLeft of element aligned to bottomLeft of relativeTo element*/
$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'bottomLeft',
  edge: 'bottomLeft'
});

/* center of element aligned to upperRight of relativeTo element*/
$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'upperRight',
  edge: 'center'
});

/* center of element aligned to upperRight of relativeTo element*/
$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'centerRight',
  edge: 'center'
});

/* center of element aligned to upperRight of relativeTo element*/
$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'centerBottom',
  edge: 'centerTop'
});

Again, you can use objects to describe these positions:

/* center of element aligned to upperRight of relativeTo element*/
$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: {
		x: 'right',
		y: 'top'
	},
  edge: {
		x: 'left',
		y: 'center'
	}
});

It's possible to position an element and ignore the margins around it. Here's an example; the first shows you what it looks like with the margins applied but not ignored, then 2 seconds delayed is the method to have it ignore the margin.

$('setPositionTarget').setStyles({
    'margin-right': 30,
    'margin-top': 50,
    'margin-left': 20,
    'margin-bottom': 10
});
$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: {
    x: 'left',
    y: 'top'
  },
  edge: {
    x: 'right',
    y: 'top'
  }
});
 
(function(){
	/*now ignore the margins*/
	$('setPositionTarget').setPosition({
	  relativeTo: $('fxTarget'),
	  ignoreMargins: true,
	  position: {
	    x: 'left',
	    y: 'top'
	  },
	  edge: {
	    x: 'left',
	    y: 'top'
	  }
	});
}).delay(2000);
 
 
/*put the margins back for other examples*/
(function(){
	$('setPositionTarget').setStyles({
	    'margin-right': 0,
	    'margin-top': 0,
	    'margin-left': 0,
	    'margin-bottom': 0
	});
}).delay(5000);

An additional option for .setPosition is returnPos.

returnPos will just return the x/y coordinates of where the element would move to, but not move it. This lets you use setPosition to get these coords without changing anything.

$('setPositionTarget').setPosition({
  relativeTo: $('fxTarget'),
  position: 'upperRight',
  offset: {x: 20, y: 20},
  returnPos: true
}); //returns something like {top: "123px", left: "234px"}

You can also use Fx.Move to position an element. It works just like setPosition except it allows you to have the element transition to the location instead of just jump there.