- Print
- DarkLight
- PDF
Create Contextual Bar
- Print
- DarkLight
- PDF
A contextual bar is a sidebar displayed on the screen after the user triggers it. In this document, we will see how to use the UIKit components to create a contextual bar. To create and update contextual bars, use the following methods respectively:
modify.getUiController().openSurfaceView({type, title, blocks}, triggerId, user)
modify.getUiController().updateSurfaceView({type, title, blocks}, context, user)
For details on these methods, see the IUIController interface TypeScript definition.
Let’s look at a basic app to open a contextual bar that is triggered with a slash command using the openSurfaceView
method.
In your app folder, create a file to define the slash command and the context bar. For example,
OpenCtxBarCommand.ts
.Import the following:
import { IModify, IRead } from "@rocket.chat/apps-engine/definition/accessors";
import { App } from "@rocket.chat/apps-engine/definition/App";
import { ISlashCommand, SlashCommandContext } from "@rocket.chat/apps-engine/definition/slashcommands";
import { UIKitSurfaceType } from "@rocket.chat/apps-engine/definition/uikit";
Now, in the class
OpenCtxBarCommand
, define the slash command as follows:
export class OpenCtxBarCommand implements ISlashCommand {
public command = 'contextualbar'; // this is what we will type when calling the slashcommand: /contextualbar
public i18nParamsExample = 'slashcommand_params';
public i18nDescription = 'slashcommand_description';
public providesPreview = false;
}
Next, in the same class, define the context bar in the
async executor
method as follows:
constructor(private readonly app: App) { }
public async executor(context: SlashCommandContext, _read: IRead, modify: IModify): Promise<void> {
modify.getUiController().openSurfaceView({
type: UIKitSurfaceType.CONTEXTUAL_BAR, // The type of the UI, CONTEXTUAL_BAR or MODAL.
title: { text: 'test', type: 'plain_text' }, // The title of the UI type that is displayed in the workspace.
blocks: [{ // The content of the UI type. It can contain many elements (inputs, actions, etc.)
type: 'section', // The type of the block.
blockId: 'section_1', // The name of the block.
text: { // The object contains the content that will be displayed in the contextual bar.
type: 'plain_text',
text: 'lorem ipsum 🚀',
emoji: true,
} // Additionally, the `accessory` field can contain the block elements.
}]
},
{ triggerId: context.getTriggerId()! }, // The trigger ID is like a security measure - to show users the contextual bar or modal only if users interacted with Rocket.Chat.
context.getSender() // The user that types the slash command.
)
}
}
See Building blocks for details on how to use the blocks.
Update the main app class to call the
OpenCtxBarCommand.ts
file.
import {
IAppAccessors,
IConfigurationExtend,
ILogger,
} from '@rocket.chat/apps-engine/definition/accessors';
import { App } from '@rocket.chat/apps-engine/definition/App';
import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata';
import { OpenCtxBarCommand } from './contextbar'; // import the `OpenCtxBarCommand` class
export class HelloWorldApp extends App {
protected async extendConfiguration(configuration: IConfigurationExtend): Promise<void> {
await configuration.slashCommands.provideSlashCommand(
new OpenCtxBarCommand(this)
)
}
}
Deploy and test the app. In any channel, send the slash command
/contextualbar
.
The following screenshot shows the contextual bar called test
with the content that we defined in the blocks.