mirror of
https://github.com/netbox-community/netbox.git
synced 2026-01-12 23:02:17 -06:00
Compare commits
6 Commits
v4.5-beta1
...
c357abd1ce
| Author | SHA1 | Date | |
|---|---|---|---|
|
c357abd1ce | ||
|
|
3317169329 | ||
|
|
6dc00206a4 | ||
|
|
16c8dffe7c | ||
|
|
1715ce6cdd | ||
|
|
6d777a20ad |
@@ -32,6 +32,14 @@ class MyFilterSet(NetBoxModelFilterSet):
|
||||
fields = ('some', 'other', 'fields')
|
||||
```
|
||||
|
||||
In addition to the base NetBoxModelFilterSet class, the following filterset classes are also available for subclasses of standard base models.
|
||||
|
||||
| Model Class | FilterSet Class |
|
||||
|-----------------------|--------------------------------------------------|
|
||||
| `PrimaryModel` | `netbox.filtersets.PrimaryModelFilterSet` |
|
||||
| `OrganizationalModel` | `netbox.filtersets.OrganizationalModelFilterSet` |
|
||||
| `NestedGroupModel` | `netbox.filtersets.NestedGroupModelFilterSet` |
|
||||
|
||||
### Declaring Filter Sets
|
||||
|
||||
To utilize a filter set in a subclass of one of NetBox's generic views (such as `ObjectListView` or `BulkEditView`), define the `filterset` attribute on the view class:
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Form Classes
|
||||
|
||||
NetBox provides several base form classes for use by plugins.
|
||||
NetBox provides several base form classes for use by plugins. Additional form classes are also available for other standard base model classes (PrimaryModel, OrganizationalModel, and NestedGroupModel).
|
||||
|
||||
| Form Class | Purpose |
|
||||
|----------------------------|--------------------------------------|
|
||||
@@ -19,7 +19,17 @@ This is the base form for creating and editing NetBox models. It extends Django'
|
||||
|-------------|---------------------------------------------------------------------------------------|
|
||||
| `fieldsets` | A tuple of `FieldSet` instances which control how form fields are rendered (optional) |
|
||||
|
||||
**Example**
|
||||
#### Subclasses
|
||||
|
||||
The corresponding model-specific subclasses of `NetBoxModelForm` are documented below.
|
||||
|
||||
| Model Class | Form Class |
|
||||
|-----------------------|---------------------------|
|
||||
| `PrimaryModel` | `PrimaryModelForm` |
|
||||
| `OrganizationalModel` | `OrganizationalModelForm` |
|
||||
| `NestedGroupModel` | `NestedGroupModelForm` |
|
||||
|
||||
#### Example
|
||||
|
||||
```python
|
||||
from django.utils.translation import gettext_lazy as _
|
||||
@@ -49,9 +59,19 @@ class MyModelForm(NetBoxModelForm):
|
||||
|
||||
### `NetBoxModelImportForm`
|
||||
|
||||
This form facilitates the bulk import of new objects from CSV, JSON, or YAML data. As with model forms, you'll need to declare a `Meta` subclass specifying the associated `model` and `fields`. NetBox also provides several form fields suitable for import various types of CSV data, listed below.
|
||||
This form facilitates the bulk import of new objects from CSV, JSON, or YAML data. As with model forms, you'll need to declare a `Meta` subclass specifying the associated `model` and `fields`. NetBox also provides several form fields suitable for importing various types of CSV data, listed [below](#csv-import-fields).
|
||||
|
||||
**Example**
|
||||
#### Subclasses
|
||||
|
||||
The corresponding model-specific subclasses of `NetBoxModelImportForm` are documented below.
|
||||
|
||||
| Model Class | Form Class |
|
||||
|-----------------------|---------------------------------|
|
||||
| `PrimaryModel` | `PrimaryModelImportForm` |
|
||||
| `OrganizationalModel` | `OrganizationalModelImportForm` |
|
||||
| `NestedGroupModel` | `NestedGroupModelImportForm` |
|
||||
|
||||
#### Example
|
||||
|
||||
```python
|
||||
from django.utils.translation import gettext_lazy as _
|
||||
@@ -83,7 +103,17 @@ This form facilitates editing multiple objects in bulk. Unlike a model form, thi
|
||||
| `fieldsets` | A tuple of `FieldSet` instances which control how form fields are rendered (optional) |
|
||||
| `nullable_fields` | A tuple of fields which can be nullified (set to empty) using the bulk edit form (optional) |
|
||||
|
||||
**Example**
|
||||
#### Subclasses
|
||||
|
||||
The corresponding model-specific subclasses of `NetBoxModelBulkEditForm` are documented below.
|
||||
|
||||
| Model Class | Form Class |
|
||||
|-----------------------|-----------------------------------|
|
||||
| `PrimaryModel` | `PrimaryModelBulkEditForm` |
|
||||
| `OrganizationalModel` | `OrganizationalModelBulkEditForm` |
|
||||
| `NestedGroupModel` | `NestedGroupModelBulkEditForm` |
|
||||
|
||||
#### Example
|
||||
|
||||
```python
|
||||
from django import forms
|
||||
@@ -125,7 +155,17 @@ This form class is used to render a form expressly for filtering a list of objec
|
||||
| `model` | The model of object being edited |
|
||||
| `fieldsets` | A tuple of `FieldSet` instances which control how form fields are rendered (optional) |
|
||||
|
||||
**Example**
|
||||
#### Subclasses
|
||||
|
||||
The corresponding model-specific subclasses of `NetBoxModelFilterSetForm` are documented below.
|
||||
|
||||
| Model Class | Form Class |
|
||||
|-----------------------|------------------------------------|
|
||||
| `PrimaryModel` | `PrimaryModelFilterSetForm` |
|
||||
| `OrganizationalModel` | `OrganizationalModelFilterSetForm` |
|
||||
| `NestedGroupModel` | `NestedGroupModelFilterSetForm` |
|
||||
|
||||
#### Example
|
||||
|
||||
```python
|
||||
from dcim.models import Site
|
||||
|
||||
@@ -46,3 +46,19 @@ NetBox provides two object type classes for use by plugins.
|
||||
::: netbox.graphql.types.NetBoxObjectType
|
||||
options:
|
||||
members: false
|
||||
|
||||
## GraphQL Filters
|
||||
|
||||
NetBox provides a base filter class for use by plugins which employ subclasseses of `NetBoxModel`.
|
||||
|
||||
::: netbox.graphql.filters.NetBoxModelFilter
|
||||
options:
|
||||
members: false
|
||||
|
||||
Additionally, the following filter classes are available for subclasses of standard base models.
|
||||
|
||||
| Model Class | FilterSet Class |
|
||||
|-----------------------|----------------------------------------------------|
|
||||
| `PrimaryModel` | `netbox.graphql.filters.PrimaryModelFilter` |
|
||||
| `OrganizationalModel` | `netbox.graphql.filters.OrganizationalModelFilter` |
|
||||
| `NestedGroupModel` | `netbox.graphql.filters.NestedGroupModelFilter` |
|
||||
|
||||
@@ -67,6 +67,46 @@ class MyModel(ExportTemplatesMixin, TagsMixin, models.Model):
|
||||
...
|
||||
```
|
||||
|
||||
### Additional Models
|
||||
|
||||
In addition to the base NetBoxModel class, the following additional classes are provided for convenience.
|
||||
|
||||
!!! info "These model classes were added to the plugins API in NetBox v4.5."
|
||||
|
||||
#### PrimaryModel
|
||||
|
||||
PrimaryModel is the go-to class for most object types. It extends NetBoxModel with `description` and `comments` fields, and it introduces support for ownership assignment.
|
||||
|
||||
| Field | Required | Unique | Description |
|
||||
|---------------|----------|--------|---------------------------------------------|
|
||||
| `owner` | No | No | The object's owner |
|
||||
| `description` | No | No | A human-friendly description for the object |
|
||||
| `comments` | No | No | General comments |
|
||||
|
||||
#### OrganizationalModel
|
||||
|
||||
OrganizationalModel is used by object types whose function is primarily the organization of other objects.
|
||||
|
||||
| Field | Required | Unique | Description |
|
||||
|---------------|----------|--------|---------------------------------------------|
|
||||
| `name` | Yes | Yes | The name of the object |
|
||||
| `slug` | Yes | Yes | A unique URL-friendly identifier |
|
||||
| `owner` | No | No | The object's owner |
|
||||
| `description` | No | No | A human-friendly description for the object |
|
||||
|
||||
#### NestedGroupModel
|
||||
|
||||
NestedGroupModel is used for objects which arrange into a recursive hierarchy (like regions and locations) via its self-referential `parent` foreign key.
|
||||
|
||||
| Field | Required | Unique | Description |
|
||||
|---------------|----------|--------|-----------------------------------------------------------------|
|
||||
| `name` | Yes | Yes | The name of the object |
|
||||
| `slug` | Yes | Yes | A unique URL-friendly identifier |
|
||||
| `parent` | No | No | The object (of the same type) under which this object is nested |
|
||||
| `owner` | No | No | The object's owner |
|
||||
| `description` | No | No | A human-friendly description for the object |
|
||||
| `comments` | No | No | General comments |
|
||||
|
||||
## Database Migrations
|
||||
|
||||
Once you have completed defining the model(s) for your plugin, you'll need to create the database schema migrations. A migration file is essentially a set of instructions for manipulating the PostgreSQL database to support your new model, or to alter existing models. Creating migrations can usually be done automatically using Django's `makemigrations` management command. (Ensure that your plugin has been installed and enabled first, otherwise it won't be found.)
|
||||
|
||||
@@ -27,6 +27,14 @@ Serializers are responsible for converting Python objects to JSON data suitable
|
||||
|
||||
The default nested representation of an object is defined by the `brief_fields` attributes under the serializer's `Meta` class. (Older versions of NetBox required the definition of a separate nested serializer.)
|
||||
|
||||
In addition to the base NetBoxModelSerializer class, the following serializer classes are also available for subclasses of standard base models.
|
||||
|
||||
| Model Class | Serializer Class |
|
||||
|-----------------------|--------------------------------------------------------|
|
||||
| `PrimaryModel` | `netbox.api.serializers.PrimaryModelSerializer` |
|
||||
| `OrganizationalModel` | `netbox.api.serializers.OrganizationalModelSerializer` |
|
||||
| `NestedGroupModel` | `netbox.api.serializers.NestedGroupModelSerializer` |
|
||||
|
||||
#### Example
|
||||
|
||||
To create a serializer for a plugin model, subclass `NetBoxModelSerializer` in `api/serializers.py`. Specify the model class and the fields to include within the serializer's `Meta` class.
|
||||
|
||||
@@ -36,6 +36,14 @@ class MyModelTable(NetBoxTable):
|
||||
default_columns = ('pk', 'name', ...)
|
||||
```
|
||||
|
||||
In addition to the base NetBoxTable class, the following table classes are also available for subclasses of standard base models.
|
||||
|
||||
| Model Class | Serializer Class |
|
||||
|-----------------------|------------------------------------------|
|
||||
| `PrimaryModel` | `netbox.tables.PrimaryModelTable` |
|
||||
| `OrganizationalModel` | `netbox.tables.OrganizationalModelTable` |
|
||||
| `NestedGroupModel` | `netbox.tables.NestedGroupModelTable` |
|
||||
|
||||
### Table Configuration
|
||||
|
||||
The NetBoxTable class features dynamic configuration to allow users to change their column display and ordering preferences. To configure a table for a specific request, simply call its `configure()` method and pass the current HTTPRequest object. For example:
|
||||
|
||||
@@ -1,111 +0,0 @@
|
||||
## v4.5.0 (FUTURE)
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
* Python 3.10 and 3.11 are no longer supported. NetBox now requires Python 3.12 or later.
|
||||
* GraphQL API queries which filter by object IDs or enums must now specify a filter lookup similar to other fields. (For example, `id: 123` becomes `id: {exact: 123 }`.)
|
||||
* Rendering a device or virtual machine configuration is now restricted to users with the `render_config` permission for the applicable object type.
|
||||
* Retrieval of API token plaintexts is no longer supported. The `ALLOW_TOKEN_RETRIEVAL` config parameter has been removed.
|
||||
* The owner of an API token can no longer be changed once it has been created.
|
||||
* Config contexts now apply to all child platforms of a parent platform.
|
||||
* The `/api/extras/object-types/` REST API endpoint has been removed. (Use `/api/core/object-types/` instead.)
|
||||
* The `/api/dcim/cable-terminations/` REST API endpoint is now read-only. Cable terminations must be set on cables directly.
|
||||
* The UI view dedicated to swaping A/Z circuit terminations has been removed.
|
||||
* Webhooks no longer specify a `model` in payload data. (Reference `object_type` instead, which includes the parent app label.)
|
||||
* The obsolete module `core.models.contenttypes` has been removed (replaced in v4.4 by `core.models.object_types`).
|
||||
* The `load_yaml()` and `load_json()` utility methods have been removed from the base class for custom scripts.
|
||||
* The experimental HTMX navigation feature has been removed.
|
||||
* The obsolete field `is_staff` has been removed from the `User` model.
|
||||
|
||||
### New Features
|
||||
|
||||
#### Lookup Modifiers in Filter Forms ([#7604](https://github.com/netbox-community/netbox/issues/7604))
|
||||
|
||||
#### Improved API Authentication Tokens ([#20210](https://github.com/netbox-community/netbox/issues/20210))
|
||||
|
||||
#### Object Ownership ([#20304](https://github.com/netbox-community/netbox/issues/20304))
|
||||
|
||||
#### Advanced Port Mappings ([#20564](https://github.com/netbox-community/netbox/issues/20564))
|
||||
|
||||
#### Cable Profiles ([#20788](https://github.com/netbox-community/netbox/issues/20788))
|
||||
|
||||
### Enhancements
|
||||
|
||||
* [#16681](https://github.com/netbox-community/netbox/issues/16681) - Introduce a `render_config` permission, which is noq required to render a device or virtual machine configuration
|
||||
* [#18658](https://github.com/netbox-community/netbox/issues/18658) - Add a `start_on_boot` choice field for virtual machines
|
||||
* [#19095](https://github.com/netbox-community/netbox/issues/19095) - Add support for Python 3.13 and 3.14
|
||||
* [#19338](https://github.com/netbox-community/netbox/issues/19338) - Enable filter lookups for object IDs and enums in GraphQL API queries
|
||||
* [#19523](https://github.com/netbox-community/netbox/issues/19523) - Cache the number of instances for device, module, and rack types, and enable filtering by these counts
|
||||
* [#20417](https://github.com/netbox-community/netbox/issues/20417) - Add an optional `color` field for device type power outlets
|
||||
* [#20476](https://github.com/netbox-community/netbox/issues/20476) - Once provisioned, the owner of an API token cannot be changed
|
||||
* [#20492](https://github.com/netbox-community/netbox/issues/20492) - Completely disabled the means to retrieve legacy API token plaintexts (removed the `ALLOW_TOKEN_RETRIEVAL` config parameter)
|
||||
* [#20639](https://github.com/netbox-community/netbox/issues/20639) - Apply config contexts to devices/VMs assigned any child platform of the parent platform
|
||||
* [#20834](https://github.com/netbox-community/netbox/issues/20834) - Add an `enabled` boolean field to API tokens
|
||||
* [#20917](https://github.com/netbox-community/netbox/issues/20917) - Include usage reference on API token views
|
||||
* [#20925](https://github.com/netbox-community/netbox/issues/20925) - Add optional `comments` field to all subclasses of `OrganizationalModel`
|
||||
* [#20936](https://github.com/netbox-community/netbox/issues/20936) - Introduce the `/api/authentication-check/` REST API endpoint for validating authentication tokens
|
||||
|
||||
### Plugins
|
||||
|
||||
* [#13182](https://github.com/netbox-community/netbox/issues/13182) - Added `PrimaryModel`, `OrganizationalModel`, and `NestedGroupModel` to the plugins API, as well as their respective base classes for various resources
|
||||
|
||||
### Other Changes
|
||||
|
||||
* [#16137](https://github.com/netbox-community/netbox/issues/16137) - Remove the obsolete boolean field `is_staff` from the `User` model
|
||||
* [#17571](https://github.com/netbox-community/netbox/issues/17571) - Remove the experimental HTMX navigation feature
|
||||
* [#17936](https://github.com/netbox-community/netbox/issues/17936) - Introduce a dedicated `GFKSerializerField` for representing generic foreign keys in API serializers
|
||||
* [#19889](https://github.com/netbox-community/netbox/issues/19889) - Drop support for Python 3.10 and 3.11
|
||||
* [#19898](https://github.com/netbox-community/netbox/issues/19898) - Remove the obsolete REST API endpoint `/api/extras/object-types/`
|
||||
* [#20088](https://github.com/netbox-community/netbox/issues/20088) - Remove the non-deterministic `model` key from webhook payload data
|
||||
* [#20095](https://github.com/netbox-community/netbox/issues/20095) - Remove the obsolete module `core.models.contenttypes`
|
||||
* [#20096](https://github.com/netbox-community/netbox/issues/20096) - Remove the `load_yaml()` and `load_json()` utility methods from the `BaseScript` class
|
||||
* [#20204](https://github.com/netbox-community/netbox/issues/20204) - Started migrating object views from custom HTML templates to declarative layouts
|
||||
* [#20617](https://github.com/netbox-community/netbox/issues/20617) - Introduce `BaseModel` as the global base class for models
|
||||
* [#20683](https://github.com/netbox-community/netbox/issues/20683) - Remove the UI view dedicated to swaping A/Z circuit terminations
|
||||
* [#20926](https://github.com/netbox-community/netbox/issues/20926) - Standardize naming of GraphQL filters
|
||||
|
||||
### REST API Changes
|
||||
|
||||
* Most objects now include an optional `owner` foreign key field.
|
||||
* The `/api/dcim/cable-terminations` endpoint is now read-only.
|
||||
* Introduced the `/api/authentication-check/` endpoint.
|
||||
* `circuits.CircuitGroup`
|
||||
* Add optional `comments` field
|
||||
* `circuits.CircuitType`
|
||||
* Add optional `comments` field
|
||||
* `circuits.VirtualCircuitType`
|
||||
* Add optional `comments` field
|
||||
* `dcim.Cable`
|
||||
* Add the optional `profile` choice field
|
||||
* `dcim.InventoryItemRole`
|
||||
* Add optional `comments` field
|
||||
* `dcim.Manufacturer`
|
||||
* Add optional `comments` field
|
||||
* `dcim.ModuleType`
|
||||
* Add read-only `module_count` integer field
|
||||
* `dcim.PowerOutletTemplate`
|
||||
* Add optional `color` field
|
||||
* `dcim.RackRole`
|
||||
* Add optional `comments` field
|
||||
* `dcim.RackType`
|
||||
* Add read-only `rack_count` integer field
|
||||
* `ipam.ASNRange`
|
||||
* Add optional `comments` field
|
||||
* `ipam.RIR`
|
||||
* Add optional `comments` field
|
||||
* `ipam.Role`
|
||||
* Add optional `comments` field
|
||||
* `ipam.VLANGroup`
|
||||
* Add optional `comments` field
|
||||
* `tenancy.ContactRole`
|
||||
* Add optional `comments` field
|
||||
* `users.Token`
|
||||
* Add `enabled` boolean field
|
||||
* `virtualization.ClusterGroup`
|
||||
* Add optional `comments` field
|
||||
* `virtualization.ClusterType`
|
||||
* Add optional `comments` field
|
||||
* `virtualization.VirtualMachine`
|
||||
* Add optional `start_on_boot` choice field
|
||||
* `vpn.TunnelGroup`
|
||||
* Add optional `comments` field
|
||||
@@ -45,34 +45,30 @@ class NetBoxModelFilterSetForm(FilterModifierMixin, CustomFieldsMixin, SavedFilt
|
||||
return customfield.to_form_field(set_initial=False, enforce_required=False, enforce_visibility=False)
|
||||
|
||||
|
||||
class PrimaryModelFilterSetForm(NetBoxModelFilterSetForm):
|
||||
class OwnerFilterMixin(forms.Form):
|
||||
owner_id = DynamicModelChoiceField(
|
||||
queryset=Owner.objects.all(),
|
||||
required=False,
|
||||
label=_('Owner'),
|
||||
)
|
||||
|
||||
|
||||
class PrimaryModelFilterSetForm(OwnerFilterMixin, NetBoxModelFilterSetForm):
|
||||
"""
|
||||
FilterSet form for models which inherit from PrimaryModel.
|
||||
"""
|
||||
owner_id = DynamicModelChoiceField(
|
||||
queryset=Owner.objects.all(),
|
||||
required=False,
|
||||
label=_('Owner'),
|
||||
)
|
||||
pass
|
||||
|
||||
|
||||
class OrganizationalModelFilterSetForm(NetBoxModelFilterSetForm):
|
||||
class OrganizationalModelFilterSetForm(OwnerFilterMixin, NetBoxModelFilterSetForm):
|
||||
"""
|
||||
FilterSet form for models which inherit from OrganizationalModel.
|
||||
"""
|
||||
owner_id = DynamicModelChoiceField(
|
||||
queryset=Owner.objects.all(),
|
||||
required=False,
|
||||
label=_('Owner'),
|
||||
)
|
||||
pass
|
||||
|
||||
|
||||
class NestedGroupModelFilterSetForm(NetBoxModelFilterSetForm):
|
||||
class NestedGroupModelFilterSetForm(OwnerFilterMixin, NetBoxModelFilterSetForm):
|
||||
"""
|
||||
FilterSet form for models which inherit from NestedGroupModel.
|
||||
"""
|
||||
owner_id = DynamicModelChoiceField(
|
||||
queryset=Owner.objects.all(),
|
||||
required=False,
|
||||
label=_('Owner'),
|
||||
)
|
||||
pass
|
||||
|
||||
Reference in New Issue
Block a user