2022-01-28 15:48:15 -05:00
# Forms
2022-01-31 14:10:13 -05:00
## Form Classes
2022-03-08 14:15:22 -05:00
NetBox provides several base form classes for use by plugins.
2022-01-28 15:48:15 -05:00
2022-11-15 12:24:57 -05:00
| Form Class | Purpose |
|----------------------------|--------------------------------------|
| `NetBoxModelForm` | Create/edit individual objects |
| `NetBoxModelImportForm` | Bulk import objects from CSV data |
| `NetBoxModelBulkEditForm` | Edit multiple objects simultaneously |
2022-03-23 12:12:31 -04:00
| `NetBoxModelFilterSetForm` | Filter objects within a list view |
2022-01-28 15:48:15 -05:00
2022-03-23 12:12:31 -04:00
### `NetBoxModelForm`
2022-01-31 14:10:13 -05:00
2022-03-23 12:12:31 -04:00
This is the base form for creating and editing NetBox models. It extends Django's ModelForm to add support for tags and custom fields.
| Attribute | Description |
|-------------|-------------------------------------------------------------|
| `fieldsets` | A tuple of two-tuples defining the form's layout (optional) |
**Example**
```python
from dcim.models import Site
from netbox.forms import NetBoxModelForm
from utilities.forms.fields import CommentField, DynamicModelChoiceField
from .models import MyModel
class MyModelForm(NetBoxModelForm):
site = DynamicModelChoiceField(
queryset=Site.objects.all()
)
comments = CommentField()
fieldsets = (
('Model Stuff', ('name', 'status', 'site', 'tags')),
('Tenancy', ('tenant_group', 'tenant')),
)
class Meta:
model = MyModel
fields = ('name', 'status', 'site', 'comments', 'tags')
```
!!! tip "Comment fields"
If your form has a `comments` field, there's no need to list it; this will always appear last on the page.
2022-11-15 12:24:57 -05:00
### `NetBoxModelImportForm`
2022-03-23 12:12:31 -04:00
2022-11-15 12:24:57 -05:00
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.
2022-03-23 12:12:31 -04:00
**Example**
```python
from dcim.models import Site
2022-11-15 12:24:57 -05:00
from netbox.forms import NetBoxModelImportForm
2022-03-23 12:12:31 -04:00
from utilities.forms import CSVModelChoiceField
from .models import MyModel
2022-11-15 12:24:57 -05:00
class MyModelImportForm(NetBoxModelImportForm):
2022-03-23 12:12:31 -04:00
site = CSVModelChoiceField(
queryset=Site.objects.all(),
to_field_name='name',
help_text='Assigned site'
)
class Meta:
model = MyModel
fields = ('name', 'status', 'site', 'comments')
```
### `NetBoxModelBulkEditForm`
This form facilitates editing multiple objects in bulk. Unlike a model form, this form does not have a child `Meta` class, and must explicitly define each field. All fields in a bulk edit form are generally declared with `required=False` .
| Attribute | Description |
|-------------------|---------------------------------------------------------------------------------------------|
| `model` | The model of object being edited |
| `fieldsets` | A tuple of two-tuples defining the form's layout (optional) |
| `nullable_fields` | A tuple of fields which can be nullified (set to empty) using the bulk edit form (optional) |
**Example**
```python
from django import forms
from dcim.models import Site
2022-11-15 12:24:57 -05:00
from netbox.forms import NetBoxModelImportForm
2022-03-23 12:12:31 -04:00
from utilities.forms import CommentField, DynamicModelChoiceField
from .models import MyModel, MyModelStatusChoices
2022-11-15 12:24:57 -05:00
class MyModelEditForm(NetBoxModelImportForm):
2022-03-23 12:12:31 -04:00
name = forms.CharField(
required=False
)
status = forms.ChoiceField(
choices=MyModelStatusChoices,
required=False
)
site = DynamicModelChoiceField(
queryset=Site.objects.all(),
required=False
)
comments = CommentField()
model = MyModel
fieldsets = (
('Model Stuff', ('name', 'status', 'site')),
)
nullable_fields = ('site', 'comments')
```
### `NetBoxModelFilterSetForm`
This form class is used to render a form expressly for filtering a list of objects. Its fields should correspond to filters defined on the model's filter set.
| Attribute | Description |
|-------------------|-------------------------------------------------------------|
| `model` | The model of object being edited |
| `fieldsets` | A tuple of two-tuples defining the form's layout (optional) |
**Example**
```python
from dcim.models import Site
from netbox.forms import NetBoxModelFilterSetForm
from utilities.forms import DynamicModelMultipleChoiceField, MultipleChoiceField
from .models import MyModel, MyModelStatusChoices
class MyModelFilterForm(NetBoxModelFilterSetForm):
site_id = DynamicModelMultipleChoiceField(
queryset=Site.objects.all(),
required=False
)
status = MultipleChoiceField(
choices=MyModelStatusChoices,
required=False
)
model = MyModel
```
2022-01-31 14:10:13 -05:00
## General Purpose Fields
2022-03-23 12:12:31 -04:00
In addition to the [form fields provided by Django ](https://docs.djangoproject.com/en/stable/ref/forms/fields/ ), NetBox provides several field classes for use within forms to handle specific types of data. These can be imported from `utilities.forms.fields` and are documented below.
2022-01-31 14:10:13 -05:00
::: utilities.forms.ColorField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.CommentField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.JSONField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.MACAddressField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.SlugField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
2022-03-21 15:08:05 -04:00
## Choice Fields
2023-02-16 10:25:51 -05:00
!!! warning "Obsolete Fields"
NetBox's custom `ChoiceField` and `MultipleChoiceField` classes are no longer necessary thanks to improvements made to the user interface. Django's native form fields can be used instead. These custom field classes will be removed in NetBox v3.6.
2022-03-21 15:08:05 -04:00
::: utilities.forms.ChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-03-21 15:08:05 -04:00
members: false
::: utilities.forms.MultipleChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-03-21 15:08:05 -04:00
members: false
2022-01-31 14:10:13 -05:00
## Dynamic Object Fields
::: utilities.forms.DynamicModelChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.DynamicModelMultipleChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
## Content Type Fields
::: utilities.forms.ContentTypeChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.ContentTypeMultipleChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
## CSV Import Fields
::: utilities.forms.CSVChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.CSVMultipleChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.CSVModelChoiceField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.CSVContentTypeField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false
::: utilities.forms.CSVMultipleContentTypeField
2022-10-12 05:36:02 -07:00
options:
2022-01-31 14:10:13 -05:00
members: false