Portals

register Portals components to be rendered in other plugins.

What is a Portal and what can I do with it?

A portal is a component that a plugin exports in order to be used internally or by other plugins.

To be able to register Portals with Dashboard you should pass an Array of objects with key `portals` and each object of your Portals should contain a valid React component and a uniq id to be target the Portal with that id.

Portal object:

{
    id: 'my-awesome-portal',
    name: 'My awesome portal',
    description: 'A portal component will render an image within a stylish frame',
    component: MyPortalComponent
}

example

Registering a portal with Dashboard.

import DashboardPlugin from 'Dashboard/plugin'

const Plugin = new DashboardPlugin('@plugin_bundle')

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

        portals: [
            {
                id: 'my-awesome-portal',
                name: 'My awesome portal',
                description: 'A portal component will render an image within a stylish frame',
                component: MyAwesomePortal
            }
        ]
    })
}

registerPlugin()

export {
    Plugin
}

Now your Portal has been register in Dashboard with the given id 'my-awesome-portal' and can be used with other plugin.

A portal component can only be a valid react component.

example

Function based

import { forwardRef } from 'react'

import {
    Wrapper,
    StyledImg
} from './style'

const PortalComponent = (props, ref) => {
    const { imageSrc, onImageLoaded } = props

    return (
        <Wrapper ref={ref}>
            <StyledImg
                src={imageSrc}
                onLoad={onImageLoaded}
            />
        </Wrapper>
    )
}

const MyAwesomePortal = forwardRef(PortalComponent)

export {
    MyAwesomePortal
}

Now after we have our portal component, we can import it and use it in our plugin and other plugins can also use it and render it

How to use a Portal?

You can use a portal in your plugin with the method `getPortal` that can be accessible from the Plugin-API

And by passing the Portal id to `getPortal` it will return the portal component and ready to use in your plugin.

example

We will use the Portal that we just registered with the other plugin 👆🏽 with the giving id 'my-awesome-portal'

pagegetPortal

Results:

ImagePortal

💁‍♀️Tips for writing Portals

• Don't connect your portal with your application redux state if you are using one

  when connecting a portal component with redux state it won't get the state from redux HOC, because your portal component won't be rendered within the redux provider for your state, it's rendered outside the provider context, you can of course have an internal state for your portal and connect all the children with portal's state

• Don't wrap your portal with any of your application contextHOCs if there is any

  Same like the redux connect, your portal component will be rendered outside of your context provider

• Style

  all the style rules will work fine in your portal, but if you are using styled-components and you have a custom theme and you wrap your application with a theme providerthe same applies here. in this case you should wrap your portal with another theme provider and pass the theme object as a prop.

• Config

  your portal component will get your plugin config by default such like Application, Widget .. from props