Edit

Create a removal page

  • Article

You can extend and enhance the user experience by supporting removal and modification options in your app. Teams enables users to rename or remove a channel or group tab and you can permit users to reconfigure your tab after installation. Additionally, the tab removal experience provides the users with post-removal options to delete or archive content.

Note

This topic reflects version 2.0.x of the Microsoft Teams JavaScript client library (TeamsJS). If you are using an earlier version, refer to the TeamsJS library overview for guidance on the differences between the latest TeamsJS and earlier versions.

Enable your tab to be reconfigured after installation

Your manifest.json defines your tab's features and capabilities. The tab instance canUpdateConfiguration property takes a Boolean value that indicates whether a user can modify or reconfigure the tab after it's created. The following table provides the property details:

Name Type Maximum size Required Description
canUpdateConfiguration Boolean A value indicating whether an instance of the tab's configuration can be updated by the user after creation. Default is true.

When your tab is uploaded to a channel or group chat, Teams adds a right-click dropdown menu for your tab. The available options are determined by the canUpdateConfiguration setting. The following table provides the setting details:

canUpdateConfiguration true false description
Settings √ The configurationUrl page is reloaded in an iFrame allowing the user to reconfigure the tab.
Rename √ √ The user can change the tab name as it appears in the tab bar.
Remove √ √ If the removeURL property and value are included in the configuration page, the removal page is loaded into an iFrame and presented to the user. If a removal page isn't included, the user is presented with a confirm dialog box.

Create a tab removal page for your application

The optional removal page is an HTML page that you host and is displayed when the tab is removed. The removal page URL is designated by the setConfig() method (or setSettings() before TeamsJS v.2.0.0) within your configuration page. As with all pages in your app, the removal page must comply with Teams tab prerequisites.

Register a remove handler

Optionally, within your removal page logic, you can invoke the registerOnRemoveHandler((RemoveEvent) => {} event handler when the user removes an existing tab configuration. The method takes in the RemoveEvent interface and executes the code in the handler when a user attempts to remove content. The method is used to perform cleanup operations such as removing the underlying resource powering the tab content. At a time only one, remove handler can be registered.

The RemoveEvent interface describes an object with two methods:

  • The notifySuccess() function is required. It indicates that the removal of the underlying resource succeeded and its content can be removed.

  • The notifyFailure(string) function is optional. It indicates that removal of the underlying resource failed and its content can't be removed. The optional string parameter specifies a reason for the failure. If provided, this string is displayed to the user; else a generic error is displayed.

Use the getConfig() function

You can use getConfig() (formerly getSettings()) to assign the tab content to be removed. The getConfig() function returns a promise that resolves with the Config object and provides the valid settings property values that can be retrieved.

Use the getContext() function

You can use getContext() to get the current context in which the frame is running. The getContext() function returns a promise that resolves with the Context object. The Context object provides valid Context property values that you can use in your removal page logic to determine the content to display in the removal page.

Include authentication

Authentication is required before allowing a user to delete the tab content. Context information can be used to help construct authentication requests and authorization page URLs. See Microsoft Teams authentication flow for tabs. Make sure that all domains used in your tab pages are listed in the validDomains array of your app manifest.

The following sample is an example of tab removal code block:

<body>
  <button onclick="onClick()">Delete this tab and all underlying data?</button>
  <script>
    await microsoftTeams.app.initialize();
    pages.config.registerOnRemoveHandler((removeEvent) => {
      // Here you can designate the tab content to be removed and/or archived.
        const configPromise = pages.getConfig();
        configPromise.
            then((configuration) => {
                configuration.contentUrl = "...";
                removeEvent.notifySuccess()}).
            catch((error) => {removeEvent.notifyFailure("failure message")});
    });

    const onClick() => {
        pages.config.setValidityState(true);
    }
  </script>
</body>

When a user selects Remove from the tab's dropdown menu, Teams loads the optional removeUrl page assigned in your configuration page, into an iFrame. The user is shown a button loaded with the onClick() function that calls pages.config.setValidityState(true) and enables the Remove button shown at the bottom of the removal page iFrame.

After the remove handler is executed, removeEvent.notifySuccess() or removeEvent.notifyFailure() notifies Teams of the content removal outcome.

Note

  • To ensure that an authorized user's control over a tab isn't inhibited, Teams removes the tab in both success and failure cases.
  • After you invoke the registerOnRemoveHandler event handler, respond to the method within 15 seconds. The app must call setValidityState(true) in order to enable the Remove button and for the remove handler to get invoked.
  • When the user selects Remove, Teams removes the tab after 30 seconds regardless of whether the actions have been completed or not.

Next step

Tabs on mobile

See also