piral-modals
Version:
Plugin for the display of modal dialogs in Piral.
166 lines (110 loc) • 4.82 kB
Markdown
[](https://piral.io)
# [Piral Modals](https://piral.io) · [](https://github.com/smapiot/piral/blob/main/LICENSE) [](https://www.npmjs.com/package/piral-modals) [](https://jestjs.io) [](https://discord.gg/kKJ2FZmK8t)
This is a plugin that only has a peer dependency to `piral-core`. What `piral-modals` brings to the table is a set of Pilet API extensions that can be used with `piral` or `piral-core` to easily trigger the display of modal dialogs from pilets.
## Why and When
If you have modal dialogs on your page that `piral-modals` gives you a nice abstraction over registering components for them. These items will be stored in the global state container and will be filtered on a given dialog name. Thus the plugin makes only sense if you want to have consistent dialog management.
Alternative: You could simply use an event to trigger opening a dialog. The event could transport a React component which would then be globally used. Alternatively, each pilet would come up with its own dialog design and management system.
## Video
We also have a video for this plugin:
@[youtube](https://youtu.be/gZt7Ic1BHNA)
## Documentation
The following functions are brought to the Pilet API.
### `registerModal()`
Adds a modal dialog definition to the app shell. Can be called from *any* pilet using the specified name.
### `unregisterModal()`
Removes a modal dialog definition from the app shell.
### `showModal()`
Shows the modal dialog registered with the provided name.
Does not open in case no modal dialog using the provided name is available (i.e., registered in the app shell).
## Usage
::: summary: For pilet authors
You can use the `showModal` function from the Pilet API to show a modal dialog registered by any pilet. In case of a naming conflict the dialogs from the current pilet are preferred.
Example use:
```ts
import { PiletApi } from '<name-of-piral-instance>';
export function setup(piral: PiletApi) {
piral.showModal('my-modal', {
someValue: 42,
});
}
```
You can use the `registerModal` function from the Pilet API to add a new modal dialog in the app shell.
Example use:
```ts
import { PiletApi } from '<name-of-piral-instance>';
import { MyModal } from './MyModal';
export function setup(piral: PiletApi) {
piral.registerModal('my-modal', MyModal);
}
```
You can use the `unregisterModal` function from the Pilet API to remove a previously added modal dialog from the app shell.
Example use:
```ts
import { PiletApi } from '<name-of-piral-instance>';
export function setup(piral: PiletApi) {
piral.unregisterModal('my-modal');
}
```
:::
::: summary: For Piral instance developers
The provided library only brings API extensions for pilets to a Piral instance.
For the setup of the library itself you'll need to import `createModalsApi` from the `piral-modals` package.
```ts
import { createModalsApi } from 'piral-modals';
```
The integration looks like:
```ts
const instance = createInstance({
// important part
plugins: [createModalsApi()],
// ...
});
```
Via the options the globally available `dialogs` can be defined.
For example:
```ts
const instance = createInstance({
// important part
plugins: [createModalsApi({
dialogs: [
{
name: 'userinfo',
component: UserInfoModal,
},
],
})],
// ...
});
```
In order to host the modal dialogs you'll need to embed the `Modals` component somewhere in your layout.
As an example:
```jsx
import { Modals } from 'piral-modals';
const MyLayout = ({ children }) => {
<div>
<Modals />
{children}
</div>
};
```
If you want to customize the styling (which you should) make sure to register components such as `ModalsHost` (shell for the modals) or `ModalsDialog` (wrapper for an individual dialog) via, e.g., `<SetComponent name="ModalsHost" component={MyModalsHost} />`.
### Customizing
You can customize the available dialogs and their options.
```ts
import type {} from 'piral-modals';
declare module 'piral-modals/lib/types' {
// interface shared across all dialogs defined in PiralCustomModalsMap
interface BaseModalOptions {
common?: boolean;
}
interface PiralCustomModalsMap {
login: {
required?: boolean;
};
}
}
// now showModal("login", { required: true, common: true }) is strongly typed in pilets
```
:::
## License
Piral is released using the MIT license. For more information see the [license file](./LICENSE).