Adding Breadcrumbs to the Fluid Navigator

The Fluid Navigator is the new navigation technique that most closely resembles to old Classic style drop down menu navigation.  If you have not yet had the chance to convert your entire menu structure to use more modern navigation techniques, then you are stuck having to rely on the Fluid Navigator to get you where you need to be in some cases.  One major limitation of the Fluid Navigator is that is does not show you breadcrumbs when drilling down into the menu structure.  Not having breadcrumbs displayed makes it much harder to quickly jump around the menu.  In this post, I will demonstrate how you can add breadcrumbs to your Fluid Navigator.

This solution will be achieved using the Related Content Framework Event Mapping functionality.  We will be mapping two separate application classes to a couple of CREFs in the application.  One application class will be mapped to the component level post build event of the Fluid NavBar.

And the other application class will be mapped to the component level post build event of the Fluid Navigator.

I have included all of the applicable objects for this solution in an App Designer project.

CLICK HERE to download the project.

Project Overview:

Once you import this project into App Designer, you can open up the PSM_BREADCRUMB_NAV Application Package and take a peek at the two classes that will be getting mapped with Event Mapping.  The first class is named DisplayBreadcrumbs.  This class is used to keep track of the portal registry folder objects that the user drills into when navigating.  The folder names serve as the breadcrumbs and they will get displayed at the top of the Fluid Navigator as the user navigates.  When a user clicks on the breadcrumb, the Navigator content area will display the folder’s contents.

import PT_RCF:ServiceInterface;
import PTNUI:NavBarContentArea:NBContentCollection;
import PTNUI:NavBarContentArea:NBContent;

class DisplayBreadcrumbs implements PT_RCF:ServiceInterface
 method execute();
end-class;

/* This is a reference to the current nav bar content collection */
Component PTNUI:NavBarContentArea:NBContentCollection &ptnui_CurContentColl;

/* Use this function to get a reference to the appropriate portal */
Declare Function PortalOpen PeopleCode FUNCLIB_PORTAL.PORTAL_GEN_FUNC FieldFormula;

/* Use this function to set what shows up in the content (menu) area */
Declare Function SetContentArea PeopleCode PTNUI_DOCK_REC.PTNUI_NB_ACTION FieldFormula;

Declare Function GetLocalNodeContentURI PeopleCode PTNUI_NB_WRK.FUNCLIB FieldFormula;

method execute
 /+ Extends/implements PT_RCF:ServiceInterface.execute +/
 
 /* If the nav bar content collection is blank then return */
 If None(&ptnui_CurContentColl) Then
 Return;
 End-If;
 
 /* The FLDR parameter will be the folder that the user clicked on */
 Local string &sFolder = %Request.GetParameter("FLDR");
 
 Local string &standalone = %Request.GetParameter("sa");
 
 /* If no folder was passed in, then the user must be a the root */
 If None(&sFolder) Then
 &sFolder = "PORTAL_ROOT_OBJECT";
 End-If;
 
 /* Get a reference to the current portal */
 Local ApiObject &portal = PortalOpen();
 
 /* Get a reference to the current portal registry folder object */
 Local ApiObject &sParentFolder = &portal.FindFolderByName(&sFolder);
 
 Local integer &iBreadcrumbCount = 0;
 
 /* While the parent folder exists */
 While All(&sParentFolder)
 
 /* Generate the URL to invoke when the breadcrumb is clicked on */
 Local string &sUrl = GetLocalNodeContentURI() | "/c/NUI_FRAMEWORK.PTNUI_MENU_COMP.GBL?sa=" | &standalone | "&FLDR=" | &sParentFolder.name;
 If &standalone <> "y" Then
 &sUrl = "javascript:PTNavBar.OpenInContentArea('" | &sUrl | "&ICDoModal=1&ICGrouplet=1', '" | &sParentFolder.name | "');";
 End-If;
 
 /* Change the label for the Root folder */
 If (&sParentFolder.name = "PORTAL_ROOT_OBJECT") Then
 &sParentFolder.label = "Main Menu";
 End-If;
 
 /* Create NBContent object to represent the breadcrumb in the nav bar */
 Local PTNUI:NavBarContentArea:NBContent &oParentBreadCrumb = create PTNUI:NavBarContentArea:NBContent(&sParentFolder.name, &sParentFolder.label, &sUrl);
 
 /* Set a custom style to differentiate the breadcrumbs from the normal nav bar content items */
 If (&iBreadcrumbCount > 0) Then
 &oParentBreadCrumb.style = "psm_breadcrumb"; /* Parent breadcrumb */
 Else
 &oParentBreadCrumb.style = "psm_breadcrumb_selected"; /* Current breadcrumb */
 End-If;
 
 /* Set the breadcrumb to show at the top of the nav bar content collection */
 &ptnui_CurContentColl.InsertItemAtStart(&oParentBreadCrumb);
 
 /* Reference the current folder's parent */
 &sParentFolder = &portal.FindFolderByName(&sParentFolder.ParentName);
 
 &iBreadcrumbCount = &iBreadcrumbCount + 1;
 
 End-While;
 
 /* Set the content area equal to the modified nav bar content collection */
 SetContentArea(&portal, &ptnui_CurContentColl);
 
 /* Close the PortalRegistry object */
 &portal.close();
 
end-method;

The second class is named StyleBreadcrumbs.  This class is just used to inject custom styles and scripts when the NavBar is clicked by making use of the AddStyleSheet and AddJavaScript functions.  The main style sheet (PSM_BREADCRUMB) will be used to apply a special style to the breadcrumbs so that they cosmetically differ from non-breadcrumb items in the Fluid Navigator.

import PT_RCF:ServiceInterface;

class StyleBreadcrumbs implements PT_RCF:ServiceInterface
 method execute();
end-class;

method execute
 /+ Extends/implements PT_RCF:ServiceInterface.execute +/
 
 /* Hide the delivered Navigator header */
 AddStyleSheet(StyleSheet.PSM_HIDE_NAVIGATOR_HEADER);
 
 /* Override the size of the Navigator menu items */
 AddStyleSheet(StyleSheet.PSM_SMALL_NAVIGATOR_ITEMS);
 
 /* Apply a custom style to the breadcrumbs in the Navigator */
 AddStyleSheet(StyleSheet.PSM_BREADCRUMB);
 
 /* Automatically open the Navigator when the NavBar is clicked */
 AddJavaScript(HTML.PSM_OPEN_NAVIGATOR);
 
end-method;

The included PSM_BREADCRUMB style sheet in the project applies a rather basic styling to the breadcrumbs.  I am sure there is a way to make the breadcrumbs more visually appealing, but I do not have an eye for design.  I am certainly open to enhancement suggestions on this!

Project Configuration:

Now that we have a basic understanding of the technical details of this project, we are now ready to perform the Event Mapping configuration for this solution.  You will need to navigate to the Event Mapping tab of the Manage Related Content Service page (Main Menu > PeopleTools > Portal > Related Content Service > Manage Related Content Service) and select the “Map the event of the Application pages” link.  We are interested in performing mappings to the Navigator CREF and the NavBar CREF.

You are going to need to map the PSM_BREADCRUMB_DISPLAY Service to the post build/post processing of the Navigator CREF.

You will need to map the PSM_BREADCRUMB_STYLE Service to the post build/post processing of the NavBar CREF.

After successfully performing and saving the mappings, you should be all set.  All you need to do is log out and log back in to see the changes.

Here is an example of drilling down into the “Permissions & Roles” folder in the Fluid Navigator with this bolt on configured:

In this example, clicking on the PeoleTools folder will bring up the PeopleTools folder contents in the Fluid Navigator content area like this:

Additional Navigator Styling:

You probably noticed in the picture above that the menu items are smaller than they are as delivered.   This is because a custom style sheet (PSM_SMALL_NAVIGATOR_ITEMS in the project) was applied in the event mapped code to override the size of the menu items.  I find this style particularly helpful on large form factor devices.  The delivered large sizing of the menu items works well for phones and tablets since the user has less clicking precision.  However, for devices with a lot more screen real estate, I find the large menu items counterproductive. If you are not interested in applying this style to all form factors, then you could always evaluate the user’s form factor in the event mapped code to conditionally apply the custom style.

Another subtle difference is the picture above is the absence of the Navigator header that contains the buttons to go to previous directories.  I found the Navigator header to be useless with the breadcrumbs present.  This is because we can now simply click on the breadcrumb (folder name) to go back to previous directories.  The style sheet that makes this occur is included in the project as well and is named PSM_HIDE_NAVIGATOR_HEADER. Similar to the other custom style to adjust the menu item sizing, you have complete control in how you want to apply the style in the event mapped code.

If you decide to not apply the custom styles to alter the Navigator and are only interested in the breadcrumbs, then here is an example of what this would look like:

---

While adding breadcrumbs to the Fluid Navigator will hopefully make using it easier, don’t use this as a reason to not explore other navigation techniques that may allow for an even better navigation experience.  There are many ways to perform navigation in a Fluid environment by implementing and using things like Homepages, Tiles, Navigation Collections, Search, etc.  I believe that the proper implementation of these more modern navigation techniques will provide for the best possible overall user experience.