Modal

You can create modals using the instances.create action in the Core API and passing modal as the location. See instances.create in the Core API.

Example

var client = ZAFClient.init();

client.invoke('instances.create', {
  location: 'modal',
  url: 'https://en.m.wikipedia.org/wiki/Main_Page',
  size: { // optional
    width: '450px',
    height: '300px'
  }
}).then(function(modalContext) {
  // The modal is on screen now
  var modalClient = client.instance(modalContext['instances.create'][0].instanceGuid);
  modalClient.on('modal.closed', function() {
  // The modal has been closed
  });
});

Note: The maximum recommended width and height are 80vw and 80vh. Scrollbars are displayed if your content is larger than the width or height of the modal.

See Using modal dialogs.

If you want to use a server-side source for your modal, you must use signed urls to authenticate your Zendesk instance. You must also declare the modal location in the app's manifest file rather than in client.invoke(). Example:

"name": "My App",
"signedUrls": true,
"location": {
  "sell": {
    "person_card": "https://myapp.example.org/resources/sidebar",
    "modal": "https://myapp.example.org/resources/modal"
  }
},

The following conditions apply when declaring a server-side modal location:

• All the other locations must be server-side
• All the locations must be name/url pairs under "sell", as in the example above
• signedUrls must be true and declared at the top-level of the manifest JSON

If you declare the modal location in the manifest file, you don't have to declare it in client.invoke(). Example:

function displayModal() {
  return client.invoke('instances.create', {
    location: 'modal'
  }).then(function(data) {
    ...
  });
}

The objects available in all locations are available in this location.

You can also use the resize core action to change the modal's size after it has been created. Example:

client.invoke('resize', { width: '80vw', height: '80vh' });

Events

In addition to the core events, the following event is available to an app in a modal dialog:

• modal.closed

To add event listeners to your app, see Working with framework events.

Users can dismiss modals by clicking on their backdrop or the Cancel button. The modal.closed event is fired at the time the modal is hidden from the user so no further UI update is possible. Your iframe is removed from the DOM after its handler for modal.closed has run. If your event handler returns a promise, removal can be delayed for up to ten seconds.

Actions

• destroy

destroy

Closes the modal.

invoke

client.invoke('destroy')