Lightning Communities are used to provide apps and services directly to your customers and partners. What makes them so great is that they allow you to take advantage of a lot of the same platform services and features that you have with your internal org. Part of this is the ability to build awesome Lightning Web Components to give those customers and partners an ideal experience. One way you can achieve this is designing and building custom navigation components that an admin can maintain.
Navigation in communities
If you’ve worked with Lightning Communities in the past, you would have modified the navigation menu and items to drive the available options in the theme’s navigation menu. As of Summer ’20, this functionally has expanded even more to support the tile navigation component. If you’re new to communities, a navigation menu is a set of navigation menu items that allows you to specify a label, type, navigation reference, public availability, and an image.
The available navigation types are:
- Community page/internal link – a link to a named community page
- External link – a link directed outside of the community
- Global action – a link to a page generated to host a global action
- Menu label – a parent heading for additional navigation menu items
- Navigational topic – a link to a topic page within the community
- Salesforce object – a link to an object list page with the ability to specify an object and related list
Building a custom navigation component
Navigation menus are great for declaratively managing a set of a list of navigation menu items that you can access programmatically within a custom component. A very common use case for a custom navigation component is the display of social links on a community. It’s a design pattern seen throughout the web and a great way for a company to promote their social presence. There are quite a few ways that we could achieve this with code, but using a navigation menu will give an admin the ability to manage the menu items using a familiar tool.
End result – social navigation component
To get started, all we need to do is go into the Experience Builder and create a new navigation menu; in this case, we’ve created one called Social Links. In this menu, we can specify the details of the navigation menu items and supply an image.
Accessing the navigation items
You can access the navigation menu items as objects grouped by their parent navigation menu. Here we can use SOQL to query for the navigation menu items that are associated with a parent menu.
While this is great for getting the navigation menu items, it doesn’t give us the image references. If your navigation menu doesn’t require images, then this is a great solution for using the items. In this example, we do require the images. Thankfully there’s another option. We can access the navigation items via the Chatter REST API. To access the menu items, we just need to callout to the correct endpoint. This will take the navigation menu items, bring them together with the images, and present us with a unified data structure:
/connect/communities/communityId/navigation-menu/navigation-menu-items
The available paramaters and options associated to the endpoint are:
- communityId – the Id of the community that the navigation menu is associated to
- navigationLinkSetId – the navigation link set we are looking to get back
- addHomeMenuItem – decides if we include the home menu item
- includeImageUrl – decides if we include the image
- menuItemTypesToSkip – allows you to supply a comma separated string of types to be skipped
- publishStatus – filters only the draft or live navigation menu items
If successful, the callout will respond with the following array:
As you can see, it includes an image url, which is exactly what we need to render the icons in the component. To achieve this, we just need the communityId, navigationSetId, includeImageUrl and lastly the addHomeMenuItem paramaters.
We can take the response body from this callout and pass it back to the LWC for rendering.
Bringing the navigation menu to the front end
In order to get the navigation menu items into the LWC, we need to make sure we’re importing all of the modules we need. New in the Summer ’20 release are two community related modules, now available in your components:
To get the Id of the current community:
To get the base path of the current community (for example ‘awesomecommunity.force.com/s/’):
Looking at our current use case, the social navigation component, we can take advantage of these new features!
Once we’ve imported everything we need for the component, we can then use a wire decorator to give the component the ability to get the data from the Apex controller reactively.
Rendering navigation menu items
Here you can see that in the template, we are iterating over the navigation menu items and providing the image url that was returned from the callout. The image reference/file-name.png can be rendered with the provided reference, as it has the same base path as the community.
When a user selects an item, we can handle the click in the JavaScript controller by referencing the data-label attribute that is defined using the dataset property. If you’re new to datasets, they are part of the HTMLOrForeignElement interface that give you the ability to add custom attributes to your html elements. Using data-*=“value” as an attribute will give you access to the string provided as the value when an event is fired.
Navigating to the selected item
The entire purpose of displaying menu items is for a user to click on them and be routed to a new page. Keeping in mind that we have many different page types, references and targets, we’ll need to provide some logic in the controller to point the url in the right direction. Putting the dataset property to good use, when a user clicks one of the menu items, it fires the onclick() event and we can access the data-label=* of the item using event.currentTarget.dataset.label. Once we have access to the menu item, we can determine if the url is internal or external and then broker the action to a separate method.
Navigating to an external url
There are two ways that we can navigate to an external url in communities. We can use the Lightning navigation service to navigate to a standard__webPage page reference that will open in a new tab. The only drawback to this is that we can’t specify a target. This means that in order to open a url in the current window, we are required to use the standard window.open JavaScript method.
Navigating to an internal url
An internal link is compiled down to a url that can be navigated to in the same way as the external link. The format that the url is returned in from the Connect API does not allow us to navigate to a comm__namedPage page reference, therefore we must use the same standard__webPage references that were used for our external links. The difference is that the internal link will always open in the current window, which is the opposite behavior of an external link.
Conclusion
As you can see, navigation menus are a powerful feature within Lightning Communities that allow you to create new navigation experiences that are easily maintainable. We’ve been able to integrate navigation menu items into a LWC and style them in a way that your customers are familiar with. Be sure to check out the github repo and share your ideas for navigation components!
Trailhead
Community Cloud Basics
Project: Building a Custom Theme Layout
Documentation
Community Navigation Menu
Navigation Menu Metadata
Chatter REST API
About the Author
Stephan Chandler-Garcia is a Senior Developer Evangelist at Salesforce. He focuses on Application development, Security and Communities. You can follow him on Twitter @stephanwcg