How to add a functional dock to jquery.mb.containerPlus

Many times people are asking me to implement features to my jquery components but most of the times those features are easily implementable by adding custom behavior to the callbacks functions yet available.
In ths post we’ll see how to realize a functional dock element for the mb.containerPlus.

For this tutorial I’m using the latest 2.5.0 release of this component that has implemented a new onCreate event callback and many other useful features (take a look at the component page).


1. How should it works?

In my project I need that for each container in the page there should be a small icon rapresenting it in a specific place called “Dock”. The “Dock” element is the place where all the containers are collected once minimized. This behavior is already implemented in the component but as default the iconized container icon is placed as last of the dock area and it’s not shown once the container is open.

So, in my case I want the icons to be alwais visible except when the container is closed and shoud mantain ther position in the dock area. Those icons should also have some actions for restoring/iconizig the corresponding container.


2. How to obtain this behavior?

mb.containerPlus has callbacks events that let you implement additional functionalities for their behavior.

The standard initialization of a containerPlus does not introduce callbacks.

this is the simple code:

[sourcecode language=”javascript”]
$(".containerPlus").buildContainers({
containment:"document",
elementsPath:"../elements/"
});
[/sourcecode]

For this tutorial we have to create some extra methods to be invoked once the container is initialized, once it’s iconized and once it’s restored.

the final initialization code will be:

[sourcecode language=”javascript”]
$(".containerPlus").buildContainers({
containment:"document",
elementsPath:"../elements/",
dockedIconDim:45,
<strong>onCreate</strong>:function(o){<strong>initDock(o,"dock")</strong>},
<strong>onClose</strong>:function(o){<strong>close(o)</strong>},
<strong>onRestore</strong>:function(o){<strong>restore(o)</strong>},
<strong>onIconize</strong>:function(o){<strong>iconize(o)</strong>},
effectDuration:300
})
[/sourcecode]

As you can see some extra methods has been added as callbak to the init function.

onCreate callback:

On the onCreate event I added the initDock(o,dockID) function that build the placeholder for the initialized container icon on the “Dock”; the function is:

[sourcecode language=”javascript”]
function <strong>initDock(o,docID)</strong>{
var opt= o.get(0).options;
var docEl=$("<span>").attr("id",o.attr("id")+"_dock").css({width:opt.dockedIconDim+5,display:"inline-block"});
var icon= $("<img>").attr("src",opt.elementsPath+"icons/"+(o.attr("icon")?o.attr("icon"):"restore.png")).css({opacity:.4,width:opt.dockedIconDim, cursor:"pointer"});
icon.click(function(){o.mb_iconize()});
docEl.append(icon);
$("#"+docID).append(docEl);
o.attr("dock",o.attr("id")+"_dock");
}
[/sourcecode]

The two parameters I’m passing to the function are the container element (o) provided by the mb.containerPlus callback method and the “Dock” element ID (docID).

Here is what this function does:

[sourcecode language=”javascript”]
var <strong>opt</strong>= o.get(0).options;
[/sourcecode]

it fills the opt variable with the container options to get easily some usefull properties for its manipulation.

[sourcecode language=”javascript”]
var docEl=$("<span>").attr("id",o.attr("id")+"_dock").css({width:opt.dockedIconDim+5,display:"inline-block"});
[/sourcecode]

it defines the placeholder for the container icon on the dock as docEl, setting an ID (composed by the container ID and a “_dock” postfix ) and some CSS properties: the width retrived from the dockedIconDim option setted as option of the init function.

[sourcecode language=”javascript”]
var icon= $("<img>").attr("src",opt.elementsPath+"icons/"+(o.attr("icon")?o.attr("icon"):"restore.png")).css({opacity:.4,width:opt.dockedIconDim, cursor:"pointer"});
[/sourcecode]

it defines the icon element to be placed inside the placeholder retriving it from the container attribute “icon” created by the metadata written in the container DIV class.

[sourcecode language=”javascript”]
icon.click(function(){o.mb_iconize()});
[/sourcecode]

it attaches an onclick event to the icon to iconize the corresponding container.

[sourcecode language=”javascript”]
docEl.append(icon);
$("#"+docID).append(docEl);
[/sourcecode]
it places the icon into the placeholder and than the placeholder into the “Dock” element.

[sourcecode language=”javascript”]
o.attr("dock",o.attr("id")+"_dock");
[/sourcecode]
it redefines the “dock” attribute of the container to let it iconize into its placeholder.

onClose callback:

On the onClose event I added the close(o) function that hide the placeholder icon once the container is closed:

[sourcecode language=”javascript”]
function close(o){
$("#"+o.attr("dock")).find("img:first").hide();
}
[/sourcecode]

onRestore callback:

On the onRestore event I added the restore(o) function that shows the placeholder icon of the restored container:

[sourcecode language=”javascript”]
function restore(o){
$("#"+o.attr("dock")).find("img:first").show();
}
[/sourcecode]

onIconize callback:

On the onIconize event I added the iconize(o) function that hides the placeholder icon of the iconized container; the mb.containerPlus component will fill the “Dock” placeholder with its icon:

[sourcecode language=”javascript”]
function iconize(o){
$("#"+o.attr("dock")).find("img:first").hide();
}
[/sourcecode]


3. The javascript code:

Here is the initialization javascript code for containers in this tutorial:

[sourcecode language=”javascript”]
$(function(){
function initDock(o,docID){
var opt= o.get(0).options;
var docEl=$("&lt;span&gt;").attr("id",o.attr("id")+"_dock").css({width:opt.dockedIconDim+5,display:"inline-block"});
var icon= $("&lt;img&gt;").attr("src",opt.elementsPath+"icons/"+(o.attr("icon")?o.attr("icon"):"restore.png")).css({opacity:.4,width:opt.dockedIconDim, cursor:"pointer"});
icon.click(function(){o.mb_iconize()});
docEl.append(icon);
$("#"+docID).append(docEl);
o.attr("dock",o.attr("id")+"_dock");
}
function iconize(o){
$("#"+o.attr("dock")).find("img:first").hide();
}
function <strong>restore</strong>(o){
$("#"+o.attr("dock")).find("img:first").show();
}
function <strong>close</strong>(o){
$("#"+o.attr("dock")).find("img:first").hide();
}
$(".containerPlus").buildContainers({
containment:"document",
elementsPath:"../elements/",
dockedIconDim:45,
onCreate:function(o){initDock(o,"dock")},
onClose:function(o){close(o)},
onRestore:function(o){restore(o)},
onIconize:function(o){iconize(o)},
effectDuration:300
});
});
[/sourcecode]


4. The HTML code:

And here the HTML code to define a container:

[sourcecode language=”javascript”]
<div id="c1" class="containerPlus draggable resizable {buttons:’m,i,c’, icon:’browser.png’, skin:’black’, width:’500′,iconized:’true’, dock:’dock’, title:’container 1′}" style="position:fixed;top:130px;left:400px">
Content goes here
</div>
[/sourcecode]

As you can see the code to define the containerPlus is really simplified respect previous versions. You don’t need to write all the container structure but only the content.

for those who are upgrading from prvious version there’s no need to rewrite the containers HTML code; the component itself will detect if the code has all the structure or not and it’ll work consequently.

take a look at the demo


This demo is included in the component package you can download from the mb.containerPlus page:

go to the component page