# Portals

## 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:

```javascript
{
    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.

```javascript
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.

{% hint style="info" %}
A portal component can only be a valid react component.
{% endhint %}

#### example

{% tabs %}
{% tab title="Function based" %}

```jsx
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
}
```

{% endtab %}
{% endtabs %}

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'

{% content-ref url="../getportal" %}
[getportal](https://docs.navigaglobal.com/dashboard-plugin/api-and-gui/api/getportal)
{% endcontent-ref %}

####

#### Results:

![ImagePortal](https://2209870672-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbTKPOIEi2LNGOi0-yz%2F-LeB3BkyBxzVtI1UuXoT%2F-LeB4pm0BdsSLjkdut3J%2FScreenshot%202019-05-06%20at%2009.41.23.png?alt=media\&token=8944fdfd-9966-464f-8d00-ff4f21aaa858)

### 💁‍♀️Tips for writing Portals&#x20;

* **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 provider`the 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