Public
cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

How we built Atlas's custom header

Khoros Staff

With the latest Atlas redesign, we reimagined our Community header to build a more intuitive navigation and search experience. 

Learn more about our redesign in Atlas Redesign Project Story.

Our custom header experience differs depending on:

  • whether the user is anonymous or registered
  • whether the user is on a desktop or a mobile device
  • whether the user is on the Community Page or any other page in Atlas
  • the user's role(s) in the community

This article includes a zip file with our commented source code for the components, functions, macros, and CSS we used to build our customization.

Let's look at the different ways the header renders depending on user, device, and page.

Anonymous view (Desktop)

Anonymous users have limited access to Atlas. You'll notice that some areas, such as the Dev Network, are not accessible to anonymous users at all.

commPageAnonymousHeader.gif

Registered user view (Desktop)

Registered users see all menu items that they have permission to view based on their role(s) in Atlas. Notice that the registered user in the gif below has many more options than our anonymous friend above.
comPageMemberHeader.gif

Mobile/Tablet view

Roles determine what menu items appear in mobile or tablet navigation, just as they do in a desktop viewport. The mobile/Tablet header uses the out-of-the-box Community Navigation (Slide-out) component, which uses a hamburger menu control.

customNavAtlasMobile.jpg

Community Page view (Desktop)

The Atlas landing page (the Community Page quilt) includes a hero component with a search box. When the search box in the hero is in view, we don't include a search bar in the header. Once the user scrolls past the hero component, the search icon appears. This behavior uses JavaScript injected to our custom header component via the liaAddScript FreeMarker directive. Learn more about liaAddScript.

scrollPastHero.gif

Non-Community Page view (Desktop)

On all other pages, the header includes the search icon and expanding/collapsing search box.

searchExpandCollapse.gif

Customization source files

Our source code is in a zip file attached to this article.

To keep our component code easier to understand, we separate the business logic code for creating the different sections of the navigation menu into separate functions and macros outside of our custom header component (custom-new-header.ftl). This makes it easier to read and understand the display that builds the header within the component code.

You'll find these files in the attachment:

  • custom-new-header.ftl - the component that renders the Atlas header
  • theme-lib-common-functions.ftl - a macro that includes common functions used throughout Atlas customizations
    • function executeLiQLQuery - logic to run LiQL queries and define the response format
  • new-header-util-macro.ftl - a set of macros specific to the Atlas header customization
    • function getUserInfo - gets a user's role(s) in the Atlas community and sets the role data in the user cache
    • macro renderMainMenu - contains the logic to retrieve and render the main menu items
    • macro dropdownButton - renders the dropdown that contains the submenu items for each main menu item
    • macro renderSubMenu - contains the logic to retrieve and list the submenu items for each main menu item
    • macro renderCasePortalMenu - contains the logic to render the Support menu item in the main menu
  • _new-header.scss - The SASS used for the custom header styling

customNavIncludes.pngCustom header configuration

We placed our custom header component within the Page Header section of the Community Wrapper in Studio. We call the component with the following HTML. The cacheTimeMs parameter is used to set the component cache time-to-live (TTL).

 

<div class="custom-header"><@component id="custom.new-header" cacheTimeMs="60000" /></div>

 

Caching considerations

Component-level caching

We use component caching to cache our custom header component. This caches the entire menu for each user. Because the content of the menu can vary based on the user's roles and permissions, we set the variation parameter to current_user and set the anonymousOnly parameter to false. The cache TTL is 5 minutes. You'll find our component caching code near the top of custom-new-header.ftl in the source file attachment. Learn about component caching in Component caching with liaMarkupCache.

User-level caching

The menu items displayed in the header's main navigation menu depends on the current user's roles. We store role data in the user cache so that we can check the cache rather than running a series of if/else statements each time we need to decide whether or not to display a menu item. The user cache logic is contained in a function called getUserInfo. You'll find the code for getUserInfo in the new-header-util-macro.ftl file in the source file attachment. Learn more about the user cache in User and application caching and usercache.

Tags (1)
6 Comments
Trusted Contributor

This post is awesome!  Thanks @SuzieH! I'd love to see a bunch more posts like this because it was super informative!

Edit:  And thank you for providing the source code!

Khoros Staff

I'm so glad you liked it! It takes a little while to pull them together, but they are fun to do. We ran the source code past some of our senior Community engineers as well to ensure that the customizations were coded in as efficient and performant ways possible.

We're hoping to get a couple of more articles out about the "Author" label we use in Atlas next to user avatar in posts, as well as the hover profile card. 

@RyanPi are the lone dev doc writers at this time, so we still have to balance these articles out against all the rest of the API docs for Community, Care, and Marketing.

Khoros Staff

I love this! So much great info here for Community Managers who like to challenge themselves or for those who just want to see what the Khoros platform and team is capable of!! 

Honored Contributor

👏 Awesome stuff, thanks so much for sharing.

Khoros Staff

Great article @SuzieH One question I have heard a few times is how do we integrate the status page notifications at the top banner of Atlas.  It's a great feature! Maybe it is posted elsewhere in docs.

Esteemed Contributor

Thanks @SuzieH and Khoros for sharing these, "behind the scenes" stories. Keep up the good work!