Merge pull request #8428 from netbox-community/8334-plugins-views

Closes #8334: Formally support use of generic views by plugins

docs/plugins/development/generic-views.md

@@ -0,0 +1,96 @@
+# Generic Views
+
+NetBox provides several generic view classes to facilitate common operations, such as creating, viewing, modifying, and deleting objects. Plugins can subclass these views for their own use.
+
+| View Class | Description |
+|------------|-------------|
+| `ObjectView` | View a single object |
+| `ObjectEditView` | Create or edit a single object |
+| `ObjectDeleteView` | Delete a single object |
+| `ObjectListView` | View a list of objects |
+| `BulkImportView` | Import a set of new objects |
+| `BulkEditView` | Edit multiple objects |
+| `BulkDeleteView` | Delete multiple objects |
+
+!!! note
+    Please note that only the classes which appear in this documentation are currently supported. Although other classes may be present within the `views.generic` module, they are not yet supported for use by plugins.
+
+### Example Usage
+
+```python
+# views.py
+from netbox.views.generic import ObjectEditView
+from .models import Thing
+
+class ThingEditView(ObjectEditView):
+    queryset = Thing.objects.all()
+    template_name = 'myplugin/thing.html'
+    ...
+```
+
+## Object Views
+
+Below is the class definition for NetBox's BaseObjectView. The attributes and methods defined here are available on all generic views which handle a single object.
+
+::: netbox.views.generic.base.BaseObjectView
+    rendering:
+      show_source: false
+
+::: netbox.views.generic.ObjectView
+    selection:
+      members:
+        - get_object
+        - get_template_name
+    rendering:
+      show_source: false
+
+::: netbox.views.generic.ObjectEditView
+    selection:
+      members:
+        - get_object
+        - alter_object
+    rendering:
+      show_source: false
+
+::: netbox.views.generic.ObjectDeleteView
+    selection:
+      members:
+        - get_object
+    rendering:
+      show_source: false
+
+## Multi-Object Views
+
+Below is the class definition for NetBox's BaseMultiObjectView. The attributes and methods defined here are available on all generic views which deal with multiple objects.
+
+::: netbox.views.generic.base.BaseMultiObjectView
+    rendering:
+      show_source: false
+
+::: netbox.views.generic.ObjectListView
+    selection:
+      members:
+        - get_table
+        - export_table
+        - export_template
+    rendering:
+      show_source: false
+
+::: netbox.views.generic.BulkImportView
+    selection:
+      members: false
+    rendering:
+      show_source: false
+
+::: netbox.views.generic.BulkEditView
+    selection:
+      members: false
+    rendering:
+      show_source: false
+
+::: netbox.views.generic.BulkDeleteView
+    selection:
+      members:
+        - get_form
+    rendering:
+      show_source: false

mkdocs.yml

@@ -28,6 +28,7 @@ plugins:
             - django.setup()
           rendering:
             heading_level: 3
+            members_order: source
             show_root_heading: true
             show_root_full_path: false
             show_root_toc_entry: false
@@ -102,6 +103,7 @@ nav:
         - Developing Plugins:
             - Introduction: 'plugins/development/index.md'
             - Model Features: 'plugins/development/model-features.md'
+            - Generic Views: 'plugins/development/generic-views.md'
         - Developing Plugins (Old): 'plugins/development.md'
     - Administration:
         - Authentication: 'administration/authentication.md'

netbox/netbox/views/generic/base.py

@@ -0,0 +1,58 @@
+from django.shortcuts import get_object_or_404
+from django.views.generic import View
+
+from utilities.views import ObjectPermissionRequiredMixin
+
+
+class BaseObjectView(ObjectPermissionRequiredMixin, View):
+    """
+    Base view class for reusable generic views.
+
+    Attributes:
+        queryset: Django QuerySet from which the object(s) will be fetched
+        template_name: The name of the HTML template file to render
+    """
+    queryset = None
+    template_name = None
+
+    def get_object(self, **kwargs):
+        """
+        Return the object being viewed or modified. The object is identified by an arbitrary set of keyword arguments
+        gleaned from the URL, which are passed to `get_object_or_404()`. (Typically, only a primary key is needed.)
+
+        If no matching object is found, return a 404 response.
+        """
+        return get_object_or_404(self.queryset, **kwargs)
+
+    def get_extra_context(self, request, instance):
+        """
+        Return any additional context data to include when rendering the template.
+
+        Args:
+            request: The current request
+            instance: The object being viewed
+        """
+        return {}
+
+
+class BaseMultiObjectView(ObjectPermissionRequiredMixin, View):
+    """
+    Base view class for reusable generic views.
+
+    Attributes:
+        queryset: Django QuerySet from which the object(s) will be fetched
+        table: The django-tables2 Table class used to render the objects list
+        template_name: The name of the HTML template file to render
+    """
+    queryset = None
+    table = None
+    template_name = None
+
+    def get_extra_context(self, request):
+        """
+        Return any additional context data to include when rendering the template.
+
+        Args:
+            request: The current request
+        """
+        return {}