Documentation

Dialog

The Dialog module provides a mechanism for launching an add-on's modules as modal dialogs from within an add-on's iframe.

A modal dialog displays information without requiring the user to leave the current page.

The dialog is opened over the entire window, rather than within the iframe itself.

Styling your dialog to look like a standard Atlassian dialog

By default the dialog iframe is undecorated. It's up to you to style the dialog.

In order to maintain a consistent look and feel between the host application and the add-on, we encourage you to style your dialogs to match Atlassian's Design Guidelines for modal dialogs.

To do that, you'll need to add the AUI styles to your dialog.

For more information, read about the Atlassian User Interface dialog component.

Members

<static> customData

Returns the custom data Object passed to the dialog at creation.

This module is deprecated and will be removed after August 2017.

Please use the dialog.getCustomData(callback) instead.

Example
var myDataVariable = AP.dialog.customData.myDataVariable;

Methods

close(data)

Closes the currently open dialog. Optionally pass data to listeners of the dialog.close event. This will only close a dialog that has been opened by your add-on. You can register for close events using the dialog.close event and the events module.

Parameters:
Name Type Description
data Object

An object to be emitted on dialog close.

Example
AP.dialog.close({foo: 'bar'});

isCloseOnEscape(callback)

Queries the value of the 'closeOnEscape' property.

If this property is true then the dialog should close if ESC is pressed.

Parameters:
Name Type Description
callback function

function to receive the 'closeOnEscape' value.

Example
AP.dialog.isCloseOnEscape(function(enabled){
  if(enabled){
    // close on escape is true
  }
});

onDialogMessage(buttonName, listener)

Register callbacks responding to messages from the host dialog, such as "submit" or "cancel"

Parameters:
Name Type Description
buttonName String

button either "cancel" or "submit"

listener function

callback function invoked when the requested button is pressed

This method is deprecated and will be removed after August 2017.

Please use AP.events.on("dialog.message", callback) instead.

create(options) → {Dialog~Dialog}

Creates a dialog for a common dialog, page or web-item module key.

Parameters:
Name Type Description
options Dialog~DialogOptions

configuration object of dialog options.

Returns:

Dialog object allowing for callback registrations

Dialog~Dialog
Example
AP.dialog.create({
  key: 'my-module-key',
  width: '500px',
  height: '200px',
  chrome: true,
  buttons: [
    {
      text: 'my button',
      identifier: 'my_unique_identifier'
    }
  ]
}).on("close", callbackFunc);

createButton() → {Dialog~DialogButton}

Creates a dialog button that can be controlled with javascript

Returns:
Dialog~DialogButton
Example
AP.dialog.createButton({
  text: 'button text',
  identifier: 'button.1'
}).bind(function mycallback(){});

getButton() → {Dialog~DialogButton}

Returns the button that was requested (either cancel or submit). If the requested button does not exist, an empty Object will be returned instead.

Returns:
Dialog~DialogButton
Example
AP.dialog.getButton('submit');

getCustomData(callback)

Passes the custom data Object to the specified callback function.

Parameters:
Name Type Description
callback function

Callback method to be executed with the custom data.

Example
AP.dialog.getCustomData(function (customData) {
  console.log(customData);
});