TabGroups ('Super-tabs') Feature

Owned by Andrew Wills
Aug 27, 2013
5 min read

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.

Step 1: 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

Step 2: 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.

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.

Example fragment-layout File with TabGroups

Below is an example where the TabGroup, 'Sample Tabs', contains four tabs, each with one portlet. In uPortal 4, the structure is slightly different where <tab> is no longer used and it has been replaced with <folder>.

<!-- IDs are unique identifiers. Your ID numbers will be different. Export your layout and re-import as stated above -->
 
<?xml version="1.0" encoding="UTF-8"?>
<layout xmlns:dlm="http://www.uportal.org/layout/dlm" script="classpath://org/jasig/portal/io/import-layout_v3-2.crn" username="sample-lo">
  <folder ID="s1" hidden="false" immutable="false" name="Root folder" type="root" unremovable="true">
    <folder ID="s2" hidden="true" immutable="true" name="Header folder" type="header" unremovable="true">
      <channel fname="fragment-admin-exit" unremovable="false" hidden="false" immutable="false" ID="n3"/>
    </folder>
    <folder ID="s4" hidden="false" immutable="false" name="Footer folder" type="footer" unremovable="false"/>
    <folder ID="s16" hidden="false" immutable="false" name="My First Sub Tab" type="regular" unremovable="false">
         <structure-attribute type="folder">
                <name>tabGroup</name>
                <value>Sample Tabs</value>
        </structure-attribute>
        <channel fname="my-portlet1" unremovable="false" hidden="false" immutable="false" ID="n62"/>
    </folder>
    <folder ID="s21" hidden="false" immutable="false" name="My Second Sub Tab" type="regular" unremovable="false">
          <structure-attribute type="folder">
                <name>tabGroup</name>
                <value>Sample Tabs</value>
          </structure-attribute>
          <channel fname="my-portlet2" unremovable="false" hidden="false" immutable="false" ID="n65"/>
    </folder>
   <folder ID="s22" hidden="false" immutable="false" name="My Third Sub Tab" type="regular" unremovable="false">
        <structure-attribute type="folder">
                <name>tabGroup</name>
                <value>Sample Tabs</value>
        </structure-attribute>
        <channel fname="my-portlet3" unremovable="false" hidden="false" immutable="false" ID="n68"/>
    </folder>
    <folder ID="s23" hidden="false" immutable="false" name="My Fourth Sub Tab" type="regular" unremovable="false">
         <structure-attribute type="folder">
                <name>tabGroup</name>
                <value>Sample Tabs</value>
        </structure-attribute>
        <channel fname="my-portlet4" unremovable="false" hidden="false" immutable="false" ID="n71"/>
    </folder>
  </folder>
</layout>

Step 3: Styling the TabGroups

By default, tab groups are not styled and appear as an unordered list of links. Below is an example of some css to create stylized tabs:

The css code example below was provided by Arvīds Grabovskis  

#Place code in your theme directory /uportal-war/src/main/webapp/media/skins/universality/<your theme>/portal.css
#Code below will need to be revised to reflect your theme's color scheme
 
#portalNavigationTabGroup{background:#006b67 url('images/bg_menu_v2.gif') repeat-x top left;padding:0 22px;}
#portalNavigationTabGroupsList{margin:0;padding:0;}
#portalNavigationTabGroupsList li{display:inline-block;border-right:1px solid #475454;list-style-type:none;}
#portalNavigationTabGroupsList li:hover, #portalNavigationTabGroupsList .tabGroupListActive {background:#ececec url('images/bg_menu_sel_v2.gif') repeat-x top left;}
#portalNavigationTabGroupsList li:hover a, #portalNavigationTabGroupsList .tabGroupListActive a{color:#000;}
#portalNavigationTabGroupsList a{color:#fff;text-decoration:none;font-size:14px; padding: 5px 15px; float:left;}

Additional TabGroup Notes

  • The "More" tab is shown whenever you have tab groups enabled and one or more tabs do not have a tabGroup attribute specified. 
  • When clicking on the "Add Tab", a sub-tab will be under the active tabGroup 
  • The best practice approach is to: 1) Export a fragment layout, 2) Modify the xml with tabGroups, 3) Import your modified fragment layout