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

openIMbyStreamID()

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.

openIMbyUserIDs()

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.

registerExtension()

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: icon: the url of an image that will be displayed on the action button. Recommended format is a square SVG. label: a label associated with the action button. data: an opaque block of data that will be passed along with the trigger event

trigger()

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 + '.');
    }

unregisterExtension()

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	single-user-im multi-user-im room hashtag cashtag settings	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');

themeChangeV2 event

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;
});