Comment on page
Build an Extension App with Message Renderers
This guide will provide an overview on how to use the Symphony App Developer Kit (ADK) to build an extension app that handles custom message rendering. This app will look for incoming messages that match a specific type and replace their default rendering with a custom one.
Create a working directory and initialize it using
npm.mkdir adk-example-basic && cd $_
npm init -y
Install the Symphony ADK along with the webpack bundler.
npm install @symphony-ui/adk
npm install --save-dev @symphony-ui/adk-webpack webpack-cli webpack-dev-server
Open the project directory in an editor of your choice
Edit the
package.json file, replacing the scripts section with the following:"scripts": {
"start": "webpack-dev-server --mode=development",
"build": "webpack --mode=production"
},
This adds two commands:
npm startfor starting the development web servernpm run buildto launch the production build process
Create a file named
webpack.config.js that will inject the ADK configuration into the webpack bundler.webpack.config.js
1
const SymADKWebpack = require('@symphony-ui/adk-webpack');
2
const package = require('./package.json');
3
module.exports = SymADKWebpack({}, package.name);
Each extension app requires a manifest (also known as the
bundle.json file) to describe the application. Create a file named bundle.json with the following contents:bundle.json
1
{
2
"applications": [
3
{
4
"type": "sandbox",
5
"id": "adk-example",
6
"name": "ADK Example",
7
"description": "Symphony ADK",
8
"blurb": "Symphony ADK",
9
"publisher": "Symphony",
10
"url": "https://localhost:4000/controller.html",
11
"domain": "localhost"
12
}
13
]
14
}
We are now ready to start building the app. Create a
src directory and a file named index.js within it.src/index.js
1
import * as ADK from '@symphony-ui/adk';
2
3
ADK.start({ id: 'adk-example' }).then(() => {
4
const quoteRenderer = (data) => ({
5
template: `<entity><action class="tk-button tk-button--primary" id="quote" /></entity>`,
6
actions: {
7
quote: {
8
label: 'Show Quote for ' + data.ticker,
9
data: data.ticker
10
},
11
},
12
extraData: '1h'
13
});
14
15
const actionHandler = (action, payload) => {
16
const dialog = ADK.dialogs.show(
17
`<dialog>
18
<div class="container">
19
<h1>Price Quote</h1>
20
<p>You asked for <text id='data' /> with <text id='extraData' /> expiry</p>
21
<p><action id="ok" class="tk-button tk-button--secondary" /></p>
22
</div>
23
</dialog>`,
24
{
25
data: payload,
26
actions: {
27
ok: {
28
label: 'OK ' + action,
29
action: () => dialog.close(),
30
}
31
},
32
size: 'small'
33
}
34
);
35
};
36
37
ADK.messages.registerRenderer('adk.entity.quote', quoteRenderer, actionHandler);
38
});
The code
ADK.start() initializes the ADK with an app id (adk-example) that must correspond with the value provided in the bundle.json manifest from the previous step.
Once the initialization is complete, we use ADK.messages.registerRenderer to register a message renderer on the message type adk.entity.quote.The
quoteRenderer function returns an object defining the template to render as well as any action buttons and extra data. The template field uses ExtensionML, which supports a range of formatting options, action buttons as well as iframes. If action buttons are defined in the template, the id of each action button needs to correspond with a key in the actions field (e.g. quote). This key should reference an object with label and data fields. The extraData field can either be a primitive as in this example or an object.The
actionHandler then defines the callback to execute when the action buttons are clicked on. In this example, we useADK.dialogs.show to launch a dialog, feeding in the previous payload as the dialog's data. Dialog allows the use of <text /> references with id's corresponding to data keys.We can now start the app using:
npm start
This starts a local development server on
https://localhost:4000. Note that this is a TLS-enabled site because all extension apps need to be loaded from TLS-enabled sites. However, because this is a development server, the certificate is self-signed and not trusted by any browser.Visit https://localhost:4000 in your browser to accept the security warning about the untrusted self-signed certificate. Skipping this step will cause the extension app to not load within Symphony in the next step.
There are 2 ways to load an extension app into Symphony. For development purposes, we will be using the bundle injection method to temporarily load the app into the current session.
Beyond local development testing, you should get your pod administrator to create a corresponding app entry in the Admin Portal by uploading the
bundle.json file.We can now load the app by injecting the bundle URL as a parameter named
bundle behind a pod URL. For example, if you are using the developer sandbox located at develop2.symphony.com, visit the following URL in your browser:https://develop2.symphony.com/?bundle=https://localhost:4000/bundle.json
Acknowledge the warning about being in developer mode.
We now need to send a test message that corresponds with the registered message type
adk.entity.quote. You can either do this in Postman or create a simple BDK project. Assuming a Java BDK project was used, this is the sample code required to send a message with the custom message type:1
Map<String, ?> data = Map.of(
2
"quote", Map.of(
3
"type", "adk.entity.quote",
4
"version", "1.0",
5
"ticker", "TSLA"
6
)
7
);
8
String msg = "<div class=\"entity\" data-entity-id=\"quote\">Hello</div>";
9
Message message = Message.builder().content(msg).data(data).build();
10
bdk.messages().send(streamId, message);
Once the message is sent, you should see that it renders as an action button. If the extension app is not installed, users will see the fallback text ("Hello") instead. You should use this text to hint to users that they should install your extension app in order to access further interactivty.
Clicking on the button then lauches a dialog with the defined content.
Last modified 2mo ago