Mattermost Logo
Edit on GitHub

Web App Reference

PluginClass 

The PluginClass interface defines two methods used by the Mattermost web app to initialize and uninitialize your plugin:

class PluginClass {
    /**
    * initialize is called by the webapp when the plugin is first loaded.
    * Receives the following:
    * - registry - an instance of the registry tied to your plugin id
    * - store - the Redux store of the web app.
    */
    initialize(registry, store)

    /**
    * uninitialize is called by the webapp if your plugin is uninstalled
    */
    uninitialize()
}

Your plugin should implement this class and register it using the global registerPlugin method defined on the window by the webapp:

window.registerPlugin('myplugin', new PluginClass());

Use the provided registry to register components, post type overrides and callbacks. Use the store to access the global state of the web app, but note that you should use the registry to register any custom reducers your plugin might require.

Example 

The entry point index.js of your application might contain:

import UserPopularity from './components/profile_popover/user_popularity';
import SomePost from './components/some_post';
import MenuIcon from './components/menu_icon';
import {openExampleModal} from './actions';

class PluginClass {
    initialize(registry, store) {
        registry.registerPopoverUserAttributesComponent(
            UserPopularity,
        );
        registry.registerPostTypeComponent(
            'custom_somepost',
            SomePost,
        );
        registry.registerMainMenuAction(
            'Plugin Menu Item',
            () => store.dispatch(openExampleModal()),
            mobile_icon: MenuIcon,
        );
    }

    uninitialize() {
        // No clean up required.
    }
}

window.registerPlugin('myplugin', new PluginClass());

This will add a custom UserPopularity component to the profile popover, render a custom SomePost component for any post with the type custom_somepost, and insert a custom main menu item.

Registry 

An instance of the plugin registry is passed to each plugin via the initialize callback.


registerRootComponent 

/**
    * Register a component at the root of the channel view of the app.
    * Accepts a React component. Returns a unique identifier.
*/
registerRootComponent(component)

registerPopoverUserAttributesComponent 

/**
    * Register a component in the user attributes section of the profile popover (hovercard), below the default user attributes.
    * Accepts a React component. Returns a unique identifier.
*/
registerPopoverUserAttributesComponent(component)

registerPopoverUserActionsComponent 

/**
    * Register a component in the user actions of the profile popover (hovercard), below the default actions.
    * Accepts a React component. Returns a unique identifier.
*/
registerPopoverUserActionsComponent(component)

registerLeftSidebarHeaderComponent 

/**
    * Register a component fixed to the top of the left-hand channel sidebar.
    * Accepts a React component. Returns a unique identifier.
*/
registerLeftSidebarHeaderComponent(component)

registerBottomTeamSidebarComponent 

/**
    * Register a component fixed to the bottom of the team sidebar. Does not render if
    * user is only on one team and the team sidebar is not shown.
    * Accepts a React component. Returns a unique identifier.
*/
registerBottomTeamSidebarComponent(component)

registerPostMessageAttachmentComponent 

/**
    * Register a component fixed to the bottom of the post message.
    * Accepts a React component. Returns a unique identifier.
*/
registerPostMessageAttachmentComponent(component)

registerChannelHeaderButtonAction 

/**
    * Add a button to the channel header. If there are more than one buttons registered by any
    * plugin, a dropdown menu is created to contain all the plugin buttons.
    * Accepts the following:
    * - icon - React element to use as the button's icon
    * - action - a function called when the button is clicked, passed the channel and channel member as arguments
    * - dropdown_text - string or React element shown for the dropdown button description
    * - tooltip_text - string shown for tooltip appear on hover
*/
registerChannelHeaderButtonAction(icon, action, dropdownText, tooltipText)

registerPostTypeComponent 

/**
    * Register a component to render a custom body for posts with a specific type.
    * Custom post types must be prefixed with 'custom_'.
    * Accepts a string type and a component.
    * Returns a unique identifier.
*/
registerPostTypeComponent(type, component)

registerMainMenuAction 

/**
    * Register a main menu list item by providing some text and an action function.
    * Accepts the following:
    * - text - A string or React element to display in the menu
    * - action - A function to trigger when component is clicked on
    * - mobileIcon - A React element to display as the icon in the menu in mobile view
    * Returns a unique identifier.
*/
registerMainMenuAction(text, action, mobileIcon)

registerPostDropdownMenuAction 

/**
    * Register a post menu list item by providing some text and an action function.
    * Accepts the following:
    * - text - A string or React element to display in the menu
    * - action - A function to trigger when component is clicked on
    * - filter - A function whether to apply the plugin into the post' dropdown menu
    * Returns a unique identifier.
*/
registerPostDropdownMenuAction(text, action, filter)

registerPostDropdownMenuComponent 

/**
    * Register a component at the bottom of the post dropdown menu.
    * Accepts a React component. Returns a unique identifier.
*/
registerPostDropdownMenuComponent(component)

registerFileUploadMethod 

/**
    * Register a file upload method by providing some text, an icon, and an action function.
    * Accepts the following:
    * - icon - JSX element to use as the button's icon
    * - text - A string or JSX element to display in the file upload menu
    * - action - A function to trigger when the menu item is selected.
    * Returns a unique identifier.
*/
registerFileUploadMethod(icon, action, text)

registerFilesWillUploadHook 

/**
    * Register a hook to intercept file uploads before they take place.
    * Accepts a function to run before files get uploaded. Receives an array of
    * files and a function to upload files at a later time as arguments. Must
    * return an object that can contain two properties:
    * - message - An error message to display, leave blank or null to display no message
    * - files - Modified array of files to upload, set to null to reject all files
    * Returns a unique identifier.
*/
registerFilesWillUploadHook(hook)

unregisterComponent 

/**
    * Unregister a component, action or hook using the unique identifier returned after registration.
    * Accepts a string id.
    * Returns undefined in all cases.
*/
unregisterComponent(componentId)

registerReducer 

/**
    * Register a reducer against the Redux store. It will be accessible in redux state
    * under "state['plugins-<yourpluginid>']"
    * Accepts a reducer. Returns undefined.
*/
registerReducer(reducer)

registerWebSocketEventHandler 

/**
    * Register a handler for WebSocket events.
    * Accepts the following:
    * - event - the event type, can be a regular server event or an event from plugins.
    * Plugin events will have "custom_<pluginid>_" prepended
    * - handler - a function to handle the event, receives the event message as an argument
    * Returns undefined.
*/
registerWebSocketEventHandler(event, handler)

unregisterWebSocketEventHandler 

/**
    * Unregister a handler for a custom WebSocket event.
    * Accepts a string event type.
    * Returns undefined.
*/
unregisterWebSocketEventHandler(event)

registerReconnectHandler 

/**
    * Register a handler that will be called when the app reconnects to the
    * internet after previously disconnecting.
    * Accepts a function to handle the event. Returns undefined.
*/
registerReconnectHandler(handler)

unregisterReconnectHandler 

/**
    * Unregister a previously registered reconnect handler.
    * Returns undefined.
*/
unregisterReconnectHandler()

registerMessageWillFormatHook 

/**
    * Register a hook that will be called before a message is formatted into Markdown.
    * Accepts a function that receives the unmodified post and the message (potentially
    * already modified by other hooks) as arguments. This function must return a string
    * message that will be formatted.
    * Returns a unique identifier.
*/
registerMessageWillFormatHook(hook)

Theme 

In Mattermost, users are able to set custom themes that change the color scheme of the UI. It’s important that plugins have access to a user’s theme so that they can set their styling to match and not look out of place.

Every pluggable component in the web app will have the theme object as a prop.

The theme object has the following properties:

Property Description
sidebarBg Background color of the left-hand sidebar
sidebarText Color of text in the left-hand sidebar
sidebarUnreadText Color of text for unread channels in the left-hand sidebar
sidebarTextHoverBg Background color of channels when hovered in the left-hand sidebar
sidebarTextActiveBorder Color of the selected indicator channel indicator in the left-hand siebar
sidebarTextActiveColor Color of the text for the selected channel in the left-hand sidebar
sidebarHeaderBg Background color of the left-hand sidebar header
sidebarHeaderTextColor Color of text in the left-hand sidebar header
onlineIndicator Color of the online status indicator
awayIndicator Color of the away status indicator
dndIndicator Color of the do not disturb status indicator
mentionBg Background color for mention jewels in the left-hand sidebar
mentionColor Color of text for mention jewels in the left-hand sidebar
centerChannelBg Background color of channels, right-hand sidebar and modals/popovers
centerChannelColor Color of text in channels, right-hand sidebar and modals/popovers
newMessageSeparator Color of the new message separator in channels
linkColor Color of text for links
buttonBg Background color of buttons
buttonColor Color of text for buttons
errorTextColor Color of text for errors
mentionHighlightBg Background color of mention highlights in posts
mentionHighlightLink Color of text for mention links in posts
codeTheme Code block theme, either ‘github’, ‘monokai’, ‘solarized-dark’ or ‘solarized-light’

Exported Libraries and Functions 

The web app exports a number of libraries and functions on the window object for plugins to use. To avoid bloating your plugin, we recommend depending on these using Webpack externals or importing them manually from the window. Below is a list of the exposed libraries and functions:

Library Exported Name Description
react window.React ReactJS
react-dom window.ReactDOM ReactDOM
redux window.Redux Redux
react-redux window.ReactRedux React bindings for Redux
react-bootstrap window.ReactBootstrap Bootstrap for React
prop-types window.PropTypes PropTypes
post-utils window.PostUtils Mattermost post utility functions (see below)

post-utils 

Contains the following post utility functions:

formatText(text, options) 

Performs formatting of text including Markdown, highlighting mentions and search terms and converting URLs, hashtags, @mentions and ~channels to links by taking a string and returning a string of formatted HTML.

  • text - String of text to format, e.g. a post’s message.
  • options - (Optional) An object containing the following formatting options
  • searchTerm - If specified, this word is highlighted in the resulting HTML. Defaults to nothing.
  • mentionHighlight - Specifies whether or not to highlight mentions of the current user. Defaults to true.
  • mentionKeys - A list of mention keys for the current user to highlight.
  • singleline - Specifies whether or not to remove newlines. Defaults to false.
  • emoticons - Enables emoticon parsing with a data-emoticon attribute. Defaults to true.
  • markdown - Enables markdown parsing. Defaults to true.
  • siteURL - The origin of this Mattermost instance. If provided, links to channels and posts will be replaced with internal links that can be handled by a special click handler.
  • atMentions - Whether or not to render “@” mentions into spans with a data-mention attribute. Defaults to false.
  • channelNamesMap - An object mapping channel display names to channels. If provided, ~channel mentions will be replaced with links to the relevant channel.
  • team - The current team object.
  • proxyImages - If specified, images are proxied. Defaults to false.
messageHtmlToComponent(html, isRHS, options) 

Converts HTML to React components.

  • html - String of HTML to convert to React components.
  • isRHS - Boolean indicating if the resulting components are to be displayed in the right-hand sidebar. Has some minor effects on how UI events are triggered for components in the RHS.
  • options - (Optional) An object containing options
  • mentions - If set, mentions are replaced with the AtMention component. Defaults to true.
  • emoji - If set, emoji text is replaced with the PostEmoji component. Defaults to true.
  • images - If set, markdown images are replaced with the PostMarkdown component. Defaults to true.
  • latex - If set, latex is replaced with the LatexBlock component. Defaults to true.
Usage Example 

A short usage example of a PostType component using the post utility functions to format text.

const React = window.react;
const PostUtils = window['post-utils']; // import the post utilities
import PropTypes from 'prop-types';
import {makeStyleFromTheme} from 'mattermost-redux/utils/theme_utils';

export default class PostTypeFormatted extends React.PureComponent {

    // ...

    render() {
        const style = getStyle(this.props.theme);
        const post = this.props.post;

        const formattedText = PostUtils.formatText(post.message); // format the text

        return (
            <div
                style={style.container}
            >
                {'Formatted text: '}
                {PostUtils.messageHtmlToComponent(formattedText)} // convert the html to components
            </div>
        );
    }
}