JS: Dhtml: Linear Path Maker and Movers (Javascript)

The scripts I feature here

rely on my ULMA approach: therefore you need to load somewhere after your body tag either an external javaScript files which holds all the ULMA functions, or you have to paste all of them inline with a <script> tag soon after the tag <body> (and also after you've defined your layer): for all the detail and the ULMA codes, please refer to my ULMA [Universal Layer Management] Procedures: you can neither understand nor use these scripts if you are not using ULMA procedures.

These scripts have two main purposes: position a layer, move it.
As ULMA prescribes (please do se the file linked above if you have no clue what I'm talking about) you have to include a layer in your page (presumably by
<div style="position:absolute; top: ... ">
tags with a consistent set of css properties declared in its style property); then you declare a global var and then to initialize it as a new layerManager:
var foo;
foo=new layerManager('foo', 'layerNameHere')foo is just a placeholder for whatever variable name you may choose, and layerNameHere the ID you assigned to your layer.
You now ready to initialize its methods (names of the methods can be seen in the active form below) as new methodManager, like for instance:
foo.toCenter=new managerMethod('foo','toCenter')

After done that, keep in mind these rules of thumb that may show to you the power of ULMA procedures for Dhtml:

If you activate one of the methods initialized as new managerMethods, you can do that either by:
- execute: foo.toCenter.execute()
  This would move the layer to the center. It appends page offsets, namely the level the user has scrolled the page to.
- run: foo.toCenter.run()
  This would actually trigger an animation since if you call for run() on a ULMA method, it triggers a timeout (which can be closed by foo.toCenter.stop() - toCenter is just the method being used in this example, obviously). Since a timeout has been called in with run(), and since the methods add page offsets, this bears a remarkable consequence: the script keeps repositioning the layer to the center of the page (in the example case) at each timeout interation (depending on its speed), with the ensuing fact that if the user scrolls either upward or bottom ward the page, the layer would... follow the scrolling: this is called a watermark, I did not invent it: the watermark has been invented, if I am not mistaken, by Yahoo/Geocities.
- You may wonder: what if I do not want to add the offsets, namely you want to position a layer in a precise location regardless to the level the user has scrolled the page to? very easy, you just declare foo.toCenter.noOffsets=1 prior to the call either to run or to execute:
  foo=new layerManager('foo', 'layerNameHere');
  foo.abilitate();
  foo.toCenter=new managerMethod('foo','toCenter');
  foo.toCenter.noOffsets=1;
  foo.toCenter.run();
  I call it self explicative and quite cool.
You may have got the hint: if you need to position without the offsets, it makes more sense anyway to resort to execute(): in fact a call to run() without adding offsets, would trigger and go on with a timeout that would reposition (without you being aware of it for it would appear still) the layer continuously to... the page location it is already located at: therefore for either noOffsets positionings or positionings that are meant to be made only once (watermarked or not) a call to execute() is more appropriate in ULMA than a call to run().
Take also into consideration that when you call in run(), the first iteration would happen only after the declared timeout speed has elapsed at least one time: this means that if you call run() with a timeout of 1000 milliseconds, your layer will "wait" 1000 milliseconds before beginning to move around. If you want to bypass this natural behaviour of a timeouted animation: first a call to execute(), then an immediate and consequent call to run(): another snap feature that ULMA provides. The former call (to execute) positions immediately, the latter call (to run) would go on with the animation after the timeout milliseconds have elapsed, so that the appearance of the whole would be smooth and gap less.
More tricks: some of the positioning move the layer to document coordinates that may be finding you with a wish to locate the layer taking into account its border margins: that is, if you locate a layer at the center/right level of the screen (central level, but moved to gaze the right vertical bar of your screen) you may want the layer being positioned there with its right margin matching the limit of the screen, or you may want it to get its left margin matching the limit of the screen: this would make the layer invisible, but is a technique you may want to resort to when you mean, for instance, to make a layer enter in the page scene as if it were appearing from nowhere.
In these cases you have in ULMA a property called switcher which defaults to zero:
- foo.myMethod.switcher=0 (default, actually) would move the layer so that it is fully visible.
- foo.myMethod.switcher=1 would move the layer completely (upon moving it that way, in some cases you won't be able to see it at all: do not argue the function didn't do its job!).
- We also have a: foo.myMethod.switcher=2 which would move the layer in a different way: it applies only to screen corners coordinates (top-left, top-right, bottom-left, bottom-right): if set to 2, the layer would be moved so that its corresponding angle would be precisely pinpointed to match the angle it has been moved to (in the test form check the toBottomRight function and scroll the page vertically and horizontally both after it has been called: run it with execute (not with the run radio box checked, that is) and with switcher set to 2, and you will see immediately what I mean).
- Numbers higher than 2 (for the functions dispatching to corners) would be read as 2.
- So, instance:
  foo=new layerManager('foo', 'layerNameHere');
  foo.abilitate();
  foo.toBottomRight=new managerMethod('foo','toBottomRight')
  you might want to add another command prior to execution if you wish so, like:
  foo.toBottomRight.noOffsets=1
  foo.toBottomRight.switcher=1
  foo.toBottomRight.run()

For the explanations on the Path Maker, see details after the Test Form.

I feature here a Path Maker, which is a function meant to build an array whose each entry holds a top and left couple of coordinates: upon moving a layer (with an animation) it may be instructed to follow it by adding to your layer manager (if you're using ULMA: and in our case the layer Manager is variable placeholder we called foo) the new method ULMAMover:
foo.ULMAMover=new managerMethod('foo', 'ULMAMover');
and the assigning to it a path by declaring:
foo.ULMAMover.path=pathMaker(arguments...)
Whereas by arguments we mean a set of arguments as they are to be outlined later on.
To set the speed in milliseconds:
foo.ULMAMover.speed=250; //250 or whatever
When ready to run, you declare just as usual:
foo.ULMAMover.run()

Before printing the pathMaker codes, I want to instruct you on how to use it. It is conceived to hold two different sets of arguments:

amount: this is the amount you want to be included between each set of coordinates in your path: that is, if you set an amount of, say, 5, each subsequent lot of coordinates would shift on (or backward) by 5: [0,0] [5,5] [10,10] ...
startTop and startLeft: they are the coordinates you want your path must start with. You don't have to pass them counting in page offsets: when ULMAMover would engage the path made by pathMaker and would start making the layer follow it, ULMAMover would automatically add page offsets, with the default assumption you want an animation to be performed on the page level (that is: the page offsets) the user is currently positoned at.
endTop and endLeft: would obviously be the coordinates where you want your animation to finish.
center: ATTENTION! ATTENTION!: this parameter must be passed always even if you don't want its services (in such case just pass it as a zero).
If you want its services you have to pass it as the layer ID (name). Please read once again this last point, for failing following its strict nature would imply either getting a javaScript error or to get your path being not the one you expected.
If you set center to the layer ID, it would move the layer not fetching it by its top/lef corner, but by... its center: therefore you can now understand why if you pass center you have to pass it as the layer ID: the function has to work out the dimensions of the given layer. Makes sense, doesn't it?
On the other hand, you set it to zero anyway, for if you don't the function would not work for it has been crafted in a particular way (see below).

So a first possible invocation of the pathMaker is:
pathMaker(5,0,0,300,350,0)
which moves 5 by 5 starting from coords [0,0] towards coords [300,350]

or, if you want to grab the layer by its center and not top corner:
pathMaker(5,0,0,300,350,'layerName')

Since you want to use ULMAMover (code later on) and you want to instruct it to follow that path, you have to make the pathMaker output to be passed as the path property of this method: so, as an example, after you have initialized a layerManager named foo, abilitated it and assigned to it the ULMAMover as a new managerMethod:
foo.ULMAMover.path=pathMaker(5,100,100,500,450,0);
//you could now activate it by simply saying:
foo.ULMAMover.run();

There is at least a second (TYPE 2) possible setting you may be wanting a path being crafted for an animation: this is when you want the layer to start moving from its current position: that is, without assigning to the pathMaker the starting position coordinates but assuming the pathMaker would argue as starting position coordinates the one the layer is currently positioned at. The pathMaker can work this out if you pass to it the parameters in the following shape/order:

amount - endTop - endLeft - layerName - center

That is, the difference is that you still pass amount, then you pass the end top and end left coordinates instead of the startTop and startLeft ones (you don't pass the start top and start left coordinates, so it means you want those coordinates to default to the current layer position).
You then pass between quotes the layerID, and again the very same as above for the center argument. Example:
foo.ULMAMover.path=pathMaker(5,500,450,'layerName',0);
//you could now activate it by simply saying:
foo.ULMAMover.run();
If you want to grab the center, just pass again as last argument the layerName in between quotes instead of zero.

You may notice that in the first case the arguments we passed were six, in this latter case they are 5. Center is still mandatory, set it to zero if you do not want the layer being grabbed by its top corner, but do pass it in both instances or the path wouldn't be generated.

The pathMaker will produce a path also for negative coordinates.

Also, the pathMaker will tailor the animation amounts for top and left coordinates, so that to accomodate the proportion between the width and height of the two segments: this means that if the amount in between the layer starting top coordinate and its end top coordinate and the amount in between the layer starting left coordinate and its end left coordinates, would produce two segments whose length is not equal, the pathMaker will be able to tailor the amount correctly!

Now, your ULMAMover codex.
Just keep in mind that ULMAMover adds page offsets: this means that if the user scrolls the page while the animation is on, the layer would... follow also the page scrolling! (just use the form to test...).
So follow these rules:

for PATH made with pathMaker TYPE 1:

TYPE 1 is the pathMaker when arranged passing both coordinates sets: the set of the meant [startTop/startLeft] position coordinates and the set of the meant [endTop/endLeft] position coordinates.

Type 1 is the name by which we flag the pathMaker when we use it passing to it all its possible arguments, namely passing to it the startTop and startLeft cvoordinates as well as the EndTop and endLeft coordinates.

Default behavior: adds offsets:
foo.ULMAMover.run()
Do not add offsets:
foo.ULMAMover.noOffsets=1;
foo.ULMAMover.run()

for PATH made with pathMaker TYPE 2:

TYPE 2 is the pathMaker when arranged passing only one coordinates set: the set of the meant [endTop/endLeft] position coordinates, thus letting the script detect on its own the current layer [top/left] position coordinates making of them the startTop/startLeft coordinates.

This typology has a great variety of possibilities, since it's the type of path that path maker generates when you do not pass the starting top and left coordinates assuming that the pathMaker would get as startTop and startLeft the current layer top and left coordinates.
There is a variety of chances depending on the fact you want watermark power or not (watermarking means that if you watermark, upon scrolling of the page the animation would follow the scrolling) and depending on the fact you want to add to your endTop/endLeft coordinates set the current page offsets or not, and last but not least depending on the fact whether you decide or not to relocate your layer to the current page offsets level (remember that relocation is a ULMA built in method meant to shift a layer from its position to the page level where the user has scrolled at -either upward or downward- preserving in the relocation process the original top/left location coordinates ratio):

WATERMARK
1. watermark plus relocating of the layer to current page level
  1. adding current page level to the endTop/endLeft coordinates
  2. without adding current page level to the endTop/endLeft coordinates
2. watermark without relocating of the layer to current page level
  1. adding current page level to the endTop/endLeft coordinates
  2. without adding current page level to the endTop/endLeft coordinates
NO WATERMARK
1. no watermark plus relocating of the layer to current page level
  1. adding current page level to the endTop/endLeft coordinates
  2. without adding current page level to the endTop/endLeft coordinates
2. no watermark without relocating of the layer to current page level
  1. adding current page level to the endTop/endLeft coordinates
  2. without adding current page level to the endTop/endLeft coordinates

On the whole they are 8 possibilities. It's not complicated, it's that I take into account all the possibilities, but yours is only one, depending on the animation architecture you want for your page. I do encourage you to test them using the form above, nothing could be more self-explicative than an active test.

To achieve these 8 possibilites you have to code in several different ways: here are the 8 formulas, all you have to do is to copy and paste them when you have met one of those 8 possible combinations.
Last but not least, in a couple of cases to achieve the formula settings we had to resort to type 1 approach: in any case when you see the startTop/startLeft couple included, it means that you can optionally even add a value to the current layer position: if you do not want add anything to the current layer positons, just change startTop and startLeft with zeros.
foo still the placeholder for your layerManager variable name.
Centers always set as zero if you do not mean to handle the layer movements by its center, otherwise pass it as the layerName itself in between quotes.
Anyway, if you prefer a function that can make these replacements for you, I add also some function snippets that would do the job by simply passing 4 parameters to them. It's not complex, I just provide you with a full-fledged approach taking into account whatever your preferences might be.

Three more arguments: rounds affects the foo.ULMAMover.rounds property: if you pass such argument, the animation will repeat the path as many times as you specified.
infiniteLoop affects the foo.ULMAMover.infiniteLoop property: if you pass such argument, the animation will repeat the path forever, overriding whatever value rounds might have or have not (see further on the ULMAMoverStopper subroutine if by chance you want to interrupt and abort the inifinte looping).
alternate affects the foo.ULMAMover.alternate property: if you pass such argument, the animation will repeat the path either forever (if you passed the infiniteLoop argument or you directly set foo.ULMAMOver.inifiniteLoop=1) or for the specified amount of times (if you passed the rounds or you directly set foo.ULMAMOver.rounds=10 - 10 or whatever...), but after completion of each iteration it will reverse the path so making a bouncing effect (without lingering on the last attained entry!).
Feel free to test in the test form.
Remember that if you want an alternate bouncing behaviour, you have obviously to specify also either the amount of rounds or set an infiniteLoop.

formula for case 1.1.1
Watermark + Relocation + Add Page Offsets to End Coords

For a function that gathers gathers all the relative commands for such a purpose, you can copy the following one: it gets executed by passing as first argument the layerManager itself (placeholder foo in our case. Note no apex, you pass the object itself, not the stringed name of it), then the amount, then endTop and endLeft.
Centers, startTop and startLeft are entirely optional, as well as rounds and infinite parameters are (and to know what they are for, scroll to botttom of this file and read the section for the ULMAMover function); if you mean to pass centers, then you have to pass it either as zero or as a number other than zero, and the function will work out the rest. If you want to pass either the round or the infinite arguments but you do not want to set the startT and startL, pass startT and startL as zeros.
Minimal sintax upon invoking on a layerManager variable named foo (values such as 5, 100 and 300 are just example values, you can use different values obviously):
formula1(foo, 5, 100, 300)

function formula1(manager, amount, endT, endL, centers, startT, startL, rounds, infinite, alternate){ centers=(centers)?manager.layerName:0; startT=(startT)?startT:0; startL=(startL)?startL:0; alternate=(alternate)?1:0; manager.ULMAMover.noOffsets=0; manager.relocate() manager.ULMAMover.path=pathMaker( amount, startT+manager.dispatcher.execute(0,0,1)[0]-eval(offsetY), startL+manager.dispatcher.execute(0,0,1)[1]-eval(offsetX), endT, endL, centers); var params=new Array(0,0); params=(rounds)? new Array(parseFloat(rounds),0):params; params=(infinite)? new Array(0,1):params; if(alternate){params[++params.length-1]=1}; manager.ULMAMover.run(params) }

formula for case 1.1.2
Watermark + Relocation + No Add Page Offsets to End Coords

function formula2(manager, amount, endT, endL, centers, startT, startL, rounds, infinite, alternate){ centers=(centers)?manager.layerName:0; startT=(startT)?startT:0; startL=(startL)?startL:0; alternate=(alternate)?1:0; manager.ULMAMover.noOffsets=0; manager.relocate() manager.ULMAMover.path=pathMaker( amount, startT+manager.dispatcher.execute(0,0,1)[0]-eval(offsetY), startL+manager.dispatcher.execute(0,0,1)[1]-eval(offsetX), endT-eval(offsetY), endL-eval(offsetX), centers); var params=new Array(0,0); params=(rounds)? new Array(parseFloat(rounds),0):params; params=(infinite)? new Array(0,1):params; if(alternate){params[++params.length-1]=1}; manager.ULMAMover.run(params) }

formula for case 1.2.1
Watermark + No Relocation + Add Page Offsets to End Coords

function formula3(manager, amount, endT, endL, centers, startT, startL, rounds, infinite, alternate){ centers=(centers)?manager.layerName:0; startT=(startT)?startT:0; startL=(startL)?startL:0; alternate=(alternate)?1:0; manager.ULMAMover.noOffsets=0; manager.ULMAMover.path=pathMaker( amount, startT+manager.dispatcher.execute(0,0,1)[0]-eval(offsetY), startL+manager.dispatcher.execute(0,0,1)[1]-eval(offsetX), endT, endL, centers); var params=new Array(0,0); params=(rounds)? new Array(parseFloat(rounds),0):params; params=(infinite)? new Array(0,1):params; if(alternate){params[++params.length-1]=1}; manager.ULMAMover.run(params) }

formula for case 1.2.2
Watermark + No Relocation + No Add Page Offsets to End Coords

function formula4(manager, amount, endT, endL, centers, startT, startL, rounds, infinite, alternate){ centers=(centers)?manager.layerName:0; startT=(startT)?startT:0; startL=(startL)?startL:0; alternate=(alternate)?1:0; manager.ULMAMover.noOffsets=0; manager.ULMAMover.path=pathMaker( amount, startT+manager.dispatcher.execute(0,0,1)[0]-eval(offsetY), startL+manager.dispatcher.execute(0,0,1)[1]-eval(offsetX), endT-eval(offsetY), endL-eval(offsetX), centers); var params=new Array(0,0); params=(rounds)? new Array(parseFloat(rounds),0):params; params=(infinite)? new Array(0,1):params; if(alternate){params[++params.length-1]=1}; manager.ULMAMover.run(params) }

formula for case 2.1.1
No Watermark + Relocation + Add Page Offsets to End Coords

function formula5(manager, amount, endT, endL, centers, startT, startL, rounds, infinite, alternate){ centers=(centers)?manager.layerName:0; startT=(startT)?startT:0; startL=(startL)?startL:0; alternate=(alternate)?1:0; manager.ULMAMover.noOffsets=1; manager.relocate() manager.ULMAMover.path=pathMaker( amount, endT+eval(offsetY), endL+eval(offsetX), manager.layerName, centers); var params=new Array(0,0); params=(rounds)? new Array(parseFloat(rounds),0):params; params=(infinite)? new Array(0,1):params; if(alternate){params[++params.length-1]=1}; manager.ULMAMover.run(params) }

formula for case 2.1.2
No Watermark + Relocation + No Add Page Offsets to End Coords

function formula6(manager, amount, endT, endL, centers, startT, startL, rounds, infinite, alternate){ centers=(centers)?manager.layerName:0; startT=(startT)?startT:0; startL=(startL)?startL:0; alternate=(alternate)?1:0; manager.ULMAMover.noOffsets=1; manager.relocate() manager.ULMAMover.path=pathMaker( amount, endT, endL, manager.layerName, centers); var params=new Array(0,0); params=(rounds)? new Array(parseFloat(rounds),0):params; params=(infinite)? new Array(0,1):params; if(alternate){params[++params.length-1]=1}; manager.ULMAMover.run(params) }

formula for case 2.2.1
No Watermark + No Relocation + Add Page Offsets to End Coords

function formula7(manager, amount, endT, endL, centers, startT, startL, rounds, infinite, alternate){ centers=(centers)?manager.layerName:0; startT=(startT)?startT:0; startL=(startL)?startL:0; alternate=(alternate)?1:0; manager.ULMAMover.noOffsets=1; manager.ULMAMover.path=pathMaker( amount, endT+eval(offsetY), endL+eval(offsetX), manager.layerName, centers); var params=new Array(0,0); params=(rounds)? new Array(parseFloat(rounds),0):params; params=(infinite)? new Array(0,1):params; if(alternate){params[++params.length-1]=1}; manager.ULMAMover.run(params) }

formula for case 2.2.2
No Watermark + No Relocation + No Add Page Offsets to End Coords

function formula8(manager, amount, endT, endL, centers, startT, startL, rounds, infinite, alternate){ centers=(centers)?manager.layerName:0; startT=(startT)?startT:0; startL=(startL)?startL:0; alternate=(alternate)?1:0; manager.ULMAMover.noOffsets=1; manager.ULMAMover.path=pathMaker( amount, endT, endL, manager.layerName, centers); var params=new Array(0,0); params=(rounds)? new Array(parseFloat(rounds),0):params; params=(infinite)? new Array(0,1):params; if(alternate){params[++params.length-1]=1}; manager.ULMAMover.run(params) }