Plugin SDK > Opening modals

Opening modals

Within all the renderXXX hooks — that is, those that have the task of presenting a custom interface part to the user — it is possible to open custom modal dialogs to "get out" of the reduced space that the iframe provides, and get more room to build more complex interfaces.

Suppose our plugin implements a custom page accessible from the top navigation bar:

1
import React from 'react';
2
import ReactDOM from 'react-dom';
3
import { connect, MainNavigationTabsCtx, RenderPageCtx } from 'datocms-plugin-sdk';
4
import { Canvas } from 'datocms-react-ui';
5

6
function render(component: React.ReactNode) {
7
  ReactDOM.render(
8
    <React.StrictMode>{component}</React.StrictMode>,
9
    document.getElementById('root'),
10
  );
11
}
12

13
connect({
14
  mainNavigationTabs(ctx: MainNavigationTabsCtx) {
15
    return [
16
      {
17
        label: 'Welcome',
18
        icon: 'igloo',
19
        pointsTo: {
20
          pageId: 'welcome',
21
        },
22
      },
23
    ];
24
  },
25
  renderPage(pageId, ctx: RenderPageCtx) {
26
    switch (pageId) {
27
      case 'welcome':
28
        return render(<WelcomePage ctx={ctx} />);
29
    }
30
  },
31
});
32

33
type PropTypes = {
34
  ctx: RenderPageCtx;
35
};
36

37
function WelcomePage({ ctx }: PropTypes) {
38
  return <Canvas ctx={ctx}>Hi!</Canvas>;
39
}

Within the ctx argument you can find the function openModal(), which triggers the opening of a modal:

1
import { Canvas, Button } from 'datocms-react-ui';
2

3
function WelcomePage({ ctx }: PropTypes) {
4
  const handleOpenModal = async () => {
5
    const result = await ctx.openModal({
6
      id: 'customModal',
7
      title: 'Custom title!',
8
      width: 'l',
9
      parameters: { name: 'Mark' },
10
    });
11
    ctx.notice(result);
12
  };
13

14
  return (
15
    <Canvas ctx={ctx}>
16
      <Button type="button" onClick={handleOpenModal}>
17
        Open modal!
18
      </Button>
19
    </Canvas>
20
  );
21
}

The openModal() function offers various rendering options, for example you can set its size and title. Interestingly, the function returns a promise, which will be resolved when the modal is closed by the user.

You can specify what to render inside the modal by implementing a new hook called renderModal which, similarly to what we did with custom pages, initializes React with a custom component:

connect({
  renderModal(modalId: string, ctx: RenderModalCtx) {
    switch (modalId) {
      case 'customModal':
        return render(<CustomModal ctx={ctx} />);
    }
  },
});

You are free to fill the modal with the information you want, and you can access the parameters specified when opening the modal through ctx.parameters:

1
import { Canvas } from 'datocms-react-ui';
2

3
type PropTypes = {
4
  ctx: RenderModalCtx;
5
};
6

7
function CustomModal({ ctx }: PropTypes) {
8
  return (
9
    <Canvas ctx={ctx}>
10
      <div style={{ fontSize: 'var(--font-size-xxxl)', fontWeight: '500' }}>
11
        Hello {ctx.parameters.name}!
12
      </div>
13
    </Canvas>
14
  );
15
}

As with any other hook, it is important to wrap the content inside the Canvas component, so that the iframe will continuously auto-adjust its size based on the content we're rendering, and to give our app the look and feel of the DatoCMS web app.

Closing the modal

If the modal will be closed through the close button provided by the interface, the promise openModal() will be resolved with value null.

You can also decide not to show a "close" button:

const result = await sdk.openModal({
  id: 'customModal',
  // ...
  closeDisabled: true,
});

In this case the user will only be able to close the modal via an interaction of your choice (custom buttons, for example):

1
import { Canvas, Button } from 'datocms-react-ui';
2

3
function CustomModal({ ctx }: PropTypes) {
4
  const handleClose = (returnValue: string) => {
5
    ctx.resolve(returnValue);
6
  };
7

8
  return (
9
    <Canvas ctx={ctx}>
10
      Hello {ctx.parameters.name}!
11
      <Button type="button" onClick={handleClose.bind(null, 'a')}>Close A</Button>
12
      <Button type="button" onClick={handleClose.bind(null, 'b')}>Close B</Button>
13
    </Canvas>;
14
}

The ctx.resolve() function will close the modal, and resolve the original openModal() promise with the value you passed.

`renderModal(modalId: string, ctx)`

This function will be called when the plugin requested to open a modal (see the openModal hook).

Context object

The following properties and methods are available in the ctx argument:

This hook exposes additional information and operations specific to the context in which it operates.

The ID of the modal that needs to be rendered.