Requirements

register requirements for your plugin with Dashboard

What is requirements?

Plugin requirements is a way to tell Dashboard what the plugin needs to be able to run in Dashboard correctly.

For example: you can tell Dashboard that your plugin needs a specific Dashboard version or a React version or a specific browser to run your plugin in or maybe that it needs some actions from other plugins!

What does that mean: lets say that your plugin require some methods from Dashboard and these methods are available with Dashboard v3.0.0, and you say: "hey! my plugin requires Dashboard v3 or higher", when a user tries to run your plugin in Dashboard v2.0.0 for example, we will notify the user that your plugin require a newer version of Dashboard in order to run, and that goes for all other requirements that you can register with Dashboard

What kind of requirements can i register?

with requirements object you can register one or more of these keys:

Key	Description
actions	An array of required actions that needed to be used in your plugin
portals	An array of required portals that needed to be used in your plugin
browsers	An array of browser names that your plugin needs to be able to run in
dashboardVersion	A string of Dashboard version that your plugin needs to be able to run in
reactVersion	A string of React version that your plugin needs to be able to run with

Actions

In order to require actions for your plugin you need to pass an array of objects with requirements object with a key "actions"

Action object

Key	Description
id	An id to your required action that will be mapped into so you can use it in your plugin.
name	A name to describe your required action.
description	A description for your required action, what is it for, and what does it need.

Example

actions: [
    {
        id: 'my-action-to-open-article',
        name: 'Open articles',
        description: 'An action need it to handle opening articles in Writer plugin.'
    }
]

Read more about actions:

pageActions

Portals

In order to require portals for your plugin you need to pass an array of objects with requirements object with a key "portals"

Portal object

Key	Description
id	An id to your required portal that will be mapped into so you can use it in your plugin.
name	A name to describe your required portal.
description	A description for your required action, what is it for, and what does it need.

Example

portals: [
    {
        id: 'my-portal-to-create-article',
        name: 'Create articles',
        description: 'A portal need it to handle creating articles.'
    }
]

Browsers

In order to require a specific browser or more for your plugin you need to pass an array of strings "browser names" with requirements object with a key "browsers"

Example

browsers: ['chrome', 'safari']

Dashboard version

In order to require a specific version of Dashboard for your plugin you need to pass a string of Dashboard version with requirements object with a key "dashboardVersion"

Example

dashboardVersion: '4.0.2'

React version

In order to require a specific version of React for your plugin you need to pass a string of React version with requirements object with a key "reactVersion"

Example

reactVersion: '16.8.0'

For dashboardVersion and reactVersion, Dashboard will take in consider to match the requested version or higher.

How can i register requirements for my plugin 🤔

Simply by passing your requirements object to register() method from Plugin-API 🙃

Example

import DashboardPlugin from 'Dashboard/plugin'

const Plugin = new DashboardPlugin('@plugin_bundle')

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

        requirements: {
            actions: [
                {
                    id: 'OPEN_ARTICLE_IN_WRITER',
                    name: 'Open article in Writer',
                    description: 'Action to handle open articles in Writer plugin'
                }
            ],
            portals: [
                {
                    id: 'CREATE_CONCEPTS',
                    name: 'Create new concepts',
                    description: 'Portal component to handle creating new concepts.'
                }
            ],
            browsers: ['chrome'],
            dashboardVersion: '4.0.3',
            reactVersion: '16.8.0'
        }
    })
}

registerPlugin()

export {
    Plugin
}

When your plugin register requirements with Dashboard, Dashboard will run a check for all the requirements your plugin registered.

And in case one or more of the requirements failed, Dashboard will notify the user what exactly went wrong.

If the requirements check failed, the user will be notified about what went wrong, and Dashboard won't run your Application within the workspace, but the user always have the ability to run your Application anyway even if the requirements check failed

Example of what the user will get if something went wrong with requirements check

In your Application/Agent component you will be able to access a status property. This property will contain information regarding the status from the requirement check. If the user choose to run the application anyway the information on what went wrong will be available to you in that property.

So now after we know what "requirements" is and how we register requirements with Dashboard. It's time to see how can we use the required "actions" and "portals" and how to configure them.

In order to understand how to configuration and use requirements, we have one more thing for you 🤫 We call it Mappings

lets move on to Mappings shall we 🤓

pageMappings