@episerver/platform-navigation

Platform Navigation

This repository contains a react implementation of the Episerver platform navigation component.

Getting Started

Add @episerver/platform-navigation as a dependency

yarn add @episerver/platform-navigation

Import the Navigation component. If you are using TypeScript there are type definitions that will help you use it. You can look at the Storybook to see usage examples.

import { Navigation } from "@episerver/platform-navigation";

You will also need the styling.

import "@episerver/platform-navigation/dist/main.css";

In your HTML file, include the Barlow font in the head.

<link href="https://fonts.googleapis.com/css?family=Barlow:400,500,700" rel="stylesheet" />

Basic usage

User interaction for menuItems is handled by PlatformNavigation and will notify your application what item was selected with the callback onItemSelect. Your application is responsible for setting the selected items in the menu on both startup and after callbacks. If no selection is given the component will select the appropriate menu items for you according to the Design System guidelines.

User interaction for actionItems differ depending on the component used. Use NavigationBarIcon for direct links such as help documentation on another domain, and use ContextMenu for a menu of options such as user "settings" and "log out".

Note: A current limitation is that action items do not have an active state. So if a user navigates to an action sub-link such as My Settings / Language the navigation will highlight the first menu item and not My Settings.

With react-router-dom

export const Navigation = withRouter(({ history }) => {
    return (
        <PlatformNavigation
            menuItems={menuItems}
            onItemSelect={(levelOne, levelTwo) => {
                history.push((levelTwo || levelOne).url);
            }}
            product={{ name: "CMS", url: "/" }}
        />
    );
});

With page reloads

export const Navigation = ({ history }) => {
    return (
        <PlatformNavigation
            menuItems={menuItems}
            onItemSelect={(levelOne, levelTwo) => {
                window.location.href = (levelTwo || levelOne).url;
            }}
            product={{ name: "CMS", url: "/" }}
        />
    );
};

With internal state

You should keep the state on an application level instead. For example using redux.

export const Navigation = ({ history, location }) => {
    const [levelOne, setLevelOne] = useState();
    const [levelTwo, setLevelTwo] = useState();

    return (
        <PlatformNavigation
            levelOne={levelOne}
            levelTwo={levelTwo}
            menuItems={menuItems}
            onItemSelect={(levelOne, levelTwo) => {
                setLevelOne(levelOne);
                setLevelTwo(levelTwo);
                // Change location or history here
            }}
            product={{ name: "CMS", url: "/" }}
        />
    );
};

With action links

Action links can be:

1. NavigationBarIcon for internal navigation
2. NavigationBarIcon with target for external links
3. ContextMenu for a dropdown with links

export const Navigation = withRouter(({ history }) => {
    return (
        <PlatformNavigation
            menuItems={menuItems}
            onItemSelect={(levelOne, levelTwo) => { /* ... */ }}

            // actionItems takes an array of any React element, but there are two helper components included: NavigationBarIcon and ContextMenu.
            // Note: Items need to handle their own onClick event.
            actionItems={[
                <NavigationBarIcon key={1} onClick={ /* ... */ }>
                    <SearchIcon />
                </NavigationBarIcon>,
                <NavigationBarIcon key={2} onClick={ /* ... */ } href="http://www.episerver.com" target="_blank">
                    <HelpIcon />
                </NavigationBarIcon>,
                <ContextMenu key={3} icon={<AccountIcon />} menuItems={[
                    { name: "My Settings", url: "", onSelected:  /* ... */ },
                    { name: "External link", url: "https://episerver.com", target: "_blank", onSelected:  /* ... */ },
                    { name: "Logout", url: "", onSelected: /* ... */ }
                ]} />
            ]}
        />
    );
});

With Telemetry

The platform navigation has built-in telemetry that can be enabled by passing in the telemetry prop. The information passed into the telemetry prop is included on each track event the navigation logs. It is not possible to add additional track events through the navigation.

export const Navigation = () => {
    return (
        <PlatformNavigation
            menuItems={menuItems}
            onItemSelect={(levelOne, levelTwo) => { /* ... */ }}

            // The product name is sent with the tracker data, so data can be grouped under the appropriate product
            product={{ name: "CMS", url: "/" }}

            telemetry={
                // Hashed (SHA512) derived from the user email without salt. If the user email is not available, the username can be used instead.
                authenticatedUserId: anonymizedUserId,
                // Hashed (SHA512) derived from a unique customer account identifier without salt. The license key should be used if it's available.
                accountId: anonymizedClientId,
                // Specify whether the application has SPA-like navigation, so telemetry knows when to send track events.
                isSPA: false,
                // Additional data that should be sent on each event.
                customProperties: {
                    myProperty: myValue
                }
            }

        />
    );
};

Releases

Releases will be created at the team's discretion. This should be done regularly when there are bug fixes or feature changes available. Releases follow semantic versioning. This means that, until there is a major version, minor versions may contain breaking changes.

See the CHANGELOG.md document for information about what is included in each release.

Internal

See the GUIDELINES.md document for more information about contributing and the release process.