Skip to content

Commit

Permalink
Add documentation for PluginMenu
Browse files Browse the repository at this point in the history
  • Loading branch information
@jeremystretch
jeremystretch committed Sep 28, 2022
1 parent db90b08 commit d046524
Show file tree
Hide file tree
Showing 2 changed files with 62 additions and 57 deletions.
107 changes: 58 additions & 49 deletions docs/plugins/development/navigation.md
View file
Original file line number Diff line number Diff line change
@@ -1,85 +1,94 @@
# Navigation

## Menu Items
## Menus

To make its views easily accessible to users, a plugin can inject items in NetBox's navigation menu under the "Plugins" header. Menu items are added by defining a list of PluginMenuItem instances. By default, this should be a variable named `menu_items` in the file `navigation.py`. An example is shown below.
!!! note
This feature was introduced in NetBox v3.4.

!!! tip
The path to declared menu items can be modified by setting `menu_items` in the PluginConfig instance.
A plugin can register its own submenu as part of NetBox's navigation menu. This is done by defining a variable named `menu` in `navigation.py`, pointing to an instance of the `PluginMenu` class. Each menu must define a label and grouped menu items (discussed below), and may optionally specify an icon. An example is shown below.

```python
from extras.plugins import PluginMenuButton, PluginMenuItem
from utilities.choices import ButtonColorChoices
```python title="navigation.py"
from extras.plugins import PluginMenu

menu_items = (
PluginMenuItem(
link='plugins:netbox_animal_sounds:random_animal',
link_text='Random sound',
buttons=(
PluginMenuButton('home', 'Button A', 'fa fa-info', ButtonColorChoices.BLUE),
PluginMenuButton('home', 'Button B', 'fa fa-warning', ButtonColorChoices.GREEN),
)
menu = PluginMenu(
label='My Plugin',
groups=(
('Foo', (item1, item2, item3)),
('Bar', (item4, item5)),
),
icon='mdi mdi-router'
)
```

A `PluginMenuItem` has the following attributes:
Note that each group is a two-tuple containing a label and an iterable of menu items. The group's label serves as the section header within the submenu. A group label is required even if you have only one group of items.

| Attribute | Required | Description |
|---------------|----------|------------------------------------------------------|
| `link` | Yes | Name of the URL path to which this menu item links |
| `link_text` | Yes | The text presented to the user |
| `permissions` | - | A list of permissions required to display this link |
| `buttons` | - | An iterable of PluginMenuButton instances to include |
!!! tip
The path to the menu class can be modified by setting `menu` in the PluginConfig instance.

## Optional Header
A `PluginMenu` has the following attributes:

Plugin menus normally appear under the "Plugins" header. An optional menu_heading can be defined to make the plugin menu to appear as a top level menu header. An example is shown below:
| Attribute | Required | Description |
|--------------|----------|---------------------------------------------------|
| `label` | Yes | The text displayed as the menu heading |
| `groups` | Yes | An iterable of named groups containing menu items |
| `icon_class` | - | The CSS name of the icon to use for the heading |

```python
!!! tip
Supported icons can be found at [Material Design Icons](https://materialdesignicons.com/)

### The Default Menu

If your plugin has only a small number of menu items, it may be desirable to use NetBox's shared "Plugins" menu rather than creating your own. To do this, simply declare `menu_items` as a list of `PluginMenuItems` in `navigation.py`. The listed items will appear under a heading bearing the name of your plugin in the "Plugins" submenu.

```python title="navigation.py"
menu_items = (item1, item2, item3)
```

!!! tip
The path to the menu items list can be modified by setting `menu_items` in the PluginConfig instance.

## Menu Items

Each menu item represents a link and (optionally) a set of buttons comprising one entry in NetBox's navigation menu. Menu items are defined as PluginMenuItem instances. An example is shown below.

```python filename="navigation.py"
from extras.plugins import PluginMenuButton, PluginMenuItem
from utilities.choices import ButtonColorChoices

menu_heading = {
"title": "Animal Sound",
"icon": "mdi-puzzle"
}

menu_items = (
PluginMenuItem(
link='plugins:netbox_animal_sounds:random_animal',
link_text='Random sound',
buttons=(
PluginMenuButton('home', 'Button A', 'fa fa-info', ButtonColorChoices.BLUE),
PluginMenuButton('home', 'Button B', 'fa fa-warning', ButtonColorChoices.GREEN),
)
),
item1 = PluginMenuItem(
link='plugins:myplugin:myview',
link_text='Some text',
buttons=(
PluginMenuButton('home', 'Button A', 'fa fa-info', ButtonColorChoices.BLUE),
PluginMenuButton('home', 'Button B', 'fa fa-warning', ButtonColorChoices.GREEN),
)
)
```

The `menu_heading` has the following attributes:
A `PluginMenuItem` has the following attributes:

| Attribute | Required | Description |
|---------------|----------|------------------------------------------------------|
| `title` | Yes | The text that will show in the menu header |
| `icon` | Yes | The icon to use next to the headermdi |

!!! tip
The icon names can be found at [Material Design Icons](https://materialdesignicons.com/)
| `link` | Yes | Name of the URL path to which this menu item links |
| `link_text` | Yes | The text presented to the user |
| `permissions` | - | A list of permissions required to display this link |
| `buttons` | - | An iterable of PluginMenuButton instances to include |

## Menu Buttons

Each menu item can include a set of buttons. These can be handy for providing shortcuts related to the menu item. For instance, most items in NetBox's navigation menu include buttons to create and import new objects.

A `PluginMenuButton` has the following attributes:

| Attribute | Required | Description |
|---------------|----------|--------------------------------------------------------------------|
| `link` | Yes | Name of the URL path to which this button links |
| `title` | Yes | The tooltip text (displayed when the mouse hovers over the button) |
| `icon_class` | Yes | Button icon CSS class* |
| `icon_class` | Yes | Button icon CSS class |
| `color` | - | One of the choices provided by `ButtonColorChoices` |
| `permissions` | - | A list of permissions required to display this button |

*NetBox supports [Material Design Icons](https://materialdesignicons.com/).
Any buttons associated within a menu item will be shown only if the user has permission to view the link, regardless of what permissions are set on the buttons.

!!! note
Any buttons associated within a menu item will be shown only if the user has permission to view the link, regardless of what permissions are set on the buttons.
!!! tip
Supported icons can be found at [Material Design Icons](https://materialdesignicons.com/)
12 changes: 4 additions & 8 deletions netbox/extras/plugins/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -204,19 +204,15 @@ def register_template_extensions(class_list):
#

class PluginMenu:
icon = 'mdi-puzzle'
icon_class = 'mdi-puzzle'

def __init__(self, label, groups, icon=None):
def __init__(self, label, groups, icon_class=None):
self.label = label
self.groups = [
MenuGroup(label, items) for label, items in groups
]
if icon is not None:
self.icon = icon

@property
def icon_class(self):
return f'mdi {self.icon}'
if icon_class is not None:
self.icon_class = icon_class


class PluginMenuItem:
Expand Down

0 comments on commit d046524

Please sign in to comment.