Add-ons can contribute Views in HipChat modal Dialogs. Dialogs should only be used for interrupt flows, e.g. "select and post a meme". If the content of the View is meant to provide more context in the conversation, you should use the Sidebar instead.
When to use
Modals can be used to gather critical input from the user such as integration configuration preferences. Modal dialogs are used to get a response from a user, to reveal critical information that cannot be ignored, or to show data without losing the overall context. Interactions on the main page must wait for the dialog to close.
- Modals act similarly to light boxes in that when they are opened, the HipChat client in the background is whited out.
- Actions are executable within the application via the primary and link buttons.
The main action should be a primary button, other actions should be link buttons. In most cases, there should only be two actions.
The 'x' button in the top right of the modal is used to close the dialog window and is only visible if the dialog does not use a bottom bar and therefore does not have a 'Close' or 'Cancel' link button.
Avoid non-descript primary action labels – instead, use action verbs that by themselves describe what will happen on click (for example 'Save' instead of 'Done').
Declaring a dialog
To use a dialog, your add-on must first declare a dialog in its descriptor:
These are the minimal required properties. You can also specify options to customize the look and feel of your dialog. All of these are purely optional:
Implementing the dialog content
The dialog iframe content is also responsible for handling events that originate from the dialog buttons or filter box:
Handling button clicks
Mostly likely you want to perform an action once the user presses "OK" or "Save" (or selects any of the secondary actions). You can register an event handler for every button by checking for its key (the one that you specified in the descriptor).
If you specify the primary action as:
You can then handle the click by using:
Handling filter box events
This works analogous to the button click handlers:
These events are already debounced by the dialog implementation, so you will only receive an event 250ms after the user stopped typing in the filter box.
Opening a dialog
From a Message Action or an Input Action
Declare the message action in the descriptor:
This will open a dialog that contains an iframe where HipChat will load the page from the URL specified in the dialog
You can also override the dialog options:
From a link in a Message or Card
In the card description or in a notification message, you can link to a dialog by using the
From another View
You can override any options that you declared in the descriptor, by passing an additional
The format of the
options parameter follows the format of the descriptor, but all the localizable elements as they appear in the descriptor are flattened:
Passing data to the dialog
In addition to specifying the look&feel options, you can also pass your own data to the dialog when you open it:
Now the dialog iframe contents can receive your data by registering another event listener:
Updating a dialog
Dialogs can also update themselves. A typical example is changing the primary button enablement state depending on whether a user provided enough data.
Generally, all dialog attributes (besides key and url) can be updated dynamically by using the same format that we used to open a customized dialog above:
For the common case of updating the primary action, we provide a convenience method:
Closing a dialog
A dialog can also close itself by calling: