# 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.

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

You will also need the styling.

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

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

```html
<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`

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

### With page reloads

```javascript
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](https://redux.js.org/).

```javascript
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
1. `NavigationBarIcon` with `target` for external links
1. `ContextMenu` for a dropdown with links

```javascript
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.

```javascript
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.
