Using the TabGroups ('Super-tabs') Feature

Owned by Andrew Wills (Deactivated)
Last updated: Feb 22, 2011Version comment

uPortal TabGroups

Beginning with version 3.2.5, uPortal offers the ability to add an extra level of hierarchy to the layout. The documentation and configuration files refer to this feature by the name TabGroups, but it has also been variously described as 'Super-tabs,' 'Sub-tabs,' and 'Tab-tags.'

The TabGroups feature allows tabs – DLM fragments or personal tabs – to be organized into groups. When this feature is enabled, only one group of tabs will be displayed at any time, and an extra layer of navigation in the user interface that allows users to choose a different Tab Group. There is also a Default Tab Group, which contains all tabs that don't have a TabGroup explicitly set.

Why TabGroups?

TabGroups are especially compelling for portals that have a lot of content, and a large number of portlets and/or tabs per user.

Example: Imaging a user with 70 portlets in his layout. Without TabGroups, these could be organized into 7 tabs or 10 portlets (leading to a lot of vertical scrolling) or 14 tabs of 5 portlets (leading to horizontal tab-wrapping). Using TabGroups, these 14 tabs could be organized into 3 groups, such that the user never sees more than 5 tabs at once.

Enabling TabGroups

To use TabGroups in uPortal, you have to do two things: (1) turn it on; and (2) place tabs into groups.

Warning

Any user whose tabs all belong to the same group, whether or not it is the default tab group, will not see the TabGroups feature. TabGroups automatically shuts itself off in this case. This behavior is especially desirable for the guest (unauthenticated) user, who normally has only 1-2 tabs of content.

Turning on TabGroups

You can enable TabGroups in the portal.properties file. Switch the value of org.jasig.portal.layout.useTabGroups to true.

portal.properties
# Whether or not to use Tab Groups (a.k.a. "Supertabs").
# This feature allows tabs to be organized into groups;  only one group of tabs 
# will be displayed at a time.  Users will experience a two-level tab hierarchy:  
# click on a tab group (top-level tab) to see the tabs in that group;  click on 
# a tab (lower-level tab) to see the portlets on that tab.
#
org.jasig.portal.layout.useTabGroups=false

Placing Tabs into Groups

Tabs can be placed into TabGroups using StructureStylesheetUserPreferences, which are stored in the portal database. NOTE: There are currently no user interface features in uPortal for managing TabGroups. All administration takes place at build and deploy time, and by manipulating the database.

The Import/Export Database Tools are a good way to apply the necessary database changes.

Example fragment-layout File with TabGroups
admin-lo.fragment-layout
[...]

    <tab unremovable="N" immutable="N" hidden="N" name="Admin Tools">
      <structure-attribute type="folder">
        <name>tabGroup</name>
        <value>Administration</value>
      </structure-attribute>
      <column unremovable="N" immutable="N" hidden="N" name="Column">
        <structure-attribute type="folder">
          <name>width</name>
          <value>50%</value>
        </structure-attribute>
        <channel unremovable="" immutable="" hidden="" fname="admin-feature"/>
        <channel unremovable="" immutable="" hidden="" fname="RegisterPortal"/>
      </column>
      <column unremovable="N" immutable="N" hidden="N" name="Column">
        <structure-attribute type="folder">
          <name>width</name>
          <value>50%</value>
        </structure-attribute>
        <channel unremovable="" immutable="" hidden="" fname="portal-administration"/>
        <channel unremovable="" immutable="" hidden="" fname="passwordmgr"/>
        <channel unremovable="" immutable="" hidden="" fname="ImportExportPortlet"/>
      </column>
    </tab>

[...]

Warning

Never re-import an outdated .fragment-layout file against a portal database with existing users. There is a risk that the folder and channel nodes on the fragment will receive new IDs that don't match up with the existing IDs, and users' customizations to that fragment will become corrupted. Always export a .fragment-layout first, apply your changes, then re-import. The fresh export will contain the proper IDs, which will be restored on import.

NOTE: It's a good idea to test this process and verify that it's working correctly before attempting it on production.