NeoAnd/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2025-12-12 03:19:36 -06:00
Code Issues Actions 11 Packages Projects Releases Wiki Activity

Add register_filterset() to plugins documentation for filtersets

Browse Source
This commit is contained in:
Jeremy Stretch 2025-12-05 14:22:45 -05:00
parent 6c94d8d49b
commit 0319fd599a
1 changed files with 12 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/plugins/development/filtersets.md
View File

@ -6,12 +6,17 @@ Filter sets define the mechanisms available for filtering or searching through a
To support additional functionality standard to NetBox models, such as tag assignment and custom field support, the `NetBoxModelFilterSet` class is available for use by plugins. This should be used as the base filter set class for plugin models which inherit from `NetBoxModel`. Within this class, individual filters can be declared as directed by the `django-filters` documentation. An example is provided below. To support additional functionality standard to NetBox models, such as tag assignment and custom field support, the `NetBoxModelFilterSet` class is available for use by plugins. This should be used as the base filter set class for plugin models which inherit from `NetBoxModel`. Within this class, individual filters can be declared as directed by the `django-filters` documentation. An example is provided below.
!!! info "New in NetBox v4.5: FilterSet Registration"
NetBox v4.5 introduced the `register_filterset()` utility function. This enables plugins to register their filtersets to receive advanced functionality, such as the automatic attachment of field-specific lookup modifiers on the filter form. Registration is optional: Unregistered filtersets will continue to work as before, but will not receive the enhanced functionality.
```python ```python
# filtersets.py # filtersets.py
import django_filters import django_filters
from netbox.filtersets import NetBoxModelFilterSet from netbox.filtersets import NetBoxModelFilterSet
from utilities.filtersets import register_filterset
from .models import MyModel from .models import MyModel
@register_filterset
class MyFilterSet(NetBoxModelFilterSet): class MyFilterSet(NetBoxModelFilterSet):
status = django_filters.MultipleChoiceFilter( status = django_filters.MultipleChoiceFilter(
choices=( choices=(
@ -42,7 +47,7 @@ class MyModelListView(ObjectListView):
filterset = MyModelFilterSet filterset = MyModelFilterSet
``` ```
To enable a filter set on a REST API endpoint, set the `filterset_class` attribute on the API view: To enable a filter set on a REST API endpoint, set the `filterset_class` attribute on the API view:
```python ```python
# api/views.py # api/views.py
@ -62,7 +67,9 @@ The `ObjectListView` has a field called Quick Search. For Quick Search to work t
```python ```python
from django.db.models import Q from django.db.models import Q
from netbox.filtersets import NetBoxModelFilterSet from netbox.filtersets import NetBoxModelFilterSet
from utilities.filtersets import register_filterset
@register_filterset
class MyFilterSet(NetBoxModelFilterSet): class MyFilterSet(NetBoxModelFilterSet):
... ...
def search(self, queryset, name, value): def search(self, queryset, name, value):
@ -90,7 +97,9 @@ This class filters `tags` using the `slug` field. For example:
```python ```python
from django_filters import FilterSet from django_filters import FilterSet
from extras.filters import TagFilter from extras.filters import TagFilter
from utilities.filtersets import register_filterset
@register_filterset
class MyModelFilterSet(FilterSet): class MyModelFilterSet(FilterSet):
tag = TagFilter() tag = TagFilter()
``` ```
@ -106,7 +115,9 @@ This class filters `tags` using the `id` field. For example:
```python ```python
from django_filters import FilterSet from django_filters import FilterSet
from extras.filters import TagIDFilter from extras.filters import TagIDFilter
from utilities.filtersets import register_filterset
@register_filterset
class MyModelFilterSet(FilterSet): class MyModelFilterSet(FilterSet):
tag_id = TagIDFilter() tag_id = TagIDFilter()
``` ```