Pane splitter (DHTMLSuite.paneSplitter)

Specifications

Widget/Class name: DHTMLSuite.paneSplitter
Demos:
Css: [THEMES_FOLDER]/css/pane-splitter.css
Other classes used by this widget:
- DHTMLSuite.paneSplitter - Main class for the widget.
- DHTMLSuite.paneSplitterPane - Main class for a pane/frame.
- DHTMLSuite.paneSplitterModel - Data source - for the widget.
- DHTMLSuite.paneSplitterPaneModel - Data source for a pane. the paneSplitterModel got an array of objects of this type.
- DHTMLSuite.paneSplitterContentModel - Data source for content/tab inside a pane.

Configuration

The pane splitter widget gives you an alternative to the <frameset> and <frame> tags. This page doesn't have any frames. Instead we have some resizable divs. These divs can be populated with content from external files via ajax or by existing DOM elements on your page.

The first thing we do is to define the content of our panes. Content of panes can be included dynamically from external files, but you can also insert content from existing elements on your page (example: from divs).

Insert content from existing elements on the page

Here, we define content by use of plain HTML. example:

<div id="westContent">This is the content of our west pane.</div>
<div id="northContent">This is the content of our north pane.</div>
<div id="southContent">Content of south pane.</div>
<div id="eastContent">Content of east pane.</div>
<div id="centerContent">Content of center pane.</div>

We have five divs, each one with it's own unique id.

Now, we need to create the Javascript datasource objects, and point them to the divs above. Example code:

The first thing we do is to create a paneSplitterModel. This is the main datasource for our widget. It will contain an array of paneSplitterPaneModel objects which again will contain an array of paneSplitterContentModel objects.

Here are the properties you can send to the constructor of the paneSplitterPaneModel class:

id - id of pane
position - Position of pane, "west", "east", "center", "north" or "south".
resizable - Should the pane be resizable (true or false) - default = true.
collapsable - Should the pane be collapsable (true or false) - default = true
size - Initial size of pane. This option only applies to the north, west, east and south pane. For north and south, size defines height, for west and east it defines width. The size is measured in pixels.
minSize - Minimum width or height of pane.
maxSize - Maximum width or height of pane.
scrollbars - Display scrollbars when there's not enough space for content inside the pane (default = true).
state - Inital state of pane, "expanded" or "collapsed".
callbackOnCollapse - Name of callback function to execute when the pane is collapsed.
callbackOnExpand - Name of callback function to execute when the pane is collapsed.
callbackOnHide - Name of callback function to execute when the pane is collapsed.
callbackOnShow - Name of callback function to execute when the pane is collapsed.
callbackOnSlideOut - Name of callback function to execute when the pane slides out, when someone clicks on the bar while it's collapsed.
callbackOnSlideIn - Name of callback function to execute when the pane slides back in.
callbackOnCloseContent - Name of callback function to execute when content(a tab) inside the pane is closed.
callbackOnBeforeCloseContent - Name of callback function to execute BEFORE content of a pane is closed.
callbackOnTabSwitch - Name of callback function to execute when the user switch between tabs inside the pane.
callbackOnResize - Callback function to execute when the pane is resized by use of the resize handles.

We add panes to the pane splitter by creating new paneSplitterPaneModel and then by using the addPane method. Content is added to a pane by the addContent method. One pane can contain more than one paneSplitterContentModel objects. When it does, navigation tabs will appear at the bottom of the pane.

As you can see from lines like this:

paneWest.addContent(
  new DHTMLSuite.paneSplitterContentModel(
  { id:"westContent",htmlElementId:'westContent',title:'West',tabTitle:'West pane' }
  )
);

we have defined that the content of this pane is the HTML element on the page where id is "westContent". This is how we point it to the div we added above.

The paneSplitterContentModel accepts these arguments to the constructor:

id - Unique id for the content object
closable - Display a close button at the top right corner of the title bar (default = true)
displayRefreshButton - Display a refresh/reload button at the top right corner of the title bar (default = true). This option should only be used when you have content loaded from the server
title - Title to be displayed in the title bar
contentUrl - Path to a file on the server. The content of this file will be displayed inside the pane
htmlElementId - Reference to DOM element on your page which you want to display inside the pane, or just the id you want the HTML element to have in case you need to refer to it later. This means that you can have both a contentUrl and a htmlElementId as long as the htmlElementId doesn't exists on your page already. The pane splitter widget will here create that div for you and insert the content of your server side file into it.
refreshAfterSeconds - Auto refresh content after "n" number of seconds. Default = 0, i.e. "off"

Now, we have created a paneModel object. It contains several panes which again contains content.

All we have to do now is to create a paneSplitter object, and point it to paneModel.

var paneSplitter = new DHTMLSuite.paneSplitter();
paneSplitter.addModel(paneModel); // Add the data model to the pane splitter
paneSplitter.init(); // Add the data model to the pane splitter

Please notice that we have unique ids for our panes and content of the panes.

Add content from external files

It is also possible to add content from external files. This is something we do a lot when the widget has been created. We can add new tabs to panes easily with the addContent method. That's what happens when you select something from the menu at the top of this page.

With this method, we usually use the addContent of the paneSplitter object, and the attribute contentUrl instead of htmlElementId.

Example code:

paneSplitter.addContent('west',
{ id:'newContent',contentUrl:'include/externalFile.php',title:'This is my new tab',tabTitle:'This is the tab title',closable:true }
);

The first argument is the position where content should be inserted. Possible values are "west","east","north","south" and "center". The next argument is an associative array describing the new content tab.

There's also a lot of other methods you can use to add, modify and delete content from the pane splitter. Please see the class documentation for more help.

Call back functions

The pane splitter widgets supports call back function for these events:

Show pane
Hide pane
Expand pane
Collapse pane
Slide out pane
Slide in pane
Close pane content
Before Close pane content
Tab switch
Resize

You define a callback function when you create the pane model. Example:

var paneSouth = new DHTMLSuite.paneSplitterPaneModel( { position : "south", id:"southPane",size:80,minSize:50,maxSize:200,resizable:true,
callbackOnCollapse:'callbackFunction' } );

Here, I have defined that a function with the name "callbackFunction" should be called when the south pane is being collapsed. Also notice that I'm only passing the name of that function.

When the pane is collapsed, then pane splitter widget will call this function and send in three arguments:

A reference to the pane model
A string specifying the action("collapse","expand","show","hide","slideIn","slideOut","closeContent" or "tabSwitch")
A reference to the content model representing the tab currently displayed in the pane.("Active tab")

This is how the callbackFunction could look:

/* This is a demo for a call back function for the panes */
function callbackFunction(modelObj,action,contentObj)
{
self.status = 'Event "' + action + '" triggered for pane with id "' + modelObj.id + '" - content id: ' + contentObj.id;
}

Some notes about callback functions

Please notice that you should only specify the name of eventual call back functions. These function will when they are executed recieve three parameters:

Reference to the pane model, i.e. the paneSplitterPaneModel object
String saying which callback function was executed.
Reference to content object, i.e. a paneSplitterPaneContent object.

Also notice that you the callbackOnBeforeCloseContent call back support checks for return values from the call back function. If you specify a function which asks the user to confirm if content should be closed, the tab will not be closed if the function returns false.

Size of tabs

The tab pane uses all it's available horizontal space. If you want a different setup, you can modify css_dhtmlsuite/pane-splitter.css. This is the css creating this feature:

.DHTMLSuite_paneTabs table{  /* All tabs are placed inside a table */
  table-layout:fixed;
  width:100%;
}

To get the same layout as in the first version of the dhtml suite, change both values("fixed" and "100%") to auto. It is also possible to have different layout for the different panes. For example, let's say you don't want the tabs to use all it's space in the west pane, add this to the css:

#DHTMLSuite_pane_west .DHTMLSuite_paneTabs table{
table-layout:auto;
width:auto;
}

Advertisement:
LudoJS framework
dhtmlchess.com