diff --git a/docs/plugins/development/model-features.md b/docs/plugins/development/model-features.md index 83f9b4205..7b70709d1 100644 --- a/docs/plugins/development/model-features.md +++ b/docs/plugins/development/model-features.md @@ -1,23 +1,51 @@ # Model Features -Plugin models can leverage certain NetBox features by inheriting from designated Python classes (documented below), defined in `netbox.models.features`. These classes perform two crucial functions: +## Enabling NetBox Features -1. Apply any fields, methods, or attributes necessary to the operation of the feature -2. Register the model with NetBox as utilizing the feature +Plugin models can leverage certain NetBox features by inheriting from NetBox's `BaseModel` class. This class extends the plugin model to enable numerous feature, including: -For example, to enable support for tags in a plugin model, it should inherit from `TagsMixin`: +* Custom fields +* Custom links +* Custom validation +* Export templates +* Job results +* Journaling +* Tags +* Webhooks + +This class performs two crucial functions: + +1. Apply any fields, methods, or attributes necessary to the operation of these features +2. Register the model with NetBox as utilizing these feature + +Simply subclass BaseModel when defining a model in your plugin: ```python # models.py -from django.db.models import models -from netbox.models.features import TagsMixin +from netbox.models import BaseModel -class MyModel(TagsMixin, models.Model): +class MyModel(BaseModel): foo = models.CharField() ... ``` -This will ensure that TaggableManager is applied to the model, and that the model is registered with NetBox as taggable. +## Enabling Features Individually + +If you prefer instead to enable only a subset of these features for a plugin model, NetBox provides a discrete "mix-in" class for each feature. You can subclass each of these individually when defining your model. (You will also need to inherit from Django's built-in `Model` class.) + +```python +# models.py +from django.db.models import models +from netbox.models.features import ExportTemplatesMixin, TagsMixin + +class MyModel(ExportTemplatesMixin, TagsMixin, models.Model): + foo = models.CharField() + ... +``` + +The example above will enable export templates and tags, but no other NetBox features. A complete list of available feature mixins is included below. (Inheriting all the available mixins is essentially the same as subclassing `BaseModel`.) + +## Feature Mixins Reference !!! note Please note that only the classes which appear in this documentation are currently supported. Although other classes may be present within the `features` module, they are not yet supported for use by plugins. @@ -26,6 +54,8 @@ This will ensure that TaggableManager is applied to the model, and that the mode ::: netbox.models.features.CustomFieldsMixin +::: netbox.models.features.CustomValidationMixin + ::: netbox.models.features.ExportTemplatesMixin ::: netbox.models.features.JobResultsMixin diff --git a/mkdocs.yml b/mkdocs.yml index 4fdf22f97..585e6d76f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,6 +27,7 @@ plugins: - os.environ.setdefault("DJANGO_SETTINGS_MODULE", "netbox.settings") - django.setup() rendering: + heading_level: 3 show_root_heading: true show_root_full_path: false show_root_toc_entry: false diff --git a/netbox/netbox/models/__init__.py b/netbox/netbox/models/__init__.py index e38412221..2db2e2602 100644 --- a/netbox/netbox/models/__init__.py +++ b/netbox/netbox/models/__init__.py @@ -22,6 +22,7 @@ __all__ = ( class BaseModel( CustomFieldsMixin, CustomLinksMixin, + CustomValidationMixin, ExportTemplatesMixin, JournalingMixin, TagsMixin, @@ -53,7 +54,7 @@ class ChangeLoggedModel(ChangeLoggingMixin, CustomValidationMixin, BigIDModel): abstract = True -class PrimaryModel(BaseModel, ChangeLoggingMixin, CustomValidationMixin, BigIDModel): +class PrimaryModel(BaseModel, ChangeLoggingMixin, BigIDModel): """ Primary models represent real objects within the infrastructure being modeled. """ @@ -63,7 +64,7 @@ class PrimaryModel(BaseModel, ChangeLoggingMixin, CustomValidationMixin, BigIDMo abstract = True -class NestedGroupModel(BaseModel, ChangeLoggingMixin, CustomValidationMixin, BigIDModel, MPTTModel): +class NestedGroupModel(BaseModel, ChangeLoggingMixin, BigIDModel, MPTTModel): """ Base model for objects which are used to form a hierarchy (regions, locations, etc.). These models nest recursively using MPTT. Within each parent, each child instance must have a unique name. @@ -105,7 +106,7 @@ class NestedGroupModel(BaseModel, ChangeLoggingMixin, CustomValidationMixin, Big }) -class OrganizationalModel(BaseModel, ChangeLoggingMixin, CustomValidationMixin, BigIDModel): +class OrganizationalModel(BaseModel, ChangeLoggingMixin, BigIDModel): """ Organizational models are those which are used solely to categorize and qualify other objects, and do not convey any real information about the infrastructure being modeled (for example, functional device roles). Organizational diff --git a/netbox/netbox/models/features.py b/netbox/netbox/models/features.py index 7865e3c8a..ce3980459 100644 --- a/netbox/netbox/models/features.py +++ b/netbox/netbox/models/features.py @@ -155,7 +155,7 @@ class CustomLinksMixin(models.Model): class CustomValidationMixin(models.Model): """ - Enables user-configured validation rules for built-in models by extending the clean() method. + Enables user-configured validation rules for models. """ class Meta: abstract = True