Interface API

Apps have access to a powerful Javascript API they can use to manipulate their own user interface as well as Zendesk's interface. While there is complete control over the App's own interface, access to the Zendesk UI is provided in a structured fashion - you don't get access to the DOM directly, but use specific API methods to manipulate parts of the interface.

There are some interface APIs that all Apps, regardless of their location, have access to. We will go over those first.

App Interface

These are a set of Javascript methods that allow you to manipulate an App's user interface.

this.$([selector])

Returns a jQuery object scoped to your App's DOM.

Arguments

• selector a CSS selector targetting an element or a set of elements within 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 within your App's DOM. Refer to the jQuery Selectors documentation for an overview of things you can query for.

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. Has to correspond to one of the Handlebars templates in the App's package.
• data (optional) a Javascript object with data that needs to be passed to the template. This is in addition to some default data that is always passed.

Example:

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

When evaluating the template renderTemplate will pass in the data you pass in along with the following defaults:

• the App's translations in a JS object mapping 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 JS Object containing the App's author in the form:

  {
    "author":
       {
         name: "App Developer",
         email: "app-developer@example.com"
       }
  }
  
  //In your template:
  {{author.name}}
  

• a JS Object containing all the App location specific data available to your App. If your App is in the ticket sidebar, for instance, this includes all the data normally available in your App via 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 the above objects within 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 render and switch to a new template in your App's interface. It allows you to structure parts of your App as different screens described in a number of Handlebars templates that you switch between upon user interaction or network events.

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

Zendesk Interface

These are Javascript APIs you can use to manipulate the user interface of Zendesk. At this point, these are limited to a set of APIs available to Apps that are located on the ticket sidebar.

this.ticketFields([name])

Returns either the named ticket field as a ticket field object, or all the ticket fields available if no name is passed in.

Arguments

• name (optional) the name of the field

Example:

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

Here are the names for the built in ticket fields: * assignee * collaborator * type * priority * tag

Custom ticket fields can also be accessed using ticketFields, just use the following naming scheme: custom_field_ID, replacing ID with the custom field's ID. Example: custom_field_1234.

The returned object has some functions available, that are documented below.

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. Please note that the change is cosmetic and will revert if the ticket tab is closed or page reloaded (until you set it again).

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

ticketField.options()

Returns either the option object with the given value, or all the option objects available if no value is passed in.

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

or

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

ticketField.isRequired()

Returns true if the ticket field is required for ticket closure, false otherwise.

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

ticketField.show()

Shows the ticket field in the Zendesk interface.

  var field = this.ticketFields('tag')
  field.show();

ticketField.hide()

Hides the ticket field in the Zendesk interface.

  var field = this.ticketFields('tag')
  field.hide();

ticketField.toggle()

Toggles the ticket field in the Zendesk interface.

  var field = this.ticketFields('tag')
  field.toggle();

ticketField.isVisible()

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

  var field = this.ticketFields('tag')
  field.isVisible(); // true

ticketField.disable()

Disables the ticket field in the Zendesk interface. The field will be visible, but will not allow user interaction.

  var field = this.ticketFields('tag')
  field.disable();

ticketField.enable()

Enables the ticket field, allowing user interaction.

  var field = this.ticketFields('tag')
  field.enable();

this.ticketFields()[0].options([value])

Returns the ticketFieldOption object with the given value. Functions available for ticketFieldOption objects are documented below.

ticketFieldOption.label()

Returns the label of the ticket field option.

  option.label();

ticketFieldOption.label(newLabel)

Sets the ticket field option label to newLabel. Please note that the change is cosmetic and will revert if the ticket tab is closed or page reloaded (until you set it again).

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

ticketFieldOption.value()

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

  option.value();

ticketFieldOption.isEnabled()

Returns 'true' if the ticket field option is enabled, '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 will not allow user interaction.

  option.disable();

ticketFieldOption.show()

Shows the ticket field option in the Zendesk interface.

  option.show();

ticketFieldOption.hide()

Hides the ticket field option in the Zendesk interface.

  option.hide();

ticketFieldOption.toggle()

Toggles the ticket field option in the Zendesk interface.

  option.toggle();

ticketFieldOption.isVisible()

Returns true if the option is visible in the Zendesk 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();