DP_PanelManager

Once a panel is added to a Panel Manager several properties and methods are added to the panel.

Panel properties available:

• panelManager: A reference to the PanelManager instance that holds this panel.
• DefaultDisplay: The default display property (used for the setDisplay(“show”) method).

DP_RequestPool methods available:

• PanelInstance.load()
• PanelInstance.getVisibility()
• PanelInstance.setVisibility()
• PanelInstance.getDisplay()
• PanelInstance.setDisplay()
• PanelInstance.getOrder()
• PanelInstance.setOrder()
• PanelInstance.hasCollisionWith()
• PanelInstance.getDistanceFrom()
• PanelInstance.getPosition()
• PanelInstance.setPosition()
• PanelInstance.shiftPosition()
• PanelInstance.getSize()
• PanelInstance.setSize()
• PanelInstance.shiftSize()
• PanelInstance.getOpacity()
• PanelInstance.setOpacity()
• PanelInstance.shiftOpacity()
• PanelInstance.addEvent()
• PanelInstance.removeEvent()
• PanelInstance.handleEvent()

Note that in method/function signatures a pipe (“|”) indicates “OR” while arguments in square brackets are optional.

PanelInstance.load()

PanelInstance.getVisibility()

PanelInstance.setVisibility()

PanelInstance.getDisplay()

PanelInstance.setDisplay()

PanelInstance.getOrder()

PanelInstance.setOrder()

PanelInstance.hasCollisionWith()

PanelInstance.getDistanceFrom()

PanelInstance.getPosition()

PanelInstance.setPosition()

PanelInstance.shiftPosition()

PanelInstance.getSize()

PanelInstance.setSize()

PanelInstance.shiftSize()

PanelInstance.getOpacity()

PanelInstance.setOpacity()

PanelInstance.shiftOpacity()

PanelInstance.addEvent()

PanelInstance.removeEvent()

PanelInstance.handleEvent()

Panel Mananger Demo

The Panel Manager Demo allows you to create and manipulate panels using the various panel methods. See the end of this section for more practical examples of use.

Instantiating a PanelManager

You instantiate a PanelManager for use as you would any other JavaScript Object. The following line will instantiate a PanelManager calls “MyPanels”:

MyPanels = new DP_PanelManager();

At this point the PanelManager is created and ready to be used. You can now use the general methods getWindowSize(), getCanvasSize(), getMousePosition(), newPanel() and addPanel(). However the PanelManager does not, at this point, actually contain any panels.

You can create as many PanelManagers as required. For example you might want to create a PanelManager to contain all panels related to a menu and another to hold all the panels related to the content area. This would allow you to easily access these collections as single units (for example you could easily hide all menu items by looping over the Panels property of the appropriate PanelManager).

Creating Panels

Panels can be created using either the newPanel() or addPanel() methods.

Using newPanel() creates a new HTML element and adds it to the document (appending it to the BODY element). The ID of the panel becomes the HTML ID of the new element. For example:

myPanel1 = PanelManager.newPanel("myPanel1");

The above creates a new DIV element (the default element type) as the last child of the BODY element. The new element’s HTML ID is “myPanel1”. Panels created in this way are, by default, hidden from view. Use the setDisplay() method to reveal them.

Using addPanel() allows you create a panel from an existing HTML element (referenced by the HTML ID). Assuming that there’s a DIV on the page with an ID of “MenuItem1” you could create a panel out of this element using:

myPanel2 = PanelManager.addPanel("MenuItem1");

Once a panel is created it is accessible, using indexed notation by ID, in the “Panels” property (a JavaScript object) of the PanelManager. All Panel-specific methods will be available directly as methods of the element: any method (getElementById, getElementByTagName, etc) that returns a reference to the element can be used to access all panel-specific methods. Considering the above example the following would both work:

PanelManager.panels["MenuItem1"].getPosition();

document.getElementById("MenuItem1").getPosition();

Manipulating Panels

Once you have a reference to the panel (the HTML element) you can call panel methods to easily manipulate panels. You can also, of course, still access all general HTML properties and styles. For example to assuming the PanelManager “MyPanels” you could create a new panel, set it’s size, color and content and then cause it to fade slowly into view using the following code:

		// Create the Panel
	CurPanel = MyPanels.newPanel("myPanel1");
			// Size and position
	CurPanel.setSize([200, 200]);
		// Style the Panel
	CurPanel.style.backgroundColor = "#cccccc";
		// Load Content
	CurPanel.load("<div style='padding: 10px'>This is Panel One!</div>");
		// Set the Panel Opacity to 0 (completely transparent)
	CurPanel.setOpacity(0);
		// Display the (now transparent and thus invisible) panel
	CurPanel.setDisplay("show");
		// Fade the panel in over five seconds
	CurPanel.setOpacity(100, 0, 5000);
	

Although most lines in the above code simply run and take immediate effect the last line uses the “duration” argument to define an animation. The panel will take 5 seconds (5000 milliseconds) to fade from opacity 0 (completely transparent) to opacity 100 (completely opaque).

Remember that all “set” and “shift” manipulations will be launched as soon as they’re encountered in the code. To chain manipulations into complex effects use the “delay” argument in these methods to postpone effects. Let’s assume that after your panel is fully visible you want to, over one second, slide it 200 pixels to the right. You can do this by added the following (note that the relative “shift” method is used rather than the direct “set” method):

		// Slide the panel to the left
	CurPanel.shiftPosition([null,200], 5000, 1000);
	

The second argument (“5000”) is the number of milliseconds to delay the change – in this case 5 seconds (or, to be more specific, right after the fade animation is complete). The third argument is the duration, again in milliseconds, for the this animation (in this case the panel will take 1 second to move 200 pixels to the right).

Manipulations can also cross over. Finally assume that halfway through the movement you want your panel to start growing wider. You could add this line:

		// Widen the panel
	CurPanel.shiftSize([0,100], 5500, 500);
	

This animation increases the size of the panel by 50% (100 pixels) but waits for 5.5 seconds to do it (so it will begin about halfway through the movement animation). Once it starts it runs concurrently with the shiftPosition() method.

The manipulations you can perform are essentially endless.

Managing Panel Events

Cross-browser event management can present challenges. The abstraction methods provided to Panels can help to simplify this. Events are any of a collection of actions that can be recognized by the browser: clicking the mouse, pressing a keyboard key, resizing a window. Handlers are functions which run after a specified event has occurred (such as highlighting a tab when it’s been clicked). Linking handlers to events is the core function of event management.

To link a handler to an event use the addEvent() method. Pass it an event (such as “click”) and a function to run when that event occurs. You can add multiple handlers to a single event, but duplicate handlers will be discarded. For example to run the “doStuff()” function when a panel is clicked use this:

MyPanel.addEvent("click", doStuff);

Note that the doStuff function is passed as data (in other words the function itself is passed, “doStuff”, not a call to the function as in “doStuff()”). You can place arbitrary code in a handler, but it must be wrapped in a function. To add an alert to the panel you could do this:

MyPanel.addEvent("click", function() {alert("Hello")});

To remove events from panels use the removeEvent() method and pass it the exact same parameters used to create the event. To remove the events we just added us this:

MyPanel.removeEvent("click", doStuff);

MyPanel.removeEvent("click", function() {alert("Hello")});

Handler functions are called as methods of the Panel to which they’ve been assigned and will be passed a DOM “event” object representing the current event. This means that within the handler the “this” keyword will refer to the panel. This greatly simplifies the creation of handlers. Assume that we have three Panels, One, Two and Three and that we want the current position of a panel to be displayed when it’s clicked. The following code would accomplish this:

		// Create the Handler
	showSize = function(event){
		alert(this.getSize());
	};
	One.addEvent("click", showSize);
	Two.addEvent("click", showSize);
	Three.addEvent("click", showSize);
	

Although there is only one handler it’s called in the context of the clicked panel making it applicable to all of them.

Managing events in this manner can greatly streamline and simplify your code.

Working with Mouse Position

Getting the mouse position requires an event object. Event objects describe the environment and circumstances of an event (mouse and keyboard states, the element and action related to the event and so forth). Event objects are automatically created (in modern browsers) whenever an event is fired and passed to any registered event handlers.

Here is a simple event handler for the “mousemove” event. This handler then passes the event object to the DP_PanelManager getMousePosition() method:

	document.onmousemove = function(Event) {
		CurMouseCoords = PanelManager.getMousePosition(Event);
		...
	};
	

All events create an Event object that can be to getMousePosition() method. A common requirement is to track not only that an object was clicked, but where it was clicked. We can do this easily using DP_PanelManager by creating the following event handler:

	getClickPos = function(Event) {
			// Get the Current Mouse Position
		var CurMousePos = PanelManager.getMousePosition(Event);
			// Get the Current Panel Position
		var CurPanelPos = this.getPosition();
			// Calculate the Panel Click Position
		var CurTop = CurMousePos[0] - CurPanelPos[0];
		var CurLeft = CurMousePos[1] - CurPanelPos[1];
			// Show the results
		alert([CurTop,CurLeft]);
	};
	myPanel.addEvent("click", getClickPos);
	

The last line registers the handler to the “click” event of “myPanel”. Now, when clicked, the getClickPos() handler will run. The related Event object will be automatically created and passed to it.

The handler passes the event object forward to getMousePosition() which returns the mouse position relative to the canvas. The handler then (using the “this” keyword) gets the position of the clicked panel, again realtive to the canvas.

Because all positions returned are in the form of “[Top,Left]” the calculation to get the click location on the panel is simple: current mouse position minus the panel position.

The event handler then alerts the user to the click location.

More About Events

A full discussion of events and how to work with the Event object is beyond the scope of these instructions. Information on the Internet Explorer implementation of events can be found at the Microsoft Developer’s Network while information related to FireFox and other Mozilla browsers can be found at the Mozilla Developer Center.

Practical Examples

The following examples provide insight into “real-world” usages of the component and explore how it can be used to meet common development tasks.

Animated Menu

A fairly simple animated menu. When the mouse is over each menu item a panel appears with content. This code demonstrates many aspects of DP_PanelManager:

• The “menu” panels are generated from pre-existing (and relatively positioned) HTML Elements. Moving the menu (for example by changing the padding of the containing elements) will not affect the functionality.
• The “popup” panels are created on the fly and then positioned relative to their parent menu items. Note that the popups are actually created as properties of the menu items. This makes accessing them later much simpler.
• The mouseover and mouseout events are managed using the DP_PanelManager abstractions. Notice how the event handler functions make use of the “this” keyword and use the “delay” attribute to chain the animations.

Drag-and-Drop with Collision Detection

Next is a simple drag-and-drop demonstration which also demonstrates collision detection. Although the library does not, directly, support drag and drop functionality it does simplify building such functionality. Using collision detection allows you to perform actions when panels “collide” (overlap). In this example the dragged panel will change color when colliding with another panel.

Drag-and-Drop with Ordering

Next is a more complex drag-and-drop demonstration which also demonstrates ordering of elements built using the getPanelList() method. Again while the library does not provide this functionality directly it greatly eases the complexity of implementation.

Note that two panel managers are used in this example: one to hold the orderable elements and another used for just the BODY element. This prevents the BODY element from being returned in the Ordered PanelList.

It’s a Frog. (Drag and Drop, Collision, Bearing and a Fly.)

This is just a toy that demonstrates drag-and-drop with bearing resolution (the Frog’s eyes will follow the fly) and collision detection.

Popup Definitions

Now we have a common problem: showing definitions for words or concepts without leaving the content. This example provides popup definitions for highlit words when you mouse over them.

Useless Animation

This last example is essentially useless. It creates a grid of many panels and then randomly alters their properties. It is fun to watch (at least for a little while) and does demonstrate several aspects of DP_PanelManager.

June 8, 2013

• Initial GITHUB release.

April 23, 2008

• Updated “getDistanceFrom()” to include bearing (direction on a 360 degree plane) and directionality (on the Y/X axis).
• Added a new example to demonstrate this new feature.

November 21, 2007

• Fixed bug with “setOrder()” panel method when passing a numeric value.
• Added new panelManager method “getPanelList()”. This method accepts a property (Height, Width, Top, Left, Opacity, Order, ID) and returns an array of references to the Panels in the mananger ordered by that property.

November 20, 2007

• Added new panel method “hasCollisionWith()”. This method accepts a panel as input and returns “false” if the panels are not overlapping (colliding) and “true” if they are.
• Added new panel method “getDistanceFrom()”. This method accepts a panel as input and returns the distance (as an array in the format [Y,X]) between the panels. A negative value indicates that the panels are overlapping in that axis (such that both value being negative indicate that the panels are directly overlapping).

September 28, 2007

• You can now create a panel out of the “window” object. This allows you to manage window events but most panel methods will will error (as the window object lacks a style element).

May 01, 2007

• The component now allows for “anonymous” members – HTML elements without IDs.
• New panels can now be generated anonymously (without IDs).
• Closures, rather than evaluate, are now used for the generation of animation frames. This should speed animation slightly and eliminates some animation cross-over problems.

April 11, 2007

• Initial Release.