This is a plugin that only has a peer dependency to piral-core
. What piral-menu
brings to the table is a set of Pilet API extensions that can be used with piral
or piral-core
to bring a simplified menu integration from your pilets to your Piral instance.
If you are using one or many global menu(s) on your page, piral-menu
allows you to register menu item components for those global menus from your pilets. Menu items are registered in the application's global state and can be rendered by an app shell via a Menu
component. piral-menu
supports multiple menu types via a type
attribute, for example for a general
menu or a user
menu. Using this plugin only makes sense if your page uses a global menu.
Alternative: You could simply use dedicated extension slots for each navigation items. The downside of this approach is the discoverability and the type safety.
We also have a video for this plugin:
The following functions are brought to the Pilet API.
Adds the definition of a menu item to the app shell. Optionally specifies the type of menu where the item should be shown.
If the first argument is a string, a named menu item is registered. A named menu item can also be removed.
Removes a menu item from the app shell. This requires a named menu item.
::: summary: For pilet authors
You can use the registerMenu
function from the Pilet API to add a new menu item in the app shell.
Note: If the first argument is a string, we call it a named menu item.
Example use:
import { PiletApi } from '<name-of-piral-instance>';
import { MyMenuItem } from './MyMenuItem';
export function setup(piral: PiletApi) {
// Register the `MyMenuItem` component for the default menu:
piral.registerMenu(MyMenuItem);
// Register the `MyMenuItem` component for the special 'user' menu:
piral.registerMenu(MyMenuItem, { type: 'user' });
}
You can use the unregisterMenu
function from the Pilet API to remove a previously added menu item from the app shell.
Note: You'll need to have added a named menu item in order to be able to remove it.
Example use:
import { PiletApi } from '<name-of-piral-instance>';
import { MyTile } from './MyMenuItem';
export function setup(piral: PiletApi) {
// Register the menu item with a unique name:
piral.registerMenu('first', MyMenuItem);
// And, at some later time, unregister it via that name:
piral.unregisterMenu('first');
}
:::
::: 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 createMenuApi
from the piral-menu
package.
import { createMenuApi } from 'piral-menu';
The integration looks like:
const instance = createInstance({
// important part
plugins: [createMenuApi()],
// ...
});
Via the options, defaultSettings
and the global/initially available menu items
can be defined.
For example:
const instance = createInstance({
// important part
plugins: [createMenuApi({
defaultSettings: {
type: 'admin',
},
items: [
{
component: HomeMenuItem,
},
],
})],
// ...
});
You can customize the available menu settings.
import type {} from 'piral-menu';
declare module 'piral-menu/lib/types' {
interface PiralCustomMenuSettings {
category?: string;
}
}
// now registerMenu(() => null, { category: 'general' }) is strongly typed in pilets
You can also add new menu types to the type
selection.
import 'piral-menu';
declare module 'piral-menu/lib/types' {
interface PiralCustomMenuTypes {
'left-footer': {};
}
}
// now registerMenu(() => null, { type: 'left-footer' }) is strongly typed in pilets
This also allows you to add further settings, which you'll find nice to have:
import 'piral-menu';
declare module 'piral-menu/lib/types' {
interface PiralCustomMenuTypes {
'left-footer': {
caption: string;
};
}
}
// now registerMenu(() => null, { type: 'left-footer', caption: 'Foo' }) is strongly typed in pilets
:::
Piral is released using the MIT license. For more information see the license file.