From d0edd9d5c1f436386daf6bb658f09f7015c3bc1f Mon Sep 17 00:00:00 2001
From: Jeremy Stretch <stretch@packetlife.net>
Date: Wed, 25 Mar 2020 14:33:32 -0400
Subject: [PATCH] Update documentation for #4401

---
 docs/plugins/development.md                   | 41 ++++++++++++-------
 netbox/extras/plugins/__init__.py             |  2 +-
 .../templates/inc/plugin_nav_menu_items.html  |  4 +-
 3 files changed, 30 insertions(+), 17 deletions(-)

diff --git a/docs/plugins/development.md b/docs/plugins/development.md
index 67abeb8d5..71ff255cf 100644
--- a/docs/plugins/development.md
+++ b/docs/plugins/development.md
@@ -106,6 +106,7 @@ class AnimalSoundsConfig(PluginConfig):
 * `max_version`: Maximum version of NetBox with which the plugin is compatible
 * `middleware`: A list of middleware classes to append after NetBox's build-in middleware.
 * `caching_config`: Plugin-specific cache configuration
+* `menu_items`: The dotted path to the list of menu items provided by the plugin (default: `navigation.menu_items`)
 
 ### Install the Plugin for Development
 
@@ -271,24 +272,36 @@ With these three components in place, we can request `/api/plugins/animal-sounds
 
 ## Navigation Menu Items
 
-To make its views easily accessible to users, a plugin can inject items in NetBox's navigation menu. This is done by instantiating NetBox's `PluginNavMenuLink` class. Each instance of this class appears in the navigation menu under the header for its plugin. We'll create a link in the file `navigation.py`:
+To make its views easily accessible to users, a plugin can inject items in NetBox's navigation menu. Menu items are added by defining a list of PluginNavMenuLink instances. By default, this should be a variable named `menu_items` in the file `navigations.py`. An example is shown below.
 
 ```python
-from extras.plugins import PluginNavMenuLink
+from extras.plugins import PluginNavMenuButton, PluginNavMenuLink
+from utilities.choices import ButtonColorChoices
 
-class RandomSoundLink(PluginNavMenuLink):
-    link = 'plugins:netbox_animal_sounds:random_sound'
-    link_text = 'Random sound'
+menu_items = (
+    PluginNavMenuLink(
+        link='plugins:netbox_animal_sounds:random_sound',
+        link_text='Random sound',
+        buttons=(
+            PluginNavMenuButton('home', 'Button A', 'fa-info', ButtonColorChoices.BLUE),
+            PluginNavMenuButton('home', 'Button B', 'fa-warning', ButtonColorChoices.GREEN),
+        )
+    ),
+)
 ```
 
-Once we have our menu item defined, we need to register it in `signals.py`:
+A `PluginNavMenuLink` has the following attributes:
 
-```python
-from django.dispatch import receiver
-from extras.plugins.signals import register_nav_menu_link_classes
-from .navigation import RandomSoundLink
+* `link` - The name of the URL path to which this menu item links
+* `link_text` - The text presented to the user
+* `permission` - The name of the permission required to display this link (optional)
+* `buttons` - An iterable of PluginNavMenuButton instances to display (optional)
 
-@receiver(register_nav_menu_link_classes)
-def nav_menu_link_classes(**kwargs):
-    return [RandomSoundLink]
-```
+
+A `PluginNavMenuButton` has the following attributes:
+
+* `link` - The name of the URL path to which this menu item links
+* `title` - The tooltip text (displayed when the mouse hovers over the button)
+* `color` - Button color (one of the choices provided by `ButtonColorChoices`)
+* `icon_class` - Button icon CSS class
+* `permission` - The name of the permission required to display this button (optional)
diff --git a/netbox/extras/plugins/__init__.py b/netbox/extras/plugins/__init__.py
index 40db432e3..a0ebec7e9 100644
--- a/netbox/extras/plugins/__init__.py
+++ b/netbox/extras/plugins/__init__.py
@@ -170,7 +170,7 @@ class PluginNavMenuLink:
     def __init__(self, link, link_text, permission=None, buttons=None):
         self.link = link
         self.link_text = link_text
-        self.link_permission = permission
+        self.permission = permission
         if buttons is None:
             self.buttons = []
         else:
diff --git a/netbox/templates/inc/plugin_nav_menu_items.html b/netbox/templates/inc/plugin_nav_menu_items.html
index b79044273..55aab84c1 100644
--- a/netbox/templates/inc/plugin_nav_menu_items.html
+++ b/netbox/templates/inc/plugin_nav_menu_items.html
@@ -4,8 +4,8 @@
         {% for section_name, link_items in plugin_nav_menu_links.items %}
             <li class="dropdown-header">{{ section_name }}</li>
             {% for link_item in link_items %}
-                {% if link_item.link_permission %}
-                    <li{% if not link_item.link_permission in perms %} class="disabled"{% endif %}>
+                {% if link_item.permission %}
+                    <li{% if not link_item.permission in perms %} class="disabled"{% endif %}>
                 {% else %}
                     <li>
                 {% endif %}