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.

Fluid NavBar

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

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.

Content References

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

Navigator Event

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

NavBar Event

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:

Permissions and Roles

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

PeopleTools

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:

No Custom Nav Styling


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.

10 thoughts on “Adding Breadcrumbs to the Fluid Navigator

  1. Cory says:

    Very helpful! I did find that the breadcrumbs don’t generate if you are going from a fluid homepage, clicking on a tile, then going to a component. It only generates as you navigate from the Root of the menu. Would be cool to have that auto-generate the menu of where the underlying component in the Tile resides. Anyway, thank you for sharing this!

  2. Anonymous says:

    Thank you. Very Helpful!

    After adding the project and implementing the changes, we started seeing RELCONTENT-04 and RELCONTENT-15 exceptions on the SYSAUDIT. Any suggestion on how to make those disappear on the report? Currently, we are just ignoring the exceptions.

  3. Annie says:

    This worked great!

    Any tips on how to get it working for remote content via unified navigation? Currently the breadcrumb functionality stops as soon as a remote folder is clicked.

    I couldn’t see a way to access a remote portal registry via PeopleCode.

    • Colton Fischer says:

      I would like to think that this solution can be coded to allow for breadcrumbs to display for remote content, but I do not have an environment configured with Unified Navigation to actually test this on. After analyzing the delivered code some, I would suggest that you look in the following two classes:

      1. PTNUI:NavBarContentArea:Content:Menu
      2. PTUN_UNINAV:RemoteMenu:RemoteMenu

      The Menu class indicates that there are Unified Navigation-specific Request parameters (“UNINAV” and “UNNODE”) that get passed in on the click of the remote content menu items. These two parameters are what ques the code to generate the RemoteMenu object. The RemoteMenu class is the object representation of a Remote Registry using the Unified Navigation. From there, you might be able to fetch the needed values to properly display the breadcrumb.

      I think if you poke around the delivered code in these classes, then you can get an understanding of how the remote content menu items are generated. This will give you an idea on how to alter the event mapped code in this post so that it can create/display breadcrumbs for the remote content menu items. Feel free to reach out with any other questions and please let me know if you are able to figure this out.

  4. Joanna says:

    Hi
    We have implemented the solution in our organization , it works well however while the menu is initially displayed the main page is looping , the circle keeps on spinning and it does not stop until you click on any option , then the issue is gone .

    I wonder if anybody encountered this issue as well and found a solution .

    • Colton Fischer says:

      Hi Joanna. I have experienced this on a PeopleTools 8.55.12 system. I found that it has to do with the use of the AddStyleSheet function. When I commented out all of the calls to the AddStyleSheet function in the StyleBreadcrumbs class, the spinner does not linger. However, the additional styles injected with the AddStyleSheet function is what really makes this solution usable so not injecting the styles is not really an option.

      I would like to note that this does not occur in PeopleTools 8.56.01. It is possible that this may not occur if you are on PeopleTools 8.55.15+. I was told that there were significant changes with the Event Mapping Framework in 8.55.15 and it is possible that this issue does not occur in that Tools release.

      Can you please let me know which Tools that you are experiencing this issue on?

Leave a Reply

Your email address will not be published.