collective.portlettabber 0.2.0

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

Table of contents

• Documentation

  • What can I do with it?

  • How the new portlet looks like?

  • How to use?

  • Structure

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

  • Some more options available for new tabs?

• Development status

• Credits

• Authors

• Changelog

  • 0.2.0 (2010-12-09)

  • 0.1.0 (2010-05-17)

  • 0.0.2a (2010-05-05)

  • 0.0.1a (2010-05-02)

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).

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.

The effect of collective.portettabber inside Plone

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.

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 …. 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.

Authors

This product was developed by RedTurtle Technology team.

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