Create Contextual Bar

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.

1. In your app folder, create a file to define the slash command and the context bar. For example, OpenCtxBarCommand.ts.

2. 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";

3. 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;
}

4. 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.

5. 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)
        )
    }
}

6. 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.