Nav bar

The app appears as an icon in the navigation bar on the left side of the agent interface. Clicking the icon opens the app.

Example manifest

"location": {
  "support": {
    "nav_bar": "assets/iframe.html"
  }
},

See Setting the app location.

In addition to the objects available in all locations, the following additional actions are available in this location:

• preloadPane
• iconSymbol
• iconChars

Events

In addition to the core events, the following events are available to an app in the nav bar:

• pane.activated
• pane.deactivated
• app.route.changed

For details on the pane events, see Events in the top bar documentation.

app.route.changed

Nav bar apps differ from other locations in that it's possible to browse directly to the content pane of a specific app using a direct link. Example:

https://z3n.zendesk.com/agent/apps/app-name

The last part of the link, app-name, corresponds to the unique name given to the app at installation. If the app name is camel case or contains spaces or underscores, the name is converted into a string delimited by dashes to make it URL-friendly and to format it consistently.

To see a nav bar app route in action, install a nav bar app in Zendesk Support and click the app's icon in the nav bar. The browser's URL should include agent/apps plus the sanitized version of your app installation name.

In addition to browsing directly to a nav bar app, you can include additional segments in the app URL. Example: https://z3n.zendesk.com/agent/apps/app-name/foo/bar/baz.

When including additional segments, the parts after the sanitized app title are passed to the app being routed to by way of the app.route.changed event.

Example:

zafClient.on('app.route.changed', function(data) {
  console.log(data.appRoute); // "foo/bar/baz"
  console.log(data.appTitle); // "my-app"
});

URL parameters

When the app.route.changed event fires in a nav bar app, the event data object passed to a handler includes a key for appParams. The appParams key contains a JSON object representation of any URL parameters that exist at the time the route is processed.

Note: URL parameters other than the zat parameter are stripped from the URL after processing but are available in the app.

Example:

Given the Nav bar app route https://z3n.zendesk.com/agent/apps/app-name/foo/bar/baz?quux=true&boz=2.

zafClient.on('app.route.changed', function(data) {
  console.log(data.appRoute); // "foo/bar/baz"
  console.log(data.appTitle); // "my-app"
  console.log(data.appParams); // { quux: 'true', boz: 2 }
});

Actions

The following additional actions are available in this location:

• preloadPane
• iconSymbol
• iconChars

preloadPane

By default, the pane view of a nav bar or top bar app is only inserted into the DOM the first time the app is opened. Calling preloadPane causes the pane view to be inserted into the DOM in advance, but it won't be visible until the app is opened. This is useful in cases where you need to manipulate the DOM before the app is made visible or if you have an iframe that needs to be preloaded. When the app pane is created, the framework fires the pane.created event.

Note: You can only call preloadPane with the instances API from a location loaded earlier. In most cases however, performing background tasks directly from the background location is preferred to preloading the pane.

invoke

instanceClient.invoke('preloadPane') // called from another location using the instances API.

iconSymbol

Changes the SVG icon. See iconSymbol API.

set

client.set('iconSymbol', symbolName)

arguments

• symbolName the value of a id attribute in a <symbol id="mySymbol"> tag in your SVG file.

Note: You can't use the iconSymbol property to change an app icon in the overflow menu.

iconChars

Changes the SVG icon to the two characters provided. Supports UTF8.

invoke

client.invoke('iconChars', twoChars)
client.invoke('iconChars', 'Wi')
client.invoke('iconChars', '∑✈')

arguments

• twoChars is a string of two characters that will be put into the nav_bar icon.

Note: You can't use the iconChars property to change an app icon in the overflow menu.