Extension Applications + UI Buttons
Symphony extension apps have the ability to extend various parts of the Symphony client user interface or UI. One common implementation is to add buttons to IMs, MIMs, and chatroom modules.
Note this guide is an overview of how to leverage the Extension API to build UI Extensions as buttons. For an in depth reference of the UI Service and its methods refer to the UI Service guide.

1. Subscribe and Register your Extension

In order extend the Symphony client's UI, extension apps must subscribe to the UI service provided by the Extension API:
1
var uiService = SYMPHONY.services.subscribe("ui");
Copied!
After subscribing to this service you must register your extension in order to add elements to a particular class of the UI:
1
function registerExtension(uiClass, id, serviceName, options)
Copied!
The uiClass registered is the location within the Symphony application where the UI extension (button) will appear. The following are the possible values for the uiClass parameter:
uiClass
Description
single-user-im
Button added to 1-1 instant message module header
multi-user-im
Button added to multi-party instant message module header
room
Button added to chatroom module header
To customize the look and feel of your button, you can pass in an object containing an icon, label, and data to the options parameter:
1
{
2
label: 'Example In Chat button',
3
icon: "link/to/your/icon.png",
4
data: {"datetime" : Date()}
5
}
Copied!

2. Listen for Events

Once you have registered your UI extension on the appropriate UI class, you can listen for and handle user clicks by implementing the trigger method on your application service. This trigger() function will be called each time your extended uiClass button is pushed inside the Symphony client:
1
// The application service that will be used to handle clicks on UI extensions
2
var helloControllerService = SYMPHONY.services.register("hello:controller");
3
// The application service that will handle the filter on UI extensions
4
var helloFilterService = SYMPHONY.services.register("hello:filter");
5
// subscribe to ui service
6
var uiService = SYMPHONY.services.subscribe("ui");
7
8
// Displays a button on 1-1 instant messages
9
uiService.registerExtension(
10
"single-user-im",
11
"hello-im",
12
"hello:controller",
13
{
14
label: "IM Button",
15
icon: "link/to/your/icon.png",
16
data: {"datetime": Date()}
17
}
18
);
19
20
// Implement the trigger method on your application service
21
helloControllerService.implement({
22
trigger: function(uiClass, id, payload, data) {
23
if (uiClass == "single-user-im") {
24
console.log('IM button was clicked on ' + data.datetime + '.');
25
}
26
}
27
})
Copied!

Receiving Conversation and User Data

If your app is authenticated, you can also receive conversation and user data. Each time your extended uiClass button is pushed inside the Symphony client, the trigger() method will receive the following user object for a button registered inside of an IM or user profile:
1
//the following object is recieved if a button is pressed inside an IM or user profile
2
{
3
threadId, //id of the conversation. Also known as streamId or conversationId
4
userCount, //number of users returned
5
isCrossPod, //if cross pod, returns true
6
user : { //user information
7
id, //user identifier
8
emailAddress, //user email
9
username, //user name
10
displayName, //user display name
11
firstName, //user first name
12
lastName, //user last name
13
phone, //user phone number
14
mobile, //user mobile phone number
15
}
16
}
Copied!
If the button is registered in a chatroom or MIM, the trigger() method will receive the following object:
1
{
2
isCrossPod, //if it is a cross pod room, returns true
3
roomName, //room name
4
threadId, //id of the conversation. Also known as streamId or conversationId
5
userCount, //number of users returned
6
users : [ { //users information
7
id, //user id
8
isCrossPodUser, //if this is a cross pod user, returns true
9
emailAddress, //user email
10
username, //user name
11
displayName, //user display name
12
firstName, //user first name
13
lastName, //user last name
14
phone, //user phone number
15
mobile, //user mobile phone number
16
}]
17
}
Copied!
Note: If the chatroom or MIM exceeds 20 users, then the users list will be returned empty.

3. Filter Events

Additionally, the UI Service provides a filter() function that allows you to control if and when your UI Extension / button is displayed. This filter() function is called before your button is shown receiving the uiClass, data, and payload passed to.the trigger() function. Based on the information passed to the filter() function, you can choose to selectively display the button. For example, you can display the button only if a user's phone is present and if a user is not a cross-pod user:
1
// Implement the filter function on your application service
2
helloFilterService.implement({
3
filter: function (type, id, data) {
4
return !!(data.user && data.user.phone);
5
}
6
});
Copied!

4. Add Custom Business Logic

Now that you've registered your UI extension, the next step is to add custom business logic. The bulk of your business logic will exist in your trigger() method as it gets called each time the button is clicked.
Continue here to go through a step by step tutorial of how to add custom business logic to your UI Extension using the BDK 1.0 (Bot Developer Kit):
Last modified 9mo ago