Mappings

Mappings is a part of requirements that a plugin register with Dashboard.

As we saw in Requirements, we register some required Actions/Portals

How can i see my required actions/portals and configure them?

You can see all the requirements for all the plugins in the plugin settings in Plugins store

Plugin settings UI

By clicking on Mappings you you will be navigated to mappings settings

In this example we are using a live plugin called OC-Search

So when a plugin register actions as requirements like our example here, Dashboard will list all the required actions in mappings settings.

If we take a look at it, we can see each row has a name and a description in the left side, these from each action object we register in our example in Requirements if you remember.

And in the right side of each row there is a DropDown and an info box beneath it, the info box will tell if you have selected an action from the DropDown and what is it, or not so you have to do it.

Okay! so far so good, isn't 🙃 the question now is

How can i map actions/portals to my requirements?

As we mentioned before, in the right side there is a DropDown of each row "required action/portal", by clicking on any of them, it will open a list of all the registered Actions/Portals in Dashboard so you can select form it and map to the requirements.

So now we have mapped all the required actions to our plugin.

By selecting the actions, you can see that the info box for each row displays which action has been selected, and what is it for.

The same exact flow goes with Portals

How can i use the mapped actions/portals in my plugin?

When the user has configured Mappings and gave each required action a value and saved, Dashboard will pass a prop to your Plugin named "mappings" you will get that prop object with all Dashboard components Application, Widget, Agent ...

and the mappings prop contain all the configured requirements that the user has set in Mappings settings.

For example, in our OC-Search plugin i printed the mappings prop to the console when the component did mount

import { Plugin } from '@root'

class OpenContentSearch extends Plugin.Application {
    constructor(props) {
        super(props)
    }

    componentDidMount() {
        console.log(this.props.mappings)
    }
}

Output

{
    "actions": [
        {
            "key": "open-article",
            "name": "Open article in Writer",
            "action": "com.naviga.writer:openArticle",
            "bundle": "com.naviga.writer",
            "description": "Action to handle open articles in Writer plugin"
        },
        {
            "key": "push-notification",
            "name": "Push notification handler",
            "action": "com.naviga.notificaion-agent:add",
            "bundle": "com.naviga.notificaion-agent",
            "description": "An action will be called to handle displying notifications."
        },
        {
            "key": "content-handler",
            "name": "Fetch content handler",
            "action": "com.naviga.content-agent:getInstance",
            "bundle": "com.naviga.content-agent",
            "description": "An action will be called to handle requests and fetching content."
        },
        {
            "key": "image-handler",
            "name": "Build image urls handler",
            "action": "com.naviga.icp:getInstance",
            "bundle": "com.naviga.icp",
            "description": "An action will be called to handle building images src."
        }
    ],
    "portals": []
}

Here we can see that the mappings object has two keys: actions and portals

we can see that the actions array has the mappings settings that the user configured in Mappings UI

Lets take a closer look at the first action object for example, and explain some stuff 🤓

{
    "key": "open-article",
    "name": "Open article in Writer",
    "action": "com.naviga.writer:openArticle",
    "bundle": "com.naviga.writer",
    "description": "Action to handle open articles in Writer plugin"
}

Key	Value
key	The required action id that you registered with requirements object
name	The required action name that you registered with requirements object
action	The mapped action id that the user selected from Mappings UI
bundle	The plugin bundle that is the owner of the mapped action
description	The required action description that you registered with requirements object

In our example OC-Search plugin, we registered a required action with an id "open-article"

when the user mapped our required action, we received a mapped item basically says your required action with key "open-article" has been mapped to an action "com.naviga.writer:openArticle"

So now in our plugin we can use the required action id "open-article" to get the action and use call it, simply by passing the mapped action to Plugin.getAction() and voalá! we have an action to open articles with Writer plugin that has been mapped by the user.

Again, the same exact flow goes with Portals, but instead we pass the id to Plugin.getPortal()

import { Plugin } from 'Dashbaord'

import {
    useRef,
    useEffect
} from 'react'

const ArticleCard = props => {
    const openArticleWithWriter = userRef()
    
    useEffect(() => {
        const openArticleAction = Plugin.getAction('open-article')
        
        openArticleWithWriter.current = openArticleAction
    }, [])
    
    const { article } = props
    
    return (
        <Card
            uuid={article.uuid}
            headline={article.headline}
            onClick={() => {
                openArticleWithWriter.current(article)
            }}
        />
    )
}