Config Modifiers

Register plugin's configModifiers

What is Config Modifiers?

configModifiers is an object of methods that will be called from Dashboard when updating the plugin for certain versions and allows the plugin to modify and change the config before updating the plugin.

This will allow the plugin to twist the config for their need, it can add new config keys, remove existing config keys or modify existing ones.

This will give you the ability to reduce your config breaking changes when you release your plugin, which means that users don't have to go to plugin configuration when they update and change/save the config if your plugin's config has any breaking changes.

For example, if you moved a config ref key from a place to another, or you changed the type/structure of a config ref key ex: from an Object to an Array of Objects Then you can fix the changes with configModifiers, and update the config dynamically and avoid crashing the plugin due to your config changes!

How does it work?

You can register a config modifier for each version you want, and Dashboard will run all the modifiers in order from the current installed version to the newest one in your configModifiers

Let's say a Dashboard has your plugin installed with version 2.3.0, and the user is updating from 2.3.0 to the latest version of your plugin 2.4.0 Dashboard will run your 2.4.0 modifier and pass the current user's config and expects an updated config Object to be returned

Example

A user have version 2.3.0 with the following config:

{
    "title": "My awesome plugin",
    "username": "Dashboard_Admin",
    "password": "supperSecretPassword"
}

And in your new version 2.4.0 you have moved both keys username/password from the root config.username/config.password to a new ref key credentials config.credentials.username/config.credentials.password

Usually such a change like this in the config requires you to bump your plugin version from 2.3.0 to 3.0.0 before releasing, as it is a breaking changes in the config and the plugin won't work with out the user update it's config

Here comes the configModifiers part You can bump your plugin version with minor bump instead of a major bump and your configModifiers will take care of fixing the config without requiring the user to do the manual work

In this case your configModifiers will look something like

configModifiers: {
    "2.4.0": config => {
        let updatedConfig = config

        updatedConfig.credentials = {
            username: updatedConfig.username,
            password: updatedConfig.password
        }
        
        delete updatedConfig.username
        delete updatedConfig.password
        
        return updatedConfig
    }
}

After the user updates from ANY version older than your new 2.4.0, Dashboard will run the "2.4.0" modifier and update the config with the returned value

So the user's config will be updated from the returned value from your modifier and it should look like

{
    "title": "My awesome plugin",
    "credentials": {
        "username": "Dashboard_Admin",
        "password": "supperSecretPassword"
    }
}

You can register multiple modifiers at the same time and Dashboard will sort them automatically and run them in order from the oldest to matched version that the user is updating to

Multiple modifiers

configModifiers: {
    "2.5.0": config => {
        let updatedConfig = config
        
        updatedConfig.applicationName = updatedConfig.title
        
        delete updatedConfig.title
        
        return updatedConfig
    },
    "2.4.0": config => {
        let updatedConfig = config

        updatedConfig.credentials = {
            username: updatedConfig.username,
            password: updatedConfig.password
        }
        
        delete updatedConfig.username
        delete updatedConfig.password
        
        return updatedConfig
    }
}

How to register?

You can register configModifiers from the main register() API for your plugin

import DashboardPlugin from 'Dashboard/plugin'

const Plugin = new DashboardPlugin('@plugin_bundle')

const registerPlugin = () => {
    const { Application } = require('@components/Application')
    
    Plugin.register({
        application: Application,

        configModifiers: {
            "2.5.0": config => {
                let updatedConfig = config
                ...
                return updatedConfig
            },
            "2.4.0": config => {
                let updatedConfig = config
                ...
                return updatedConfig
            }
        }
    })
}

registerPlugin()

export {
    Plugin
}

Advanced example

import DashboardPlugin from 'Dashboard/plugin'

const Plugin = new DashboardPlugin('@plugin_bundle')

const registerPlugin = () => {
    const { Application } = require('@components/Application')
    
    Plugin.register({
        application: Application,

        configModifiers: {
            "3.0.0": config => {
                let updatedConfig = config
                
                updatedConfig.types = [
                    {
                        ...updatedConfig.itemTpye
                    }
                ]
                
                delete updatedConfig.itemType
                
                if (Array.isArray(updatedConfig?.data?.columns) && updatedConfig.data.columns.length) {
                    updatedConfig.data.columns = updatedConfig.data.columns.map((column, index) => {
                        return {
                            ...column,
                            id: `${column.name}-${index}`
                            description: `${column.name}-description`
                        }
                    })
                }
                
                if (updatedConfig.sortings && Object.keys(updatedConfig.sortings).length) {
                    updatedConfig.sortings = Object.entries(updatedConfig.sortings).map(sorting => {
                        return {
                            name: sorting.key,
                            ...sorting.value
                        }
                    })
                }
                
                return updatedConfig
            }
        }
    })
}

registerPlugin()

export {
    Plugin
}

By registering multiple modifiers, Dashboard will make sure to run all of them in the correct order if the user is skipping versions and update to the latest

This will make sure that your plugin got all the previous changes and avoid crashing the plugin