UI Service
Use the
ui service to extend various parts of the Symphony client user interface. For example, add buttons on IM, MIM, and chatroom modules or add links to the #hashtag and $cashtag hovercards:// To use the ui service, you must subscribe to it from your application
var uiService = SYMPHONY.services.subscribe("ui");
Extension apps can receive stream participant information when an end user clicks on a button added by the app. For more information, refer to Receiving Conversation and User Data.
The following methods are available on the
ui service:- openIMbyStreamID
- openIMbyUserIDs
- registerExtension
- unregisterExtension
The following events are fired by the
ui service:- themeChangeV2
Open an existing conversation in a new module.
Released in version 20.10.
function openIMbyStreamID(streamID, messageId)
Parameter | Type | Possible Values | Description |
streamID | String | | The stream ID or conversation ID to be opened. |
messageID | String | Either a messageID, or the null value | The messageId can be used in addition to the streamId to focus on a specific message of the conversation.
Use "null" as parameter value to jump to the latest message of the conversation. |
Open a conversation with one or more users in a new module.
Released in version 20.10.
function openIMbyUserIDs(userIds)
Parameter | Type | Possible Values | Description |
userIds | String[] | | Array of userIds. |
Add an action button to the Symphony user interface.
Action buttons are added to various places in the UI, such as in the header of chat modules, in #hashtag or $cashtag hovercards, on the profile of users and more.
function registerExtension(uiClass, id, serviceName, options)
Parameter | Type | Description |
uiClass | String | The location within the Symphony application where the action button should be placed. Possible values:
- single-user-im : Button added to the header of 1-1 chats
- multi-user-im : Button added to the header of group chats
- room : Button added to the header of chatrooms
- hashtag : Link added to the hovercard that appears when hovering over a hashtag (e.g. #symphony)
- cashtag : Link added to the hovercard that appears when hovering over a cashtag (e.g. $GOOG)
- settings : Link added to detail card of the application in the Marketplace
- profile : Link added to the user profile page and profile hovercard |
id | String | A unique identifier for this extension (can be used to unregister). |
serviceName | String | The name of a local service implemented by your application that will be invoked when a user clicks on your action button. |
options | Object | An object, containing:
|
You must implement the
trigger method on your application service in order to handle clicks on the registered action buttons:// The application service that will be used to handle clicks on UI extensions
var helloControllerService = SYMPHONY.services.register("hello:controller");
// The application service that will handle the filter on UI extensions
var helloFilterService = SYMPHONY.services.register("hello:filter");
// Displays a button in the header of 1-1 chats
uiService.registerExtension(
"single-user-im",
"hello-im",
"hello:controller",
{
label: "IM Button",
data: {"datetime": Date()}
}
);
// Implement the trigger method on your application service
helloControllerService.implement({
trigger: function(uiClass, id, payload, data) {
if (uiClass == "single-user-im") {
console.log('IM button was clicked on ' + data.datetime + '.');
}
Remove a previously registered action button.
This will remove all instances of a particular extension - for example, from all single chat modules or all #hashtag and $cashtag hovercards.
function unregisterExtension(uiClass, id)
Parameter | Type | Possible Values | Description |
uiClass | String |
| The location within the Symphony application where the action button was registered. |
id | String | | The id of the UI extension that should be removed. |
uiService.unregisterExtension('single-user-im', 'hello-im');
This event is fired when the user's font size or theme is changed.
Use the listen method on this service to subscribe to this event and specify a callback that will be executed when the event is fired. The callback should change the styling of your application to match the user's new theme.
var uiService = SYMPHONY.services.subscribe("ui");
uiService.listen("themeChangeV2", function() {
themeColor = data.themeV2.name;
themeSize = data.themeV2.size;
// Styling is achieved by specifying the appropriate classes on the app module's body element.
document.body.className = "symphony-external-app " + themeColor + " " + themeSize;
});
Last modified 9mo ago