npm package: @nice-digital/global-nav
Description: Global header and footer components for NICE digital services
Author: NICE Digital Services
Latest version: 7.1.1152

# Global navigation

> Global header and footer used across all NICE digital services

[**:rocket: Jump straight to getting started**](#rocket-set-up)

[![GitHub release](https://img.shields.io/github/release/nice-digital/global-nav/all.svg)](https://github.com/nice-digital/global-nav)
[![GitHub license](https://img.shields.io/github/license/nice-digital/global-nav.svg)](https://github.com/nice-digital/global-nav/blob/master/LICENSE)
[![NICE Design System](https://img.shields.io/static/v1.svg?logoWidth=40&label=&message=DESIGN%20SYSTEM&color=004650&labelColor=393939&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNDEwIiBoZWlnaHQ9IjUxMiIgZmlsbD0ibm9uZSI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTQxMi4wOTYgNDU0LjA3YzAgMTYuMTQ2LTYuNzkgMTkuMjQtMTcuOTQgMTkuMjRoLTUyLjYyNGMtMTEuMTQ5IDAtMjAuNDA5LTQuMzUxLTI3LjI1Ny0xMy42NTJMMTI5LjgyMSAyMTMuMzE1aC0xLjI1NHYyNDEuMzc0YzAgMTMuNjUxLTYuMTkyIDE4LjYwMS0xOC41NTcgMTguNjAxSDUyLjQyODRDMzguMTkyMiA0NzMuMjkgMzIgNDcwLjE5NyAzMiA0NTUuMjg4VjYxLjkxMzFjMC0xNi4xMjY0IDcuNDI2OC0xOS4yMzk1IDIwLjQyODQtMTkuMjM5NWg1MS45ODc2YzEyLjM2NSAwIDE4LjU1NyAzLjczMTkgMjUuMzY3IDEzLjAzMjZMMzE0LjIzNyAzMDMuOTA1aDEuMjM0VjYwLjY1NjJjMC0xMy42MzIgNi44MS0xNy45ODI2IDE5LjE5NC0xNy45ODI2aDYwLjA1MWMxNi4wODggMCAxNy4zMjMgOC42ODE5IDE3LjMyMyAxOS4yMzk1VjQ1NC4wNTFoLjAzOGwuMDE5LjAxOXptMTk3LjMwMiAzLjU3N2MwIDcuNDQ1LTQuOTM5IDE0LjI5LTEzLjYgMTQuMjloLTcxLjIwMWMtOS4yNTkgMC0xMy41OTktNi44NDUtMTMuNTk5LTEzLjY1MVY1NS41NTE1YzAtNy40NDQ1IDQuOTU3LTE0LjI1MDggMTMuNTk5LTE0LjI1MDhoNzEuMjAxYzkuMjc5IDAgMTMuNiA2LjgwNjMgMTMuNiAxMy42NTE0VjQ1Ny42NDd6TTEwMjUuNDEgNzcuOTA0MWwtMTcuOTYgNTIuMTI5OWMtMi40NSA2LjIwNy00LjkzIDkuMzAxLTkuMjU2IDkuMzAxLTIuNDY5IDAtNC45MzgtMS4yMzctOC4wNDQtMi40OTQtMzIuODEzLTE1LjQ4OC01OC4xOTktMjEuMDk2LTg3LjI2OS0yMS4wOTYtNjQuMzkxIDAtMTA1Ljg0NiA0OS42MzYtMTA1Ljg0NiAxNDAuMjI2IDAgOTguMDU0IDQ3LjAxIDE0MC4yMDcgMTA3LjcxNyAxNDAuMjA3IDI5LjA5IDAgNTQuNDc2LTUuNTMgODMuNTQ2LTE3LjMyNiAzLjcwNC0xLjI3NiA2LjgyOS0yLjQ5NCA5LjI3OS0yLjQ5NCA1LjU3MyAwIDguNjYzIDIuNDk0IDExLjEzMyA5LjkybDE1LjQ5IDQ1Ljk0MmMxLjIzIDMuNzEzIDEuODUgNi44MDcgMS44NSA5LjkyIDAgNi4yMDctMi40NyAxMC41NTctMTEuMTUgMTMuNjUxQzk3Mi4xOTEgNDcxLjkzNyA5MzYuODg5IDQ4MCA4ODkuMjQyIDQ4MGMtMTMxLjIzMiAwLTE5Ny40NTUtODcuNDk2LTE5Ny40NTUtMjIwLjg5N0M2OTEuNzg3IDEyNS4wNjUgNzcyLjg2NCAzMiA4OTcuMjg2IDMyYzQ0LjU4IDAgODIuMzUxIDguNzAxMyAxMTguMjM0IDI0LjgyNzcgOC42OCAzLjcxMjUgMTEuNzggOC4wNjMyIDExLjc4IDEyLjM5NDUuMDIgMi40OTQzLS42MSA1LjU4ODEtMS44NyA4LjcwMTJsLS4wMi0uMDE5M3ptMzM3LjA2LTM2LjYyMjdjMTIuMzkgMCAxNi4wNyA2LjIwNjkgMTUuNDcgMTQuMjUwN2wtNS41NyA1MC4yNzM5Yy0xLjI0IDEzLjAzMy05LjI4IDE1LjUyNy0yNC4xMyAxNS41MjdoLTE0OS44M3Y5Mi40MjdoMTQwLjUzYzEzLjY0IDAgMTguNTcgNi44MjYgMTguNTcgMTYuNzQ1djQ1LjI4NmMwIDEyLjQzMy02LjE5IDE4LjAwMi0xNy45NCAxOC4wMDJoLTE0MS4xNHY5OC4wNzNIMTM2MGMxMS4xMyAwIDE3Ljk2IDQuOTMgMTcuOTYgMTYuNzI2djQ1Ljk0MmMwIDExLjc3Ni01LjU3IDE3LjM2NC0xNy4zMiAxNy4zNjRoLTI0MC4yMmMtMTQuMjQgMC0yMC40MS0zLjczMi0yMC40MS0xOS4yMzlWNTguNjQ1M2MwLTEwLjU1NzYgNS41Ny0xNy4zNjM5IDE2LjA5LTE3LjM2MzlsMjQ2LjM3LS4wMTk0di4wMTk0eiIvPjwvc3ZnPg==)](https://github.com/nice-digital/nice-design-system)

<details>
<summary><strong>:bookmark_tabs: Table of contents (click to expand)</strong></summary>

<!-- START doctoc -->

- [Global navigation](#global-navigation)
  - [What is it?](#what-is-it)
    - [Functionality](#functionality)
    - [Non-functional](#non-functional)
  - [Stack](#stack)
    - [Principles](#principles)
    - [CSS Modules](#css-modules)
  - [:rocket: Set up](#rocket-set-up)
    - [Other commands](#other-commands)
      - [Tests](#tests)
        - [Run individual files](#run-individual-files)
        - [Run individual tests](#run-individual-tests)
      - [Linting](#linting)
      - [Production build](#production-build)
    - [IDE](#ide)
      - [Extensions](#extensions)
    - [Gotchas](#gotchas)
  - [How to use](#how-to-use)
    - [React](#react)
      - [Installation](#installation)
      - [Usage](#usage)
      - [Props](#props)
        - [Main props](#main-props)
          - [Main.withPadding](#mainwithpadding)
        - [Header props](#header-props)
          - [Header.service](#headerservice)
          - [Header.skipLinkId](#headerskiplinkid)
          - [Header.renderSearchOnly](#headerrendersearchonly)
          - [Header.onNavigating](#headeronnavigating)
          - [Header.onResize](#headeronresize)
          - [Header.onDropdownOpen](#headerondropdownopen)
          - [Header.onDropdownClose](#headerondropdownclose)
          - [Header.additionalSubMenuItems](#headeradditionalsubmenuitems)
          - [Header.search](#headersearch)
          - [Header.search.url](#headersearchurl)
          - [Header.search.autocomplete](#headersearchautocomplete)
          - [Header.search.placeholder](#headersearchplaceholder)
          - [Header.search.query](#headersearchquery)
          - [Header.search.onSearching](#headersearchonsearching)
          - [Header.auth](#headerauth)
          - [Header.auth.environment](#headerauthenvironment)
          - [Header.auth.provider](#headerauthprovider)
          - [Header.auth.links](#headerauthlinks)
          - [Header.auth.displayName](#headerauthdisplayname)
        - [Footer props](#footer-props)
          - [Footer.service](#footerservice)
    - [CDN](#cdn)
      - [Container IDs](#container-ids)
      - [Overrides](#overrides)
      - [Configuration](#configuration)
        - [service](#service)
        - [header](#header)
          - [header.onRendering](#headeronrendering)
          - [header.onRendered](#headeronrendered)
        - [footer](#footer)
  - [Deployments](#deployments)
  - [Upgrading to v2](#upgrading-to-v2)
  - [Upgrading to v3](#upgrading-to-v3)
  - [Upgrading to v4](#upgrading-to-v4)
  - [Upgrading to v5](#upgrading-to-v5)
  - [Upgrading to v6](#upgrading-to-v6)

<!-- END doctoc -->
</details>
  
## What is it?

Global Nav consists common header and footer to be used across all NICE digital services. It is designed to be used across any NICE branded, externally facing web application. This includes all externally facing services that sit under the nice.org.uk domain. It also includes other NICE branded sites like Evidence Search that sit on non-NICE domains. It is a replacement for [NICE.TopHat](https://github.com/nice-digital/NICE.TopHat).

### Functionality

The header covers the following high-level functionality:

- main navigation
- skip links
- search and autocomplete
- COVID-19 message
- TLS warning message for old IE
- sign in and account management via NICE Accounts
  - In the future will support Auth0

### Non-functional

The following non-functional requirements apply:

- _accessible_: to WCAG 2.0 AA
- _touch_: optimized for touch with sufficient touch targets
- _print_: print styles
- _security_: tested against OWASP top 10 and pen tested
- _progressive enhancement_:
  - mobile first
  - non-JS fallback for SSR React apps
- _browser support_: IE11+

## Stack

- [React](https://reactjs.org/)
- [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html) for styles
- [CSS Modules](https://github.com/css-modules/css-modules) for generated class names
- [PostCSS](https://postcss.org/) for transforming CSS with plugins:
  - [autoprefixer](https://autoprefixer.github.io/) for automatically adding vendor prefixes in CSS
  - and [NICE Digital shared browserslist config](https://github.com/nice-digital/browserslist-config#readme)
- [Vite](https://vitejs.dev/) for module bundling
- [Babel 7](https://babeljs.io/) for ES6/JSX → ES5 transpilation
- [accessible-autocomplete](https://github.com/alphagov/accessible-autocomplete)
- [ESLint](https://eslint.org/) for linting our JavaScript
  - with [NICE Digital shared eslint config](https://www.npmjs.com/package/@nice-digital/eslint-config)
- [Stylelint](https://stylelint.io/) for linting our SCSS
- [Prettier](https://prettier.io/) for code formatting
- [Jest](https://jestjs.io/) for JS unit tests and snapshot tests
- [NICE Design System](https://nice-digital.github.io/nice-design-system/) core for SASS mixins, functions and colour/spacing variables
  - [NICE Icons](https://github.com/nice-digital/nice-icons)

### Principles

Consider the following development principles:

- One single header and footer component (and optional main wrapper component with back to top link) across _all_ NICE services
- Progressively enhanced to support maximum number of devices and browsers
- Fast performance
  - single HTTP request for CDN minified bundle
  - as small as possible bundle size
- High unit test coverage
- 'Standard' React wherever possible
  - easy for any React developer to pickup
- Consistent code style and formatting
  - as if a single developer worked across the codebase
- Clear extension points and hooks for integrating into applications
  - To avoid some of the issues from TopHat where there was no consistency

### CSS Modules

We use SCSS modules for a few reasons:

- local scoping of SCSS avoids accidental cascades:
  - within global nav
  - polluting out of global nav into the global scope
- obfuscated class names discourages overriding CSS styles in your app. This is by design to keep the header consistent across all services.

Using SCSS allows us to use mixins, functions and variables from the NICE Design System.

> If you _really_ need to override styles, see the [overrides documentation](#overrides).

## :rocket: Set up

**TL;DR;** to run the project locally, do the following:

- install [Node 14+](https://nodejs.org/en/download/) or latest LTS version. Or even better, use [Volta](https://volta.sh/) to use the Node version pinned in package.json.
- run `npm ci` on the command line to install dependencies
- run `npm run dev` on the command line
- navigate to <http://localhost:3000/> in a browser.

This compiles the application and spins up a development server. It then watches for changes to files and:

- lints changed files
- automatically rebuilds the app.

It then automatically reloads the application in the Browser (so no need for a manual reload) using [Hot Module Replacement (HMR) in webpack](https://webpack.js.org/concepts/hot-module-replacement/).

### Other commands

There are various other commands you can run for further things like tests and linting:

#### Tests

- `npm test` Lints code and runs tests
- `npm test:unit` Runs Jest unit tests
- `npm test:unit:watch` Runs Jest unit tests and watches for changes. Run this in development.
- `npm test:unit:coverage` Runs Jest unit tests and reports coverage

If you've installed the [VSCode npm extension](https://marketplace.visualstudio.com/items?itemName=eg2.vscode-npm-script) then you can easily run scripts by:

- right-clicking the script name in _package.json_
- or _Ctrl+Shift+P_ -> _npm run script_ -> _test:unit:watch_.

##### Run individual files

To run a single test file, use the [jest cli option](https://jestjs.io/docs/en/cli.html#jest-regexfortestfiles) to pass in a regex to match test files. For example, to run just files that match _nav_:

```sh
npm run-script test:unit -- nav
```

##### Run individual tests

To run a single test, or a bunch of tests that match a given name, use the [jest `--testNamePattern` cli flag](https://jestjs.io/docs/en/cli.html#testnamepattern-regex) (or the `-t` alias). For example, to run all tests that check aria attributes:

```sh
npm run-script test:unit -- -t aria
```

#### Linting

- `npm run lint` Lints both JavaScript and SCSS
- `npm run prettier` Checks files for Prettier code style
- `npm run prettier:fix` Fixes Prettier code style issues
- `npm run lint:js` Lints just JavaScript files
- `npm run lint:js:fix` Fixes linting issues automatically in JavaScript files
- `npm run lint:scss` Lints just SCSS files
- `npm run lint:scss:fix` Fixes linting issues automatically in SCSS files

#### Production build

To distinguish between local development builds and builds on TeamCity, a custom npm script has been added, 'build:teamcity.'. The local build step does not work on TeamCity as 'vite build' needs to be passed differently for a build configuration step. For production on TeamCity, npm run build:teamcity is used first, then 'vite build' is passed in:

```bash
run build:teamcity vite build
```

### IDE

We recommend using VS Code as the IDE. It's free, used consistently across NICE Digital Services because of the .NET integration and is extensible with high quality, useful extensions:

#### Extensions

The following VS Code extensions are **strongly** recommended, but not required:

- [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - configures VSCode to use the correct settings (line endings etc) for various files
- [stylelint](https://marketplace.visualstudio.com/items?itemName=shinnn.stylelint) - this will highlight SCSS linting errors directly in the IDE
- [eslint](https://marketplace.visualstudio.com/items?itemName=shinnn.stylelint) - automatically lints your JavaScript as you type and highlights any errors
- [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - highlights code formatting issues in the IDE and formats the file on save
- [npm](https://marketplace.visualstudio.com/items?itemName=eg2.vscode-npm-script) and [npm Intellisense](https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense) for support for using npm
- [Jest](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-jest) for automatically running tests and highlighting errors in the IDE

### Gotchas

- Check you have the right version of Node installed
- Make sure have LF line endings as this is a cross-platform project. This _should_ happen automatically because of settings in _.gitattributes_ and _.editorconfig_.
- Watch out for features of React that Nerv doesn't support, for example refs.

## How to use

We support 2 main methods for using the Global Nav in your projects:

- as a [React component](#react) installed directly into your app
- or externally to your app, loaded via the [CDN](#cdn).

### React

Install and use Global Nav as a dependency in a React application to include it as part of your application bundle.

This is a good option if you're rendering you're app's interface via React, either client side or server side, or both. For example, if you're using [Create React App](https://facebook.github.io/create-react-app/), [Gatsby](https://www.gatsbyjs.org/) or [Next.js](https://nextjs.org/).

> Note if you're using Create React App you'll need to use v2+ because we use CSS modules

Install the package and require the `Header`, `Footer` and `Main` React components into your application, just as you would for any other 3rd party component:

#### Installation for new projects

First, install the _@nice-digital/global-nav_ package [from npm](https://www.npmjs.com/package/@nice-digital/global-nav) into your project:

```sh
npm i @nice-digital/global-nav --save
```

> Note: we used to recommend installing directly from GitHub via `npm i nice-digital/global-nav --save` (notice the missing _@_), which still works but we now recommend using npm.

Then, require the header and/or footer and/or main into your application:

#### Usage

Import the header, footer and main component like this:

```js
import { Header, Footer, Main } from '@nice-digital/global-nav';
```

> Note: we've used ES6 module imports for this examples as we've assumed all React apps will be using ES6.

These header, footer and main components that can be be used like any other React component and configured via [props](#props), for example:

```jsx
const search = {
  autocomplete: '/autocomplete',
};

const page = () => (
  <div>
    <Header service="guidance" search={search} />
  <Main withPadding={true} myOptionalProp={myOptionalProp} className="my-optional-class" >{/* Your page content here */} </Main>
    <Footer />
  </div>
);
```

Wrapping your template with the main component will render a main tag in the html with a back to top link.

For a full list of all the available props, see the [props section](#props) below:

#### Props

##### Main props

###### Main.withPadding

- Type: `Boolean`
- Default: true
  
Optional spacing between page content and footer back-to-top link.

##### Header props

###### Header.service

- Type: `String | null`
- Default: `''`
- Values: `guidance`, `standards`, `evidence`, `bnf`, `bnfc`, `cks`, `journals`

The identifier of the service to highlight in the main menu.
See [services.json](src/services.json) for a list of the available service identifiers.

###### Header.skipLinkId

- Type: `String | null`
- Default: `'content-start'`

The identifier of the skip link target.
An empty div with this id will be created at the end of the header, if it doesn't already exist on the page.

###### Header.renderSearchOnly

- Type: `boolean`
- Default: `false`

Optionally render the header with search box only to aid with debugging by reducing noise in the rendered output.

###### Header.onNavigating

- Type: `String | Function`
- Default: `null`

Function parameters:

- `element` (`HTMLAnchorElement`) the HTML anchor element that was clicked to trigger the navigation
- `href` (`String`) the href of the link that was clicked

Currently `onNavigating` _only_ applies to the sub navigation.

Pass `onNavigating` to prevent default of the default navigation behaviour and
provide your own implementation. Pass either a function, or the name of a
function defined on `window`. E.g.:

```js
window.onNavigatingHandler = function (e) {
  // Define your implementation here e.g.:

  if (e.href === '/#browse') {
    // Trigger some custom behaviour
  } else window.location.assign(e.href); // Fallback to navigation as normal
};

var global_nav_config = {
  header: {
    onNavigating: 'onNavigatingHandler',
  },
};
```

###### Header.onResize

- Type: `String | Function`
- Default: `null`

Pass an `onResize` function to handle when the header is resized. This includes banners being closed/collapsed:

```js
var global_nav_config = {
  header: {
    onResize: function () {
      // Define your resize implementation here
    },
  },
};
```

Or the name of a function defined on `window`. E.g.:

```js
window.onResizeHandler = function () {
  // Define your resize implementation here
};

var global_nav_config = {
  header: {
    onResize: 'onResizeHandler',
  },
};
```

###### Header.onDropdownOpen

- Type: `String`, `Function`
- Default: `null`

Pass an `onDropdownOpen` property to enable callback when dropdown is open.
Pass either a function, or the name of a function defined on `window`. E.g.:

```js
window.onDropdownOpenHandler = function () {
  // Define your implementation here e.g.:
  document.querySelector("body").classList.add("global-nav__dropdown--open");
};

var global_nav_config = {
  header: {
      onDropdownOpen: 'onDropdownOpenHandler',
  },
};
```

###### Header.onDropdownClose

- Type: `String`, `Function`
- Default: `null`

Pass an `onDropdownClose` property to enable callback when dropdown is closed.
Pass either a function, or the name of a function defined on `window`. E.g.:

```js
window.onDropdownCloseHandler = function (e) {
  // Define your implementation here e.g.:
 document.querySelector("body").classList.remove("global-nav__dropdown--open")

};

var global_nav_config = {
  header: {
      onDropdownClose: 'onDropdownCloseHandler',
  },
};
```

###### Header.additionalSubMenuItems

- Type: `null | Array`
- Default: `null`

Pass an `additionalSubMenuItems` array to add extra sub menu items for a given service.

The array should be an array of objects, each containing a `service: string` and another array of `links: Array`.
The links array should contain an array of `text: string` and `url: string`. E.g:

```js
const adminMenus = [{
    service: "indev",
    links: [{text: "Admin", url: "/admin"}]
  },{
    service: "publications",
    links: [{text: "Admin", url: "/admin"}]
  }];

var global_nav_config = {
  header: {
    additionalSubMenuItems: adminMenus,
  },
};
```

###### Header.search

- Type: `Boolean | Object`
- Default: `{}`

Search is enabled by default, pass `false` to disable it e.g. `<Header search={false} />`.
Or pass a set of key/value pairs to configure search and autocomplete:

###### Header.search.url

- Type: `String`
- Default: `/search`

The url of the search results page that the search form submits a GET request to.
For example submitting a search term _paracetamol_ with a url of _/search_ will go to _/search?q=paracetamol_.

###### Header.search.autocomplete

- Type: `Boolean | String | Array<AutoCompleteSuggestion> | AutoCompleteOptions`
- Default: `false`

The source for autocomplete (typeahead) suggestions. Set to `false` to disable autocomplete.

Pass an array of objects to use as the source. The objects in the array should have two keys of `Title: string` and `Link: string`, with an optional `TitleHtml: string` and `TypeAheadType: string`. E.g.:

```jsx
const suggestions = [
  { Title: 'Achilles tendinopathy', Link: '/achilles-tendinopathy' },
  { Title: 'Acne vulgaris', Link: '/acne-vulgaris', TitleHtml: '<mark>Acne</mark> vulgaris', TypeAheadType: 'keyword' },
];
<Header search={{ autocomplete: suggestions }} />;
```

Pass a string, not containing a slash, to use a variable with that name on `window` e.g. `<Header search={{ autocomplete: "topics" }} />`. This is useful for when the suggestions are loaded asynchronously after page load.

Or to make a _remote call_ to a URL on demand, if the source name _does_ contain a slash e.g. `<Header search={{ autocomplete: "/autocomplete?ajax=ajax" }} />`.

The response is expected to be JSON in the format `Array<{ Title: string, TitleHtml?: string, Link: string }>` e.g.:

```json
[
  {
    "Title": "Paracetamol",
    "Link": "/search?q=Paracetamol"
  },
  {
    "Title": "Paracetamol",
    "TitleHtml": "<mark>Para</mark>cetamol",
    "Link": "/search?q=Paracetamol",
  "TypeAheadType": "keyword"
  }
]
```

Or to customise the template for autocomplete suggestions, pass an object with `suggestions` and `suggestionTemplate`, for example:

```jsx
const autocompleteOptions = {
  // Suggestions can be either the name of a variable, a remote url starting with a slash or an array
  suggestions: "/a-remote-url",
  // Return an HTML string, for example:
  suggestionTemplate: (suggestion) => {
   if (!suggestion || !suggestion.Link) return "";
   return `<a href="${suggestion.Link}">${
    suggestion.TitleHtml || suggestion.Title
   }</a>`;
  }
 };

<Header search={{
  autocomplete: autocompleteOptions
 }} />;
```

If you're using TypeScript, then you can import types e.g.:

```tsx
import { AutoCompleteSuggestions, AutoCompleteOptions } from "@nice-digital/global-nav";
```

###### Header.search.placeholder

- Type: `String`
- Default: `Search NICE…`

Override the placeholder (and label) of the search input box, for example change to _Search BNF…_ for the BNF microsite.

###### Header.search.query

- - Type: `String`
- Default: `""`

The search query term, usually taken from the q value of the querstring.

> If you're using .NET, use [HttpUtility.JavaScriptStringEncode](https://docs.microsoft.com/en-us/dotnet/api/system.web.httputility.javascriptstringencode) to avoid XSS attacks and make sure [Request Validation](https://docs.microsoft.com/en-us/aspnet/whitepapers/request-validation) is enabled.

> Note: old TopHat looked for the q querystring value itself, but with Global Nav it's the responsibility of each application to pass in the search term.

###### Header.search.onSearching

- Type: `String`, `Function`
- Default: `null`

Function parameters:

- `query` (`String`) the query term used in the search

The search form by default submits a GET request to `/search?q=XYZ`.
Disable this and provide your own implementation by passing an `onSearching` property.
Pass either a function, or the name of a function defined on `window`. E.g.:

```js
window.onSearchingHandler = function (e) {
  // Define your implementation here e.g.:
  window.location.assign('/search?q=' + encodeURIComponent(e.query));
};

var global_nav_config = {
  header: {
    search: {
      onSearching: 'onSearchingHandler',
    },
  },
};
```

###### Header.auth

- Type: `Boolean | Object`
- Default: `{}`

Authentication is enabled by default. Disable authentication by passing `false`:

```js
// React:
<Header auth={false} />

// Or config:
var global_nav_config = {
  header: {
    auth: false,
  },
};
```

Pass a set of key/value pairs to configure authentication, for example:

```js
// React
<Header auth={{ environment: 'live', provider: 'niceAccounts' }} />

// Or config:
var global_nav_config = {
  header: {
    auth: { environment: 'live', provider: 'niceAccounts' },
  },
};
```

See the `header.auth` properties below for how to configure authentication providers.

###### Header.auth.environment

- Type: `String`
- Default: `live`
- Values: `live`, `test`, `beta`, `local`

This value is the authentication environment eg `beta` would be _beta-accounts.nice.org.uk_.

###### Header.auth.provider

- Type: `String`
- Default: `niceAccounts`
- Values: `niceAccounts`, `idam`

The authentication provider allows the provider to be changed. If the provider is set to niceAccounts then an environment be defined. If the provider is set to idam the links and displayName must be defined.

###### Header.auth.links

- Type: `Array | null`
- Default: `null`
- Values: `[{ key: "Sign in", value: "/Account/Login" }]`, `[{ key: "My profile", value: "/Account/profile" },{ key: "Sign out", value: "/Account/Logout" }]`

If the authentication provider has been set to "idam", then an array of links must be provided. If the user is logged out then a "Sign in" link should be provided with an appropriate url supplied - this should be the first in the list. If the user is logged in, then a number of links are supported, with a "Sign out" link normally last in the list, also a displayName must be supplied.

###### Header.auth.displayName

- Type: `String | null`
- Default: `null`

The displayName is the user's name and must be provided if the "idam" provider is used and the user is logged in.

##### Footer props

###### Footer.service

- Type: `String | null`
- Default: `''`
- Values: `pathways`, `guidance`, `standards`, `evidence`, `bnf`, `bnfc`, `cks`, `journals`

The identifier of the currently active service.
See [services.json](src/services.json) for a list of the available service identifiers.

### CDN

Reference the Global Nav bundle directly from the NICE CDN to render the Global Nav. We recommend including this before the closing `</body>` tag but before your application's scripts:

```html
<script src="//cdn.nice.org.uk/global-nav/global-nav.min.js"></script>
```

This renders with the default configuration. See [the configuration section below](#configuration) for how to pass options into the Global Nav.

> Note: you can reference the non-minified version by removing _.min_ from the filename.

Reference a specific version of the global nav by including the build number as a sub folder. This is useful for testing, in case of a breaking change, or in case of needing to roll back for a hotfix, for example:

```html
<script src="//alpha-cdn.nice.org.uk/global-nav/4.1.806-GN-180-FixInDev/global-nav.min.js"></script>
or
<script src="//cdn.nice.org.uk/global-nav/4.1.805%2Br6D13311/global-nav.min.js"></script>
```

Note the production build needs the `+` character in the build metadata encoding as `%2B` to avoid browsers interpreting it as a space in the URL.

#### Container IDs

The CDN version of Global Nav creates its own containers for the header and footer if they don't already exist on the page. These containers use the ids:

- `global-nav-header` for the header
- `global-nav-footer` for the footer.

Include empty elements with these ids on the page and Global Nav will render into these instead of creating its own:

```html
<body>
  <div id="global-nav-header"></div>
  <main>
    <!-- Your page content here -->
  </main>
  <div id="global-nav-footer"></div>
  <script src="//cdn.nice.org.uk/global-nav/global-nav.min.js"></script>
</body>
```

#### Overrides

Where possible, we recommend using the [provided configuration hooks](#configuration) like [`onSearching`](#headersearchonsearching), [`onNavigating`](#headeronnavigating), [`onRendering`](#headeronrendering), [`onRendered`](#headeronrendered) etc for hooking into or overriding default Global Nav behaviours, rather than using unsupported CSS selectors.

Use the `global-nav-header` and `global-nav-footer` ids to target the Global Nav for more bespoke behaviours - these are the only officially supported selector hooks.

> Please don't rely on inner implementations for hooks or overrides.

For example, if you're targeting the search form via jQuery, use the robust `$("#global-nav-header form[role='search']")` selector rather than `$("#global-nav-search-form")` as this is an inner implementation and might change.

Try not to override Global Nav styles in your app: the Global Nav exists to give consistency across NICE digital services. If you _really_ have to, then same rules as apply as above. For example in CSS:

```css
#global-nav-header {
  position: relative;
}
```

#### Configuration

Global Nav configuration is loaded from a global JavaScript variable on the window object called `global_nav_config`. Include this variable before the [cdn script include](#cdn). Here's a fulle example of all the available config options:

```js
var global_nav_config = {
  service: 'guidance',
  header: {
    skipLinkId: 'content-start',
    cookie: true,
    onNavigating: function (e) {
      // Use e.href
    },
    auth: {
      environment: 'beta',
      provider: 'niceAccounts',
    },
    search: {
      autocomplete: '/autocomplete?ajax=ajax',
      url: '/search',
      placeholder: 'Search NICE…',
      query: '"diabetes in pregnancy"',
      onSearching: function (e) {
        // Use e.query
      },
    },
  },
  footer: false,
};
```

The following config options apply:

##### service

- Type: `String`
- Default: `null`

The key of the service to highlight on the navigation elements. See [_src/Header/Nav/links.json_](src/Header/Nav/links.json) for the available options.

##### header

- Type: `Boolean | Object`
- Default: `null`

The header renders by default, set `header` to `false` to stop it from rendering e.g. `global_nav_config = { header: false }`.
Or, pass an object of key/value pairs of settings specific to the header.
See the [header props](#header-props) section for available options.

In addition to the options from the React props, there are also the following callbacks available when rendering using the CDN embed:

###### header.onRendering

- Type: `Function | String` signature: `function(element)`
- Default: `null`

Function parameters:

- `element` (`HTMLElement`) the HTML element the header will be rendered in to

A callback function, called just before the header is rendered. If it is a string, then a function with that name will be looked for on `window`.

###### header.onRendered

- Type: `Function | String` signature: `function(element)`
- Default: `null`

Function parameters:

- `element` (`HTMLElement`) the HTML the header was rendered in to

A callback function, called just after the header has been rendered. If it is a string, then a function with that name will be looked for on `window`.

##### footer

- Type: `Boolean | Object`
- Default: `null`

The footer renders by default, set `footer` to `false` to stop it from rendering e.g. `global_nav_config = { footer: false }`.
Or, pass an object of key/value pairs of settings specific to the footer.
See the [footer props](#footer-props) section for available options.

## Deployments

We create 2 deployment artifacts: one for deploying to the CDN and one test site for previewing the header and footer.

To test what the deployment packages looks like locally, run the following command:

```sh
dotnet pack NICE.GlobalNav.CDN.csproj -o publish /p:Version=1.2.3-r1a2b3c
# OR dotnet pack NICE.GlobalNav.Preview.csproj -o publish /p:Version=1.2.3-r1a2b3c
```

Where the version number can be any valid [SemVer build number](https://octopus.com/blog/semver2) compatible with Octopus Deploy. Note: this version number will be the build number when TeamCity creates this build artifact.

> Note: you'll need the DotNet Core SDK installed. We don't use NuGet.exe to build so we can run on both Windows and Linux

## Upgrading to v2

Version 2 is a breaking change, because we removed the cookie banner and associated `cookie` option.

If you were already using `cookie: false` in the header config, then the upgrade is easy - the `cookie: false` will no longer do anything so can safely be removed.

If you were using `cookie: true` (or not setting the `cookie` option and leaving the default value of `true`) then you will need to include the [cookie banner](https://github.com/nice-digital/cookie-banner#usage) separately from Global Nav.

## Upgrading to v3

Version 3 removes react hot loader, replacing it with fast refresh. Although this is mostly internal implmenentation, _react-hot-loader_ was a production dependency, and the `Header` and `Footer` components were both exported wrapped in `hot`. So this _could_ affect services using Global Nav as an npm dependency (installed from GitHub).

## Upgrading to v4

V4 involved updating a lot of dependencies. Mostly this was internal implementation details. However, the one external facing change was the build command changing from `npm run build -- --env.version=1.2.3` to `npm run build -- --env version=1.2.3`. Notice the space instead of the dot. This is a result of the `--env` parameter in webpack 4.

## Upgrading to v5

Version 5 includes updates for the summer 2022 brand refresh. It's mostly an internal refactor of typography and colour updates and shouldn't include any breaking API changes.

## Upgrading to v6

Version 6 is mostly updates of dependencies, the biggest of which was React Testing Library (from Enzyme). It also includes support for React 18 and Design System v5.

## Upgrading to v7

Updated autocomplete component.

## Upgrading to v7.1

In Version 7.1, significant changes to improve the development and build processes of the project have been introduced:

### Migrating to Vite

Migration from Webpack to Vite, a faster build tool. Vite provides improved performance and a better development experience with features like Fast Refresh, which replaces React Hot Loader. Terser minification options enable further optimisation of the bundle size, resulting in approximately 10% reduction in bundle size during the build process.

### Easier transition to TypeScript

With the migration to Vite, transitioning to TypeScript in the future will be more straightforward. Vite's TypeScript support will make the process smoother when the time comes for the project to adopt TypeScript.