Interface API

Apps have access to a powerful JavaScript API to manipulate their own user interface as well as the Zendesk Support user interface. While the framework provides you with complete control over your app's interface, access to the Zendesk Support UI is provided in a more structured fashion. You don't have direct access to the DOM but you can use API methods to manipulate parts of the interface.

All apps, regardless of their location, have access to some interface APIs. These APIs are listed first.

App interface

The following methods let you manipulate your app's user interface.

this.$([selector])

Returns an element or a set of elements in your app's DOM. Not available in the background location.

Arguments
  • selector a CSS selector targeting an element or a set of elements in your app's DOM.

Example:

var saveButton = this.$("button.save");
var listElements = this.$("li");

You can use this.$() with appropriate CSS selectors to address elements in your app's DOM. See the selector documentation on the jQuery site for an overview of the things you can query for.

Note: This element is the root of your app's content area - there may be additional app decorations outside of this element. If you want to hide your app from view, you should use the app visibility API rather than modifying the visibility of this element directly.

this.currentLocation()

Returns the current location of your app. This can be useful if you have apps in multiple locations. Learn more about locations and how to declare them in your manifest file here.

Example:

var currentLocation = this.currentLocation();
this.renderTemplate(templateName, [data])

Returns a string that is the result of evaluating the Handlebars template named templateName.

Arguments
  • templateName the name of the template to evaluate. Must correspond to one of the Handlebars templates in the app's package.
  • data (optional) a JavaScript object with any data that you want to pass to the Handlebars template. Additional data is always passed to the template. See below for details.

Example:

var html = this.renderTemplate('list', {
             bookmarks:            this.bookmarks,
             ticketIsBookmarkable: this.ticketIsBookmarkable()
           });

The following additional data is always passed to the template:

  • the app's translations in a JavaScript object that maps I18n keys to strings.

    Example:

      {
        "I18n":
          {
            "txt.welcome_message": "Welcome!",
            "txt.error_occured": "There was an error!"
          }
      }
    
      //In your template:
      {{I18n.txt.welcome_message}}
    
  • a JavaScript object containing the app's author.

    Example:

    {
      "author":
         {
            "name": "App Developer",
            "email": "app-developer@example.com"
         }
    }
    
    //In your template:
    {{author.name}}
    
  • a JavaScript object containing all the location-specific data available to your app. See Locations. For example, if your app is in the ticket sidebar, the object includes all the data normally available in your app through the ticket Data API, but in the form of key-value pairs.

    Example:

    {
      "ticket.id": 1234,
      "ticket.status": "pending",
      "ticket.priority": "high"
      ...
    }
    
    //In your template:
    {{ticket.status}}
    

    You can use any of the keys in your Handlebars template.

this.switchTo(templateName, [data])

Evaluates the named template and replaces the data-main element in your app's DOM with the resulting markup.

Arguments

Refer to renderTemplate.

This is a convenience method to switch and render a new template in your app's interface. It lets you structure parts of your app as different screens to switch between in response to user interactions or network events.

this.switchTo('list', {
  bookmarks:            this.bookmarks,
  ticketIsBookmarkable: this.ticketIsBookmarkable()
});
this.assetURL(name)

Returns the path of an asset for your app.

Arguments
  • name the filename of your asset

Example:

var logoUrl = this.assetURL('logo-small.png');
this.routeTo(tabType, id)

Opens a new tab in the agent interface. Returns a promise that resolves once the new tab is opened.

Arguments
  • tabType the type of entity to open in the interface. Can be ticket, user, organization, views, or nav_bar.
  • id the id of the entity to be displayed in the new tab.

Ticket sidebar interface

The following methods let you manipulate the Zendesk Support ticket interface.

this.ticketFields([name])

Returns either the named ticket field as a ticketField object, or all available ticket fields if you don't specify a name.

Arguments
  • name (optional) the name of the field

Example:

  var fields = this.ticketFields();
  var collaborators = this.ticketFields("collaborators");

Here are the names of the built-in ticket fields:

  • assignee
  • collaborator
  • type
  • priority
  • tags
  • ticket_form_id (Enterprise only)
  • custom_field_{id}

For custom fields, replace {id} with the custom field's ID. Example: custom_field_1234.

The ticketField object has the following methods:

ticketField.name()

Returns the name of the ticket field.

  var field = this.ticketFields('requester');
  field.name(); // 'requester'
ticketField.label()

Returns the label of the ticket field.

  var field = this.ticketFields('requester');
  field.label(); // 'Requester'
ticketField.label(newLabel)

Sets the ticket field label to newLabel. The change is cosmetic and reverts if the ticket tab is closed or the page is reloaded. Set it again if necessary.

  var field = this.ticketFields('requester');
  field.label('Foo');
  field.label(); // 'Foo'
ticketField.optionGroups()

If a value is passed in, returns the specified option group object. If no value is passed in, returns all the available option group objects. Only available for dropdown fields.

  var typeField = this.ticketFields('assignee');
  typeField.optionGroups(); // [{ label: 'Support', value: 'support' }, ...]
  var support = typeField.optionGroups(0);
  support.label(); // 'Support'
  support.value(); // '957723'

or

  var myCustomField = this.ticketFields('custom_field_1234');
  myCustomField.optionGroups(); // [{ label: '-', value: '' }, { label: 'A', value: 'a' }, { label: 'A::B', value: 'b' }, ...]
  var a = myCustomField.optionGroups('a');
  a.label(); // 'A'
  a.value(); // 'a'
ticketField.optionValues()

If a value is passed in, returns the specified selectable option object. If no value is passed in, returns all the available selectable option objects. Only available for dropdown fields.

  var typeField = this.ticketFields('type');
  typeField.optionValues(); // [{ label: '-', value: 0 }, { label: 'Question', value: 1 }, { label: 'Incident', value: 2 }, ...]
  var incident = typeField.optionValues(2);
  incident.label(); // 'Incident'
  incident.value(); // 2

or

  var myCustomField = this.ticketFields('custom_field_1234');
  myCustomField.optionValues(); // [{ label: '-', value: '' }, { label: 'A', value: 'a' }, { label: 'B', value: 'b' }, ...]
  var a = myCustomField.optionValues('a');
  a.label(); // 'A'
  a.value(); // 'a'
ticketField.isRequired()

Returns true if the ticket field is required to close the ticket, or false otherwise.

  var field = this.ticketFields('requester');
  field.isRequired(); // true
ticketField.show()

Shows the ticket field in the Zendesk Support interface.

  var field = this.ticketFields('tags')
  field.show();
ticketField.hide()

Hides the ticket field in the Zendesk Support interface.

  var field = this.ticketFields('tags')
  field.hide();
ticketField.toggle()

Toggles the ticket field in the Zendesk Support interface.

  var field = this.ticketFields('tags')
  field.toggle();
ticketField.isVisible()

Returns true if the field is visible in the Zendesk Support interface.

  var field = this.ticketFields('tags')
  field.isVisible(); // true
ticketField.isEnabled()

Returns true if the field is enabled in the Zendesk Support interface.

  var field = this.ticketFields('tags')
  field.isEnabled(); // true
ticketField.disable()

Disables the ticket field in the Zendesk Support interface. The field will be visible but won't allow user interaction.

  var field = this.ticketFields('tags')
  field.disable();
ticketField.enable()

Enables the ticket field for user interaction.

  var field = this.ticketFields('tags')
  field.enable();
ticketField.hasOptions()

Returns true if the field is a dropdown. This convenience method can be used to determine if it is safe to call optionGroups() and optionValues() on the ticket field.

  var field = this.ticketFields('priority')
  field.hasOptions(); // true
ticketField.type()

Returns the type of the ticket field. For custom fields, this is one of "checkbox", "date", "decimal", "integer", "regexp", "tagger", "text", or "textarea". For built-in fields, this is "built-in".

  var field = this.ticketFields('custom_field_1234')
  field.type(); // "text"
this.ticketFields()[0].optionGroups([value]) / this.ticketFields()[0].optionValues([value])

Returns a ticketFieldOption object for the given value.

The ticketFieldOption object has the following methods:

ticketFieldOption.label()

Returns the label of the ticket field option.

  option.label();
ticketFieldOption.label(newLabel)

Sets the ticket field option label to newLabel. The change is cosmetic and reverts if the ticket tab is closed or the page is reloaded. Set it again if necessary.

  option.label('Foo');
  option.label(); // 'Foo'
ticketFieldOption.value()

Returns the value of the ticket field option if one exists, or undefined otherwise.

  option.value();
ticketFieldOption.isEnabled()

Returns true if the ticket field option is enabled, or false otherwise.

  option.isEnabled();
ticketFieldOption.enable()

Enables the ticket field option for user interaction.

  option.enable();
ticketFieldOption.disable()

Disables the option in the ticket field to which the option belongs. The field option will be visible but won't allow user interaction.

  option.disable();
ticketFieldOption.show()

Shows the ticket field option in the Zendesk Support interface.

  option.show();
ticketFieldOption.hide()

Hides the ticket field option in the Zendesk Support interface.

  option.hide();
ticketFieldOption.toggle()

Toggles the ticket field option in the Zendesk Support interface.

  option.toggle();
ticketFieldOption.isVisible()

Returns true if the option is visible in the Zendesk Support interface.

  option.isVisible(); // true
this.disableSave()

Disables the submit button on the ticket page.

  if(!this.validInput()) {
    this.disableSave();
  }
this.enableSave()

Enables the submit button on the ticket page.

  this.enableSave();

User profile sidebar interface

The following methods let you manipulate the interface of the user profile in Zendesk Support.

this.userFields([name])

Returns either the named user field as a profile field object, or all available user fields if you don't specify a name.

Arguments
  • name (optional) the name of the field

Example:

  var fields = this.userFields();
  var role = this.userFields("role");

Here are the names of the built-in user fields:

  • role
  • groups
  • alias
  • signature
  • tags
  • organization
  • locales
  • timezone
  • details
  • notes
  • {user_field_key}

For custom fields, replace {user_field_key} with the custom field's key attribute. See User Fields. Example: my_text_field.

Organization profile sidebar interface

The following methods let you manipulate the interface of the organization profile in Zendesk Support.

this.organizationFields([name])

Returns either the named organization field as a profile field object, or all available organization fields if you don't specify a name.

Arguments
  • name (optional) the name of the field

Example:

  var fields = this.organizationFields();
  var tags = this.organizationFields("tags");

Here are the names of the built-in organization fields:

  • tags
  • domains
  • group
  • shared_tickets
  • shared_comments
  • details
  • notes
  • {organization_field_key}

For custom fields, replace {organization_field_key} with the custom field's key attribute. See Organization Fields. Example: my_text_field.

Profile page fields

Each field in the sidebar of the user or organization profile page in Zendesk Support is represented by a profile field object. See User sidebar interface and Organization sidebar interface above.

The profile field object has the following methods:

userField.name() / organizationField.name()

Returns the name of the field.

  var field = this.userFields('role');
  field.name(); // 'role'
userField.show() / organizationField.show()

Shows the field in the Zendesk Support interface.

  var field = this.userFields('tags')
  field.show();
userField.hide() / organizationField.hide()

Hides the field in the Zendesk Support interface.

  var field = this.userFields('tags')
  field.hide();
userField.toggle() / organizationField.toggle()

Toggles the field in the Zendesk Support interface.

  var field = this.userFields('tags')
  field.toggle();
userField.isVisible() / organizationField.isVisible()

Returns true if the field is visible in the Zendesk Support interface.

  var field = this.userFields('tags')
  field.isVisible(); // true
userField.options() / organizationField.options()

Returns all the option objects available.

  var roleField = this.userFields('role');
  roleField.options(); // { label: 'End-user', value: 'end-user' }, { label: 'Administrator', value: 'admin' }, ...]
  var admin = roleField.options()[1];
  admin.label(); // 'Administrator'
  admin.value(); // 'admin'

The option object has the following methods:

userFieldOption.label() / organizationFieldOption.label()

Returns the label of the field option.

  option.label(); // 'Foo'
userFieldOption.value() / organizationFieldOption.value()

Returns the value of the field option, if one exists, or undefined.

  option.value();

Nav Bar and Top Bar Interface

Icon states

The app icon in a nav bar or a top bar app can have three states: active, inactive and hover.

The easiest way of specifying images for each state is to use the following naming convention for the icon images in your app: icon_<location>_<state>.png. The app automatically uses these files for the app icon.

For example, if you want the app icon for your nav bar app to have both an inactive and a hover state, and the icon for your top bar app to have only an active state, your assets directory would look like this:

  // app/assets/
  - icon_nav_bar_inactive.png
  - icon_nav_bar_hover.png
  - icon_top_bar_active.png

If you don't supply an icon for a state, the default icon is used.

Alternatively, you can manipulate the icon state dynamically using setIconState or iconSymbol as described in the following sections.

this.setIconState(state, assetPath)

This API is deprecated. Please use SVG icons instead of PNG icons.

Sets the path of the PNG icon for a given state.

Arguments
  • state the state you would like to set the icon for. This can be active, inactive or hover.

  • assetPath the path to your icon. You can pass the value returned from the assetURL helper or an absolute URL.

Example:

  this.setIconState('active', this.assetURL('selectedIcon.png'));
  this.setIconState('inactive', this.setting('inactiveIconURL'));
  this.setIconState('hover', 'https://yourdomain.com/path/to/hoverIcon.png');
this.iconSymbol(symbolName)

Changes the SVG icon. See Top bar and nav bar icon for more information.

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

Example:

  this.iconSymbol('default');
  this.iconSymbol('my_other_symbol');
  this.iconSymbol('circles');
this.preloadPane()

By default, the pane view of nav bar and top bar apps 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 will fire the pane.created event.

this.show()

Shows the app in the current location.

  this.show();
this.hide()

Hides the app in the current location.

  this.hide();
this.visible()

Returns true if the app is visible in the location the application is running in.

  this.visible();

Resizing and hiding Top Bar apps

When a user clicks the app icon in the top bar, the app's interface opens in a popover:

popover

You can resize the popover as follows:

this.popover({
  width: 400,
  height: 200
});

The special value auto is also allowed for the height property only.

Calling popover when the app is not open opens and sizes it appropriately. Calling popover when the app is already open resizes it.

You can hide the popover as follows:

this.popover('hide');