|
| 1 | +# Adding Models |
| 2 | + |
| 3 | +## 1. Define the model class |
| 4 | + |
| 5 | +Models within each app are stored in either `models.py` or within a submodule under the `models/` directory. When creating a model, be sure to subclass the [appropriate base model](models.md) from `netbox.models`. This will typically be PrimaryModel or OrganizationalModel. Remember to add the model class to the `__all__` listing for the module. |
| 6 | + |
| 7 | +Each model should define, at a minimum: |
| 8 | + |
| 9 | +* A `__str__()` method returning a user-friendly string representation of the instance |
| 10 | +* A `get_absolute_url()` method returning an instance's direct URL (using `reverse()`) |
| 11 | +* A `Meta` class specifying a deterministic ordering (if ordered by fields other than the primary ID) |
| 12 | + |
| 13 | +## 2. Define field choices |
| 14 | + |
| 15 | +If the model has one or more fields with static choices, define those choices in `choices.py` by subclassing `utilities.choices.ChoiceSet`. |
| 16 | + |
| 17 | +## 3. Generate database migrations |
| 18 | + |
| 19 | +Once your model definition is complete, generate database migrations by running `manage.py -n $NAME --no-header`. Always specify a short unique name when generating migrations. |
| 20 | + |
| 21 | +!!! info |
| 22 | + Set `DEVELOPER = True` in your NetBox configuration to enable the creation of new migrations. |
| 23 | + |
| 24 | +## 4. Add all standard views |
| 25 | + |
| 26 | +Most models will need view classes created in `views.py` to serve the following operations: |
| 27 | + |
| 28 | +* List view |
| 29 | +* Detail view |
| 30 | +* Edit view |
| 31 | +* Delete view |
| 32 | +* Bulk import |
| 33 | +* Bulk edit |
| 34 | +* Bulk delete |
| 35 | + |
| 36 | +## 5. Add URL paths |
| 37 | + |
| 38 | +Add the relevant URL path for each view created in the previous step to `urls.py`. |
| 39 | + |
| 40 | +## 6. Create the FilterSet |
| 41 | + |
| 42 | +Each model should have a corresponding FilterSet class defined. This is used to filter UI and API queries. Subclass the appropriate class from `netbox.filtersets` that matches the model's parent class. |
| 43 | + |
| 44 | +Every model FilterSet should define a `q` filter to support general search queries. |
| 45 | + |
| 46 | +## 7. Create the table |
| 47 | + |
| 48 | +Create a table class for the model in `tables.py` by subclassing `utilities.tables.BaseTable`. Under the table's `Meta` class, be sure to list both the fields and default columns. |
| 49 | + |
| 50 | +## 8. Create the object template |
| 51 | + |
| 52 | +Create the HTML template for the object view. (The other views each typically employ a generic template.) This template should extend `generic/object.html`. |
| 53 | + |
| 54 | +## 9. Add the model to the navigation menu |
| 55 | + |
| 56 | +For NetBox releases prior to v3.0, add the relevant link(s) to the navigation menu template. For later releases, add the relevant items in `netbox/netbox/navigation_menu.py`. |
| 57 | + |
| 58 | +## 10. REST API components |
| 59 | + |
| 60 | +Create the following for each model: |
| 61 | + |
| 62 | +* Detailed (full) model serializer in `api/serializers.py` |
| 63 | +* Nested serializer in `api/nested_serializers.py` |
| 64 | +* API view in `api/views.py` |
| 65 | +* Endpoint route in `api/urls.py` |
| 66 | + |
| 67 | +## 11. GraphQL API components (v3.0+) |
| 68 | + |
| 69 | +Create a Graphene object type for the model in `graphql/types.py` by subclassing the appropriate class from `netbox.graphql.types`. |
| 70 | + |
| 71 | +Also extend the schema class defined in `graphql/schema.py` with the individual object and object list fields per the established convention. |
| 72 | + |
| 73 | +## 12. Add tests |
| 74 | + |
| 75 | +Add tests for the following: |
| 76 | + |
| 77 | +* UI views |
| 78 | +* API views |
| 79 | +* Filter sets |
| 80 | + |
| 81 | +## 13. Documentation |
| 82 | + |
| 83 | +Create a new documentation page for the model in `docs/models/<app_label>/<model_name>.md`. Include this file under the "features" documentation where appropriate. |
| 84 | + |
| 85 | +Also add your model to the index in `docs/development/models.md`. |
0 commit comments