collective.portlettabber 0.2.0

A jQuery plugin for Plone layouts that merge portlets together obtaining a single portlet with tabs

.. contents:: **Table of contents**

Documentation
=============

This product load into your Plone site the *portlettabber* `jQuery`__ plugin. Before begin to look and
search in the official `jQuery plugin repository`__ for this and waste your time, you must know that the
plugin has been developed specifically for Plone even if you can use simply the Javascript code for other
projects (*maybe someday I will register this as an official jQuery plugin*).

__ http://jquery.com/
__ http://plugins.jquery.com/

What can I do with it?
----------------------

The products *try* to make simple an uncommon (and not-so-simple) task: you can use this to generate
on-the-fly a new portlet with a *tab* looks just using Javascript.
The new portlet will store inside contents grabbed and stolen from other existing portlets inside the
page.

Original portlets are removed by this operation. Why? Because in this way:

* you have no additional portlets if Javascript is disabled
* you see only the new generated portlets for Javascript enabled browsers

How the new portlet looks like?
-------------------------------

The visual effect is similar to the one that Plone use for tabbing form's fieldsets. You have selectable
headers that can be clicked for showing related subelements.

.. table:: The effect of collective.portettabber inside Plone

+------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+------------------------------------------------------------------+
| | | |
| .. figure:: http://keul.it/images/plone/portlettabber-no-js.png | .. figure:: http://keul.it/images/plone/portlettabber-tab1.png | .. figure:: http://keul.it/images/plone/portlettabber-tab2.png |
| :scale: 50 | :scale: 50 | :scale: 50 |
| :alt: No javascript, or no plugin preview | :alt: First tab selected preview | :alt: Second tab selected preview |
| | | |
| This is the portlet column without using the portlettabber plugin (or with Javascript disabled) | First tab selected | ...and second tab selected |
| | | |
+------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+------------------------------------------------------------------+

How to use?
-----------

This product is targeted on developers, so right now you need to have some basic *jQuery/Javascript
knowledge* and you must develop your own piece of product for Plone.

You need to register your own (maybe simple) Javascript source in your Plone product/theme and use in this
way the portlettabber power.

Here an example for the jsregistry.xml GenericSetup import step for your Javascript::

<javascript cacheable="True"
compression="safe"
cookable="True"
enabled="True"
id="myjs-source.js"
insert-after="++resource++jquery.portlettabber.js"
inline="False" />

What you need to put inside? The most simple example I can find (and that works for Plone Classic and Sunburst theme)
is this::

jq(document).ready(function() {
try {
var generatedPortlet = jq.tabbedportlet();

generatedPortlet.makeTab("#portal-column-two .portletNews");
generatedPortlet.makeTab("#portal-column-two .portlet-foo");
jq("#portal-column-two div:not(.managePortletsLink):last").prepend(generatedPortlet.getPortlet());
} catch(error) {
if (window.console)
window.console.log("Something goes wrong with portlettabber: " + error.message);
}
});

At load time, you can create a new *portlettabber object*. This object have some features you will need to
rely on for obtaining the new portlet.

After obtaining the *generatedPortlet* object, you can use the public *makePortlet* method to take an
existing portlet from the page and put it inside a tab.

Above we are doing it for two portlet, one for every *makeTab* call. The parameter you must provide to
this method must be a *DOM element* or a jQuery selector (in this case if it wrap more that one element,
only the first is used).

The *try/catch* statement raise the fault tolerance in case something goes wrong (a developer can still
see what's the problem on his Firebug/Safari/Chrome console).

You can change the "*prepend*" call above to "*append*" to put the generated portlet as last item in the column. The
jQuery expression given take care to always keep the "Manage portlets" link at the end of the column.

You can do a lot more (if you know what you are doing, you can move your portlet where you want inside the page).
Please, check the `jQuery reference`__ for know how.

__ http://api.jquery.com/category/manipulation/

Structure
---------

The plugin make some assumptions on the structure of the portlet. You can however customize it a little
(see below).

The final result will be an XHTML structure like this::

<portletNodeType class="portletNodeClasses-1 [portletNodeClasses-2 ...]
portletNodeAdditionalClasses1 [portletNodeAdditionalClasses2 ...]">
<portletHeaderNodeType class="portletHeaderNodeClasses-1 [portletHeaderNodeClasses-2 ...]">
<ul class="portletTabs">
<li class="portletTab">
<a href="javascript:;">{Header text... only the text}</a>
</li>
[...]
</ul>
</portletHeaderNodeType>
<portletDataNodeType class="portletDataNodeClasses1 [portletDataNodeClasses2 ...]">
{same content as in the old portlet, I mean all HTML and DOM events}
</portletDataNodeType>
[...]
</portletNodeType>

Can I use this for other (X)HTML structure?
-------------------------------------------

Yes! You can customize the following:

`portletNodeType` (String)
HTML element that store a portlet. Default 'dl'
`portletNodeClasses` (Array)
list of CSS classes that must be added to the generated portlet but also
found in the portlet that became a new tab. Default 'portlet'
`portletNodeAdditionalClasses` (Array)
additional list of classes that will be added to the generated
portlet (use this if you want to add to tabbed portlet some new classes).
Default 'portletTabGenerated'
`portletHeaderNodeType` (String)
the element used to generate the portlet header (and also must be the
header of all portlet that became new tab. Default 'dt'
`portletHeaderNodeClasses` (Array)
list of CSS classes that must be added to the generated header but
also found in the header of the portlet that became a new tab. Default 'portletHeader'
`portletDataNodeType` (String)
the element used to generate the portlet element (and also must be the
element type inside all portlet that became new tab. Default 'dd'
`portletDataNodeClasses` (Array)
array of classes for portletDataNodeType elements that are valid to be
used as elements inside the new portlet. Elements that aren't using at least one of those CSS classes
will not be moved to the tab and simply disappear from the page after makeTab() call.
Default 'portletItem' and 'portletFooter'
`id` (String)
an optional HTML id to be added to the portlet. Default *null*.

To use options above just write sentences like this::

jq(document).ready(function() {
var generatedPortlet = jq.tabbedportlet({portletNodeClasses: ['portlet','notBasicClass']});
...
});

In this way you can use the default value for all options but set a custom value for one or more of them.

Some more options available for new tabs?
-----------------------------------------

The *makeTab* method can rely with some additional parameters:

`cutChars` (Integer)
When label stolen from the tabbed portlet can be too long, put there the maximum number of characters
after which the tab header will only display this number on characters followed by the *&hellip;*.
Default 0 (all the text found in old portlet)
`label` (String)
Show this label, not the one you'll find inside the grabbed header.
Default *null* (use original text found in old portlet)
`select` (Boolean)
Select this tab as default.
Default *false* (the first tab added is selected)

To use one or more of those::

jq(document).ready(function() {
...
generatedPortlet.makeTab("#portal-column-two .portletNews", {label: 'Hello!', select: true});
...
});

Development status
==================

Maybe that there are a lot of use-cases where it can fail right now... for example there aren't much
error check.
Using a try/catch statement around your tab actions avoid problems...

Future versions probably will be a more common jQuery plugin (with chaining purpose).

Credits
=======

Developed with the support of `Regione Emilia Romagna`__; Regione Emilia Romagna supports
the `PloneGov initiative`__.

__ http://www.regione.emilia-romagna.it/
__ http://www.plonegov.it/

Authors
=======

This product was developed by RedTurtle Technology team.

.. image:: http://www.redturtle.net/redturtle_banner.png
:alt: RedTurtle Technology Site
:target: http://www.redturtle.net/


Changelog
=========

0.2.0 (2010-12-09)
------------------

* Changed documentation examples to works also with Plone 4 and Sunburst theme [keul]
* Added CSS rules to see tab effect also on Sunburts theme [keul]
* Javascript cleanup with JSLint [keul]
* Uninstall properly [keul]
* Some cleanup in the egg structure [keul]

0.1.0 (2010-05-17)
------------------

* Grabbed tab label was ignoring text if this was in the table header root [keul]
* A better example in README file, adding try/catch statement [keul]

0.0.2a (2010-05-05)
-------------------

* Removed debug stuff that grab the news item portlet [keul]
* Do not show generated portlet if the portlet is empty [keul]

0.0.1a (2010-05-02)
-------------------

* Initial (alpha) release