Mattermost Logo
Edit on GitHub

Best Practices

See here for server-specific best practices for plugins. Webapp-specific best practices are incoming.

How can I create my own plugin setting? 

A plugin’s admin settings are defined in the plugin’s manifest setting schema. This includes any pre-defined types that the System Console UI currently supports.

Additionally, a plugin could define their own type of setting with a corresponding custom user interface that will be displayed in the system console following the process below.

  1. Define a type: custom setting in the plugins manifest settings_schema

    "settings_schema": {
    "settings": [{
        "key": "NormalSetting",
        "type": "text",
    +    }, {
    +        "key": "CustomSetting",
    +        "type": "custom"
    }]
    }
    
  2. In the plugin’s web app code, define a custom component to manage the plugin’s custom setting and register it in the web app with registerAdminConsoleCustomSetting. This component will be instantiated in the System Console with the following props passed in:

    • id: The setting key as defined in the plugin manifest within settings_schema.settings.
    • label: The text for the component label based on the setting’s displayName defined in the manifest.
    • helpText: The help text based on the setting’s helpText defined in the manifest.
    • value: The setting’s current json value in the config at the time the component is loaded.
    • disabled: Boolean indicating if the setting is disabled by a parent component within the System Console.
    • config: The server configuration loaded by the web app.
    • license: The license information for the related Mattermost server.
    • setByEnv: Boolean that indicates if the setting is based on a server environment variable.
    • onChange: Function that receives the setting id and current json value of the setting when it has been changed within the custom component.
    • setSaveNeeded: Function that will prompt the System Console to enable the Save button in the plugin settings screen.
    • registerSaveAction: Registers the given function to be executed when the setting is saved. This is registered when the custom component is mounted.
    • unRegisterSaveAction: On unmount of the custom component, unRegisterSaveAction will remove the registered function executed on save of the custom component.
  3. On initialization of the custom component, the current value of the custom setting is passed in the props.value in a json format as read from the config. This value can be processed as necessary to display in your custom UI and ready to be modified by the end user. In the example below, it processes the initial props.value and sets it in a local state for the component to use as needed:

    constructor(props) {
        super(props);
    
        this.state = {
            attributes: this.initAttributes(props.value),
        }
    }
    
  4. When a user makes a change in the UI, the OnChange handler sends back the current value of the setting as a json. Additionally, setSaveNeeded should be called to enable the Save button in order for the changes to be saved.

    handleChange = () => {
    ...
    
    this.props.onChange(this.props.id,  Array.from(this.state.attributes.values()));
    this.props.setSaveNeeded()
    };
    
  5. Once the user saves the changes, any handler that was registered with registerSaveAction will be executed to perform any additional custom actions the plugin may require, such as calling an additional endpoint within the plugin.

See Demo Plugin CustomSetting for a complete example.

How can I review the entire code base of a plugin? 

Carry out the following steps:

  1. Take a backup of project directory
  2. Create a dummy-master branch with no code:

    git checkout --orphan dummy-master
    git rm -rf
    git push origin dummy-master
    
  3. Create a dummy-review branch from dummy-master:

    git checkout -b dummy-review
    git add
    git commit -m "Full checkin"
    git push origin dummy-review
    
  4. Create a PR from dummy-review -> dummy-master

  5. Code review on the resulting PR