# navigation (Navigation drawer)

## Overview

The `navigation` drawer is a somewhat omnipresent element that slides in from the left, by means of toggling the hamburger icon located at the top left of the title bar. The hamburger icon is present on any view that is listed in the drawer. These items should reflect the high level views in your app. The hamburger icon will be replaced by either a back or close icon on views that aren’t listed in the drawer - these views are seen as deeper levels within the app’s hierarchy.

The navigation drawer should be reserved for global items. Even though items can be built and displayed dynamically, they should be kept as static as possible per user role. This is analogous to a map not changing while it's in use.

{% hint style="info" %}
See the [reference documentation](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/context-menu) for the `context-menu` component for listing items that are specific to a view.
{% endhint %}

### Purpose of a Navigation System

A successful navigation system serves as a map, in that it:

* provides an overview of the content included in an app
* reinforces the relationship between different sections of content, and
* acts as a “You are here” sign, indicating how the user’s current screen fits into the bigger picture

First time users might feel lost without it, as they won’t know what to expect of an app. It can also save returning users a lot of time by optimizing frequently used flows.

### `navigation` anatomy

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-ac856fd6a2991bb8bb62de0d43e72b0deba7d3f7%2Fnavigation-anatomy.png?alt=media)

1. [Drawer branding](#drawer-branding)
2. Brand [`logo`](#logo)
3. [Section](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/navigation-navigation-drawer/section)
4. [Items](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/navigation-navigation-drawer/section/item)
5. [General Section](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/navigation-navigation-drawer/general-section)
6. [Indicator](#indicator)

### Navigation drawer branding

The top part of the navigation drawer, also referred to as the header, is reserved for customer or app branding. Here you can add a [logo](#logo) and set the [background color](#style-header-background) to give the navigation drawer a customized look.

The header will become collapsable and the logo replaced by the name of the app when either

* the content in the drawer is longer than the height of the drawer,
* the screen height is less than the drawer’s height

## Standard Attributes

### `logo`

**Optional**

**Type**: `string`

**Default:** unset

Specify the brand logo to be displayed in the navigation drawer. String or `$:function()` that returns a string.

```xml
<navigation logo="images/deep_c_corp.png">
    <!-- Navigation sections -->
</navigation>
```

{% hint style="info" %}
**`logo` best practices**

It's recommended to use a crisp PNG or an SVG for the logo. When using a PNG, the image should:

* be at least 224px in width or 136px in height
* not contain any padding
* have a transparent background
  {% endhint %}

## Advanced Attributes

### `from-js`

**Optional**

Construct a navigation component from JavaScript/TypeScript using a [`$:function`](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml) that returns a `component.navigation` object.

```xml
<!-- XML -->
<navigation from-js="$:buildNavFromJS()"/>
```

```javascript
// JS
function buildNavFromJS() {
    return component.navigation({
        sections: buildSectionsFromJS()
    });
}

function buildSectionsFromJS() {
    // Logic to build an array of component.navigationSection objects
}
```

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `indicator`

**Optional**

**Default**: The global indicator will by default only show if there are other indicators in the drawer. The style of the global indicator is derived using the following, for instance if all indicators are of type number the global indicator will be the sum of these.

Indicators can be used to draw the user’s attention to the status of an item or the navigation drawer globally. An example is showing a certain amount of unread messages. Indicators can contain either numbers, text or be empty. The color can also be customized.

An indicator can be placed either of the following elements of the `navigation` component:

1. Globally. The `indicator` will appear with the hamburger menu, overriding an item `indicator` that by default shows here (see next bullet).
2. On an item. When an item `indicator` is present, in addition to displaying with the corresponding item, an additional `indicator` will also display with the hamburger icon (unless a global `indicator` is defined).

![Item indicator example](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-e9139e73b969646e0efcbd42d1a9285efc451b2d%2Fnavigation-indicator-example.png?alt=media)

{% tabs %}
{% tab title="Global indicator" %}

```xml
<navigation indicator="$:buildIndicator()" >
    <!-- Navigation sections -->
</navigation>
```

```javascript
function buildIndicator() {
    // You logic here
    return {value: 1, color:"positive"};
}
```

{% endtab %}

{% tab title="Item indicator" %}

```xml
<navigation >
    <section >
        <item label="Reports" view="reports" indicator="true">
            <item label="Actions" view="action"  indicator="$:getActionsIndictor()"/>
        </item>
    </section>
</navigation>
```

```javascript
function getActionsIndictor() {
    // You logic here
    return {value: 'Pending' , color:"#ffa500"};
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Valid values for `indicator`:

* `"true" | "false"`
* `true | false`
* `number`
* `{ value: true }`,
* `{ value: 4 }`,
* `{ value: true, color: "#c0FFEE" }`,
  {% endhint %}

{% hint style="info" %}
The `color` attribute can be a named color or #HEX value and will be the app's `info` color by default.
{% endhint %}

{% hint style="success" %}
**`indicator` best practices**

* Use an `indicator` if:
  * it is important for the user to be aware of an item's status, even when busy with another task
  * it is beneficial to draw the user's attention away from their current task
* `color` attribute: Stick to predefined app colors, to ensure a coherent palette when displayed together.
* `value` attribute: When displaying text, use short clear words, like "Pending".
  {% endhint %}

### `sections`

**Optional**

Build navigation sections from JavaScript/TypeScript, using a function that returns an array of `component.navigationSection` objects.

{% hint style="info" %}
Sections built using the `sections` attribute will be appended after the sections specified in XML.
{% endhint %}

```xml
<navigation sections="$:buildSectionsFromJS()" >
    <section>
    <!-- Other navigation items -->
    </section>
    <!-- Section build from JS will be appended here -->
</navigation>
```

```javascript
function buildSectionsFromJS() {
    return [
        component.navigationSection({
            label: "General",
            items: [
                component.navigationItem({
                    label: "Sites",
                    view: "sites",
                    collapsable: true
                }
            )]
        })
    ];
}
```

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

### `style-header-background`

**Optional**

**Type**: `string` - can be a named color or #HEX value

**Default**: unset

Specify the background color of the navigation drawer.

```xml
<navigation style-header-background="#C0ffEE">
    <!-- Navigation sections -->
</navigation>
```

{% hint style="info" %}
For named colors the corresponding named font-color will be used for the hamburger menu icon color and app name color. For #HEX values, the icon and font colors are set to white or dark grey, after performing a contrast check.
{% endhint %}

### `style-section-case`

**Optional**

**Type**: `uppercase` | `lowercase` |`sentence-case` | `title-case` | `none`

**Default**: `uppercase`

Configure the letter case of section labels.

### `style-section-color`

**Optional**

**Type**: `string` - can be a named color or #HEX value

**Default**: `primary`

Specify the font color of section labels.

```xml
<navigation style-section-color="#1A1A1A">
    <!-- Navigation sections -->
</navigation>
```

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.getNavigation({id:'my-id'}).xxx` is called from JS/TS:

### `show`

`component.getNavigation().show()`

Programmatically open the navigation drawer, under the following conditions:

* The active view is listed in the navigation drawer.
* The hamburger menu is visible, i.e. the view is the only view on the stack.

### `hide`

`component.getNavigation().hide()`

Hide the navigation drawer programmatically. This operation follows the same conditions as listed above.

### `setActive`

`component.getNavigation().setActive({id:'myId'})`

When using a generic view that displays differently based on the view parameter values. It is a common pattern to have multiple navigation items listed in the drawer that all refer to the same view path.

In this case, the drawer will not distinguish between which of those items corresponds to the active view.

In this case it is required to manually set the active view, using `id="myId"` and `component.getNavigation().setActive({id:'myId'})` in `init()`.

```xml
<!-- XML -->
<item id="$:getItemId()" label="Site" view="site" args="$:getSiteArgs()"/>
```

```javascript
// JS
function getSiteArgs() {
    return [ user, view.currentSite ];
}

function getItemId() {
    return view.currentSite.id + '';
}
```

**Site view code**

```xml
<!-- XML -->
<view title="Site: {currentSite}">
    <!-- Parameters go here: -->
    <param name="currentUser" type="user" />
    <param name="currentSite" type="site" />

    <!-- Variables go here: -->
    <!-- Components go here: -->
</view>
```

```javascript
// JS
function init() {
    component.getNavigation().setActive({id: getItemId()});
}
function resume(from) {}
```

{% hint style="danger" %}
**Breaking change**

In version **4.57.2** of the JourneyApps Runtime, `component.getNavigation().byId('myId').setActive()` was changed to `component.getNavigation().setActive({id:'myId'})`.

Please update all affected view code.
{% endhint %}

### `setOpen`

`component.getNavigation().setOpen({id:'myId'})`

Programmatically toggle a collapsable `<section/>` or `<item/>` to an open state. This will persist across view transitions.

**Use case**: Open a section after a user has performed a particular task or action.

### `setCollapsed`

`component.getNavigation().setCollapsed({id:'myId'})`

Programmatically toggle a collapsable `<section/>` or `<item/>` to a collapsed state. Similar to `setOpen` this will, persist across view transitions.

**Use case**: Collapse all items in the drawer except for a particular set of items, focussing the user attention.