` path converter in the URL.
222 |
223 | We'll add a `get_absolute_url()` method for `AccessListRule` as well, adjusting the view name accordingly.
224 |
225 | ```python
226 | class AccessListRule(NetBoxModel):
227 | # ...
228 | def get_absolute_url(self):
229 | return reverse('plugins:netbox_access_lists:accesslistrule', args=[self.pk])
230 | ```
231 |
232 | ## Test the Views
233 |
234 | Now for the moment of truth: Has all our work thus far yielded functional UI views? Check that the development server is running, then open a browser and navigate to . You should see the access list list view and (if you followed in step two) a single access list named MyACL1.
235 |
236 | :blue_square: **Note:** This guide assumes that you're running the Django development server locally on port 8000. If your setup is different, you'll need to adjust the link above accordingly.
237 |
238 | 
239 |
240 | We see that our table has successfully render the `name`, `rule_count`, and `default_action` columns that we defined in step three, and the `rule_count` column shows two rules assigned as expected.
241 |
242 | If we click the "Add" button at top right, we'll be taken to the access list creation form. (Creating a new access list won'r work yet, but the form should render as seen below.)
243 |
244 | 
245 |
246 | However, if you click a link to an access list in the table, you'll be met by a `TemplateDoesNotExist` exception. This means exactly what it says: We have not yet defined a template for this view. Don't worry, that's coming up next!
247 |
248 | :blue_square: **Note:** You might notice that the "add" view for rules still doesn't work, raising a `NoReverseMatch` exception. This is because we haven't yet defined the REST API backends required to support the dynamic form fields. We'll take care of this when we build out the REST API functionality in step nine.
249 |
250 |
251 |
252 | :arrow_left: [Step 4: Forms](/tutorial/step04-forms.md) | [Step 6: Templates](/tutorial/step06-templates.md) :arrow_right:
253 |
254 |
255 |
256 |
--------------------------------------------------------------------------------
/tutorial/step06-templates.md:
--------------------------------------------------------------------------------
1 | # Step 6: Templates
2 |
3 | Templates are responsible for rendering HTML content for NetBox views. Each template exists as a file with a mix of HTML and template code. Generally speaking, each model in a NetBox plugin must have its own template. Templates may also be created or customized for other views, but the default templates NetBox provides are suitable in most cases.
4 |
5 | NetBox's rendering backend uses the [Django Template Language](https://docs.djangoproject.com/en/stable/topics/templates/) (DTL). It will immediately look very familiar if you've used [Jinja2](https://jinja2docs.readthedocs.io/en/stable/), but be aware that there are some important differences between the two. Generally, DTL is much more limited in the types of logic it can execute: Directly executing Python code, for instance, is not possible. Be sure to study the Django documentation before attempting to create any complex templates.
6 |
7 | :blue_square: **Note:** If you skipped the previous step, run `git checkout step05-views`.
8 |
9 | ## Template File Structure
10 |
11 | NetBox looks for templates within the `templates/` directory (if it exists) within the plugin root. Within this directory, create a subdirectory bearing the name of the plugin:
12 |
13 | ```bash
14 | $ cd netbox_access_lists/
15 | $ mkdir -p templates/netbox_access_lists/
16 | ```
17 |
18 | The template files will reside in this directory. Default templates are provided for all generic views except for `ObjectView`, so we'll need to create templates for our `AccessListView` and `AccessListRuleView` views.
19 |
20 | By default, each `ObjectView` subclass will look for a template bearing the name of its associated model. For instance, `AccessListView` will look for `accesslist.html`. This can be overriden by setting `template_name` on the view, but this behavior is suitable for our purposes.
21 |
22 | ## Create the AccessList Template
23 |
24 | Begin by creating the file `accesslist.html` in the plugin's template directory.
25 |
26 | ```bash
27 | $ edit templates/netbox_access_lists/accesslist.html
28 | ```
29 |
30 | Although we need to create our own template, NetBox has done much of the work for us, and provides a generic template that we can easily extend. At the top of the file, add an `extends` tag:
31 |
32 | ```
33 | {% extends 'generic/object.html' %}
34 | ```
35 |
36 | This tells the rendering engine to first load the NetBox template at `generic/object.html` and populate only the content we provide within `block` tags.
37 |
38 | Let's extend the generic template's `content` block with some information about the access list.
39 |
40 | ```
41 | {% block content %}
42 |
43 |
44 |
45 |
46 |
47 |
48 |
49 | | Name |
50 | {{ object.name }} |
51 |
52 |
53 | | Default Action |
54 | {{ object.get_default_action_display }} |
55 |
56 |
57 | | Rules |
58 | {{ object.rules.count }} |
59 |
60 |
61 |
62 |
63 | {% include 'inc/panels/custom_fields.html' %}
64 |
65 |
66 | {% include 'inc/panels/tags.html' %}
67 | {% include 'inc/panels/comments.html' %}
68 |
69 |
120 |
121 |
122 |
123 |
124 | {% render_table rules_table %}
125 |
126 |
127 |
128 |
150 |
151 |
152 |
153 |
154 |
155 |
156 | | Access List |
157 |
158 | {{ object.access_list }}
159 | |
160 |
161 |
162 | | Index |
163 | {{ object.index }} |
164 |
165 |
166 | | Description |
167 | {{ object.description|placeholder }} |
168 |
169 |
170 |
171 |
172 | {% include 'inc/panels/custom_fields.html' %}
173 | {% include 'inc/panels/tags.html' %}
174 |
175 |
176 |
177 |
178 |
179 |
180 |
181 | | Protocol |
182 | {{ object.get_protocol_display }} |
183 |
184 |
185 | | Source Prefix |
186 |
187 | {% if object.source_prefix %}
188 | {{ object.source_prefix }}
189 | {% else %}
190 | {{ ''|placeholder }}
191 | {% endif %}
192 | |
193 |
194 |
195 | | Source Ports |
196 | {{ object.source_ports|join:", "|placeholder }} |
197 |
198 |
199 | | Destination Prefix |
200 |
201 | {% if object.destination_prefix %}
202 | {{ object.destination_prefix }}
203 | {% else %}
204 | {{ ''|placeholder }}
205 | {% endif %}
206 | |
207 |
208 |
209 | | Destination Ports |
210 | {{ object.destination_ports|join:", "|placeholder }} |
211 |
212 |
213 | | Action |
214 | {{ object.get_action_display }} |
215 |
216 |
217 |
218 |
219 |
220 |
235 |
236 | :arrow_left: [Step 5: Views](/tutorial/step05-views.md) | [Step 7: Navigation](/tutorial/step07-navigation.md) :arrow_right:
237 |
238 |
239 |
240 |
--------------------------------------------------------------------------------
/tutorial/step07-navigation.md:
--------------------------------------------------------------------------------
1 | # Step 7: Navigation
2 |
3 | So far, we've been manually entering URLs to access our plugin's views. This obviously will not suffice for regular use, so let's see about adding some links to NetBox's navigation menu.
4 |
5 | :blue_square: **Note:** If you skipped the previous step, run `git checkout step06-templates`.
6 |
7 | ## Adding Navigation Menu Items
8 |
9 | Begin by creating `navigation.py` in the `netbox_access_lists/` directory.
10 |
11 | ```bash
12 | $ cd netbox_access_lists/
13 | $ edit navigation.py
14 | ```
15 |
16 | We'll need to import the `PluginMenuItem` class provided by NetBox to add new menu items; do this at the top of the file.
17 |
18 | ```python
19 | from extras.plugins import PluginMenuItem
20 | ```
21 |
22 | Next, we'll create a tuple named `menu_items`. This will hold our customized `PluginMenuItem` instances.
23 |
24 | ```python
25 | menu_items = ()
26 | ```
27 |
28 | Let's add a link to the list view for each of our models. This is done by instantiating `PluginMenuItem` with (at minimum) two arguments:
29 |
30 | * `link` - The name of the URL path to which we're linking
31 | * `link_text` - The text of the link
32 |
33 | Create two instances of `PluginMenuItem` within `menu_items`:
34 |
35 | ```python
36 | menu_items = (
37 | PluginMenuItem(
38 | link='plugins:netbox_access_lists:accesslist_list',
39 | link_text='Access Lists'
40 | ),
41 | PluginMenuItem(
42 | link='plugins:netbox_access_lists:accesslistrule_list',
43 | link_text='Access List Rules'
44 | ),
45 | )
46 | ```
47 |
48 | Upon reloading the page, you should see a new "Plugins" section appear at the end of the navigation menu, and below it, a section titled "NetBox Access Lists", with our two links. Navigating to either of these links will highlight the corresponding menu item.
49 |
50 | :blue_square: **Note:** If the menu items do not appear, try restarting the development server (`manage.py runserver`).
51 |
52 | 
53 |
54 | That's much more convenient!
55 |
56 | ### Adding Menu Buttons
57 |
58 | While we're at it, we can add direct links to the "add" views for access lists and rules as buttons. We'll need to import two additional classes at the top of `navigation.py`: `PluginMenuButton` and `ButtonColorChoices`.
59 |
60 | ```python
61 | from extras.plugins import PluginMenuButton, PluginMenuItem
62 | from utilities.choices import ButtonColorChoices
63 | ```
64 |
65 | `PluginMenuButton` is used similarly to `PluginMenuItem`: Instantiate it with the necessary keyword arguments to effect a menu button. These arguments are:
66 |
67 | * `link` - The name of the URL path to which the button links
68 | * `title` - The text displayed when the user hovers over the button
69 | * `icon_class` - CSS class name(s) indicating the icon to display
70 | * `color` - The button's color (choices are provided by `ButtonColorChoices`)
71 |
72 | Create these instances in `navigation.py` _above_ `menu_items`. Because each menu item expects to receive an iterable of button instances, we'll create each of these inside a list.
73 |
74 | ```python
75 | accesslist_buttons = [
76 | PluginMenuButton(
77 | link='plugins:netbox_access_lists:accesslist_add',
78 | title='Add',
79 | icon_class='mdi mdi-plus-thick',
80 | color=ButtonColorChoices.GREEN
81 | )
82 | ]
83 |
84 | accesslistrule_buttons = [
85 | PluginMenuButton(
86 | link='plugins:netbox_access_lists:accesslistrule_add',
87 | title='Add',
88 | icon_class='mdi mdi-plus-thick',
89 | color=ButtonColorChoices.GREEN
90 | )
91 | ]
92 | ```
93 |
94 | The buttons can then be passed to the menu items via the `buttons` keyword argument:
95 |
96 | ```python
97 | menu_items = (
98 | PluginMenuItem(
99 | link='plugins:netbox_access_lists:accesslist_list',
100 | link_text='Access Lists',
101 | buttons=accesslist_buttons
102 | ),
103 | PluginMenuItem(
104 | link='plugins:netbox_access_lists:accesslistrule_list',
105 | link_text='Access List Rules',
106 | buttons=accesslistrule_buttons
107 | ),
108 | )
109 | ```
110 |
111 | Now we should see green "add" buttons appear next to our menu links.
112 |
113 | 
114 |
115 |
116 |
117 | :arrow_left: [Step 6: Templates](/tutorial/step06-templates.md) | [Step 8: Filter Sets](/tutorial/step08-filter-sets.md) :arrow_right:
118 |
119 |
120 |
121 |
--------------------------------------------------------------------------------
/tutorial/step08-filter-sets.md:
--------------------------------------------------------------------------------
1 | # Step 8: Filter Sets
2 |
3 | Filters enable users to request only a specific subset of objects matching a query; when filtering the sites list by status or region, for instance. NetBox employs the [`django-filters`](https://django-filter.readthedocs.io/en/stable/) library to build and apply filter sets for models. We can create filter sets to enable this same functionality for our plugin as well.
4 |
5 | :blue_square: **Note:** If you skipped the previous step, run `git checkout step07-navigation`.
6 |
7 | ## Create a Filter Set
8 |
9 | Begin by creating `filtersets.py` in the `netbox_access_lists/` directory.
10 |
11 | ```bash
12 | $ cd netbox_access_lists/
13 | $ edit filtersets.py
14 | ```
15 |
16 | At the top of this file, we'll import NetBox's `NetBoxModelFilterSet` class, which will serve as the base class for our filter set, as well as our `AccessListRule` model. (In the interest of brevity, we're only going to create a filter set for one model, but it should be clear how to replicate this approach for the `AccessList` model as well.)
17 |
18 | ```python
19 | from netbox.filtersets import NetBoxModelFilterSet
20 | from .models import AccessListRule
21 | ```
22 |
23 | Next, create a class named `AccessListRuleFilterSet` subclassing `NetBoxModelFilterSet`. Within this class, create a child `Meta` class and define the filter set's `model` and `fields` attributes. (You may notice this looks familiar; it is very similar to the process for building a model form.) The `fields` parameter should list all the model fields against which we might want to filter.
24 |
25 | ```python
26 | class AccessListRuleFilterSet(NetBoxModelFilterSet):
27 |
28 | class Meta:
29 | model = AccessListRule
30 | fields = ('id', 'access_list', 'index', 'protocol', 'action')
31 | ```
32 |
33 | `NetBoxModelFilterSet` handles some important functions for us, including support for filtering by custom field values and tags. It also creates a general-purpose `q` filter which invokes the `search()` method. (By default, this does nothing.) We can override this method to define our general-purpose search logic. Let's add a `search` method after the `Meta` child class to override the default behavior.
34 |
35 | ```python
36 | def search(self, queryset, name, value):
37 | return queryset.filter(description__icontains=value)
38 | ```
39 |
40 | This will return all rules whose description contains the queried string. Of course, you're free to extend this to match other fields as well, but for our purposes this should be sufficient.
41 |
42 | ## Create a Filter Form
43 |
44 | The filter set handles the "behind the scenes" process of filtering queries, but we also need to create a form class to render the filter fields in the UI. We'll add this to `forms.py`. First, import Django's `forms` module (which will provide the field classes we need) and append `NetBoxModelFilterSetForm` to the existing import statement for `netbox.forms`:
45 |
46 | ```python
47 | from django import forms
48 | # ...
49 | from netbox.forms import NetBoxModelForm, NetBoxModelFilterSetForm
50 | ```
51 |
52 | Then create a form class named `AccessListRuleFilterForm` subclassing `NetBoxModelFilterSetForm` and declare an attribute named `model` referencing `AccessListRule` (which has already been imported for one of the existing forms).
53 |
54 | ```python
55 | class AccessListRuleFilterForm(NetBoxModelFilterSetForm):
56 | model = AccessListRule
57 | ```
58 |
59 | :blue_square: **Note:** Note that the `model` attribute is declared directly under the class: We don't need a `Meta` child class.
60 |
61 | Next, we need to define a form field for each filter that we want to appear in the UI. Let's start with the `access_list` filter: This references a related object, so we'll want to use `ModelMultipleChoiceField` (to allow users to filter by multiple objects). Add the form field with the same name as its peer filter, specifying the queryset to use when fetching related objects.
62 |
63 | ```python
64 | access_list = forms.ModelMultipleChoiceField(
65 | queryset=AccessList.objects.all(),
66 | required=False
67 | )
68 | ```
69 |
70 | Notice that we've also set `required=False`: This should be the case for _all_ fields in a filter form, because filters are never mandatory.
71 |
72 | :blue_square: **Note:** We're using Django's `ModelMultipleChoiceField` class for this field instead of NetBox's `DynamicModelChoiceField` because the latter requires a functional REST API endpoint for the model. Once we implement a REST API in step nine, you're free to revisit this form and change `access_list` to a `DynamicModelChoiceField`.
73 |
74 | Next we'll add a field for the `position` filter: This is an integer field, so `IntegerField` should work nicely:
75 |
76 | ```python
77 | index = forms.IntegerField(
78 | required=False
79 | )
80 | ```
81 |
82 | Finally, we'll add fields for the `protocol` and `action` choice-based filters. `MultipleChoiceField` should be used to allow users to select one or more choices. We must pass the set of valid choices when declaring these fields, so first extend the relevant import statement at the top of `forms.py`:
83 |
84 | ```python
85 | from .models import AccessList, AccessListRule, ActionChoices, ProtocolChoices
86 | ```
87 |
88 | Then add the form fields to `AccessListRuleFilterForm`:
89 |
90 | ```python
91 | protocol = forms.MultipleChoiceField(
92 | choices=ProtocolChoices,
93 | required=False
94 | )
95 | action = forms.MultipleChoiceField(
96 | choices=ActionChoices,
97 | required=False
98 | )
99 | ```
100 |
101 | ## Update the View
102 |
103 | The last step before we can use our new filter set and form is to enable them under the model's list view. Open `views.py` and extend the last import statement to include the `filtersets` module:
104 |
105 | ```python
106 | from . import filtersets, forms, models, tables
107 | ```
108 |
109 | Then, add the `filterset` and `filterset_form` attributes to `AccessListRuleListView`:
110 |
111 | ```python
112 | class AccessListRuleListView(generic.ObjectListView):
113 | queryset = models.AccessListRule.objects.all()
114 | table = tables.AccessListRuleTable
115 | filterset = filtersets.AccessListRuleFilterSet
116 | filterset_form = forms.AccessListRuleFilterForm
117 | ```
118 |
119 | After ensuring the development server has restarted, navigate to the rules list view in the browser. You should now see a "Filters" tab next to the "Results" tab. Under it we'll find the four fields we created on `AccessListRuleFilterForm`, as well as the built-in "search" field.
120 |
121 | 
122 |
123 | If you haven't already, create a few more access lists and rules, and experiment with the filters. Consider how you might filter by additional fields, or add more complex logic to the filter set.
124 |
125 | :green_circle: **Tip:** You may notice that we did not add a form field for the model's `id` filter: This is because it is unlikely to be useful for a human utilizing the UI. However, we still want to support filtering object by their primary keys, because it _is_ very helpful for consumers of NetBox's REST API, which we'll cover next.
126 |
127 |
128 |
129 | :arrow_left: [Step 7: Navigation](/tutorial/step07-navigation.md) | [Step 9: REST API](/tutorial/step09-rest-api.md) :arrow_right:
130 |
131 |
132 |
133 |
--------------------------------------------------------------------------------
/tutorial/step09-rest-api.md:
--------------------------------------------------------------------------------
1 | # Step 9: REST API
2 |
3 | The REST API enables powerful integration with other systems which exchange data with NetBox. It is powered by the [Django REST Framework](https://www.django-rest-framework.org/) (DRF), which is _not_ a component of Django itself. In this tutorial, we'll see how we can extend NetBox's REST API to serve our plugin.
4 |
5 | :blue_square: **Note:** If you skipped the previous step, run `git checkout step08-filter-sets`.
6 |
7 | Our API code will live in the `api/` directory under `netbox_access_lists/`. Let's go ahead and create that as well as an `__init__.py` file now:
8 |
9 | ```bash
10 | $ cd netbox_access_lists/
11 | $ mkdir api
12 | $ touch api/__init__.py
13 | ```
14 |
15 | ## Create Model Serializers
16 |
17 | Serializers are somewhat analogous to forms: They control the translation of client data to and from Python objects, while Django itself handles the database abstraction. We need to create a serializer for each of our models. Begin by creating `serializers.py` in the `api/` directory.
18 |
19 | ```bash
20 | $ edit api/serializers.py
21 | ```
22 |
23 | At the top of this file, we need to import the `serializers` module from the `rest_framework` library, as well as NetBox's `NetBoxModelSerializer` class and our plugin's own models:
24 |
25 | ```python
26 | from rest_framework import serializers
27 |
28 | from netbox.api.serializers import NetBoxModelSerializer
29 | from ..models import AccessList, AccessListRule
30 | ```
31 |
32 | ### Create AccessListSerializer
33 |
34 | First, we'll create a serializer for `AccessList`, subclassing `NetBoxModelSerializer`. Much like when creating a model form, we'll create a child `Meta` class under the serializer specifying the associated `model` and the `fields` to be included.
35 |
36 | ```python
37 | class AccessListSerializer(NetBoxModelSerializer):
38 |
39 | class Meta:
40 | model = AccessList
41 | fields = (
42 | 'id', 'display', 'name', 'default_action', 'comments', 'tags', 'custom_fields', 'created',
43 | 'last_updated',
44 | )
45 | ```
46 |
47 | It's worth discussing each of the fields we've named above. `id` is the model's primary key; it should always be included with every serializer, as it provides a guaranteed method of uniquely identifying objects. The `display` field is built into `NetBoxModelSerializer`: It is a read-only field which returns a string representation of the object. This is useful for populating form field dropdowns, for instance.
48 |
49 | The `name`, `default_action`, and `comments` fields are declared on the `AccessList` model. `tags` provides access to the object's tag manager, and `custom_fields` includes its custom field data; both of these are provided by `NetBoxModelSerializer`. Finally, the `created` and `last_updated` are read-only fields built into `NetBoxModel`.
50 |
51 | Our serializer will inspect the model to generate the necessary fields automatically, however there's one field that we need to add manually. Every serializer should include a read-only `url` field which contains the URL where the object can be reached; think of it as similar to a model's `get_absolute_url()` method. To add this, we'll use DRF's `HyperlinkedIdentityField`. Add it above the `Meta` child class:
52 |
53 | ```python
54 | class AccessListSerializer(NetBoxModelSerializer):
55 | url = serializers.HyperlinkedIdentityField(
56 | view_name='plugins-api:netbox_access_lists-api:accesslist-detail'
57 | )
58 | ```
59 |
60 | When invoking the field class, we need to specify the appropriate view name. Note that this view doesn't actually exist yet; we'll create it a bit later.
61 |
62 | Remember back in step three when we added a table column showing the number of rules assigned to each access list? That was handy. Let's add a serializer field for it too! Add this directly below the `url` field:
63 |
64 | ```python
65 | rule_count = serializers.IntegerField(read_only=True)
66 | ```
67 |
68 | Just as with the table column, we'll rely on our view (to be defined next) to annotate the rule count for each access list on the underlying queryset.
69 |
70 | Finally, we need to add both `url` and `rule_count` to `Meta.fields`:
71 |
72 | ```python
73 | class Meta:
74 | model = AccessList
75 | fields = (
76 | 'id', 'url', 'display', 'name', 'default_action', 'comments', 'tags', 'custom_fields', 'created',
77 | 'last_updated', 'rule_count',
78 | )
79 | ```
80 |
81 | :green_circle: **Tip:** The order in which fields are listed determines the order in which they appear in the object's API representation.
82 |
83 | ### Create AccessListRuleSerializer
84 |
85 | We also need to create a serializer for `AccessListRule`. Add it to `serializers.py` below `AccessListSerializer`. As with the first serializer, we'll add a `Meta` class to define the model and fields, and a `url` field.
86 |
87 | ```python
88 | class AccessListRuleSerializer(NetBoxModelSerializer):
89 | url = serializers.HyperlinkedIdentityField(
90 | view_name='plugins-api:netbox_access_lists-api:accesslistrule-detail'
91 | )
92 |
93 | class Meta:
94 | model = AccessListRule
95 | fields = (
96 | 'id', 'url', 'display', 'access_list', 'index', 'protocol', 'source_prefix', 'source_ports',
97 | 'destination_prefix', 'destination_ports', 'action', 'tags', 'custom_fields', 'created',
98 | 'last_updated',
99 | )
100 | ```
101 |
102 | There's an additional consideration when referencing related objects in a serializer. By default, the serializer will return only the primary key of the related object; its numeric ID. This requires the client to make additional API requests in order to determine _any_ other information about the related object. It is convenient to include on the serializer some information about the related object, such as its name and URL, automatically. We can do this by using a _nested serializer_.
103 |
104 | For instance, the `source_prefix` and `destination_prefix` fields both reference NetBox's core `ipam.Prefix` model. We can extend `AccessListRuleSerializer` to use NetBox's nested serializer for this model:
105 |
106 | ```python
107 | from ipam.api.serializers import NestedPrefixSerializer
108 | # ...
109 | class AccessListRuleSerializer(NetBoxModelSerializer):
110 | url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_access_lists-api:accesslistrule-detail')
111 | source_prefix = NestedPrefixSerializer()
112 | destination_prefix = NestedPrefixSerializer()
113 | ```
114 |
115 | Now, our serializer will include an abridged representation of the source and/or destination prefixes for the object. We should do this with the `access_list` field as well, however we'll first need to create a nested serializer for the `AccessList` model.
116 |
117 | ### Create Nested Serializers
118 |
119 | Begin by importing NetBox's `WritableNestedSerializer` class. This will serve as the base class for our nested serializers.
120 |
121 | ```python
122 | from netbox.api.serializers import NetBoxModelSerializer, WritableNestedSerializer
123 | ```
124 |
125 | Then, create two nested serializer classes, one for each of our plugin's models. Each of these will have a `url` field and `Meta` child class like the regular serializers, however the `Meta.fields` attribute for each is limited to a bare minimum of fields: `id`, `url`, `display`, and a supplementary human-friendly identifier. Add these in `serializers.py` _above_ the regular serializers (because we need to define `NestedAccessListSerializer` before we can reference it).
126 |
127 | ```python
128 | class NestedAccessListSerializer(WritableNestedSerializer):
129 | url = serializers.HyperlinkedIdentityField(
130 | view_name='plugins-api:netbox_access_lists-api:accesslist-detail'
131 | )
132 |
133 | class Meta:
134 | model = AccessList
135 | fields = ('id', 'url', 'display', 'name')
136 |
137 | class NestedAccessListRuleSerializer(WritableNestedSerializer):
138 | url = serializers.HyperlinkedIdentityField(
139 | view_name='plugins-api:netbox_access_lists-api:accesslistrule-detail'
140 | )
141 |
142 | class Meta:
143 | model = AccessListRule
144 | fields = ('id', 'url', 'display', 'index')
145 | ```
146 |
147 | Now we can override the `access_list` field on `AccessListRuleSerializer` to use the nested serializer:
148 |
149 | ```python
150 | class AccessListRuleSerializer(NetBoxModelSerializer):
151 | url = serializers.HyperlinkedIdentityField(
152 | view_name='plugins-api:netbox_access_lists-api:accesslistrule-detail'
153 | )
154 | access_list = NestedAccessListSerializer()
155 | source_prefix = NestedPrefixSerializer()
156 | destination_prefix = NestedPrefixSerializer()
157 | ```
158 |
159 | ## Create the Views
160 |
161 | Next, we need to create views to handle the API logic. Just as serializers are roughly analogous to forms, API views work similarly to the UI views that we created in step five. However, because API functionality is highly standardized, view creation is substantially simpler: We generally need only to create a single _view set_ for each model. A view set is a single class that can handle the view, add, change, and delete operations which each require dedicated views under the UI.
162 |
163 | Start by creating `api/views.py` and importing NetBox's `NetBoxModelViewSet` class, as well as our plugin's `models` and `filtersets` modules, and our serializers.
164 |
165 | ```python
166 | from netbox.api.viewsets import NetBoxModelViewSet
167 |
168 | from .. import filtersets, models
169 | from .serializers import AccessListSerializer, AccessListRuleSerializer
170 | ```
171 |
172 | First we'll create a view set for access lists, by inheriting from `NetBoxModelViewSet` and defining its `queryset` and `serializer_class` attributes. (Note that we're prefetching assigned tags for the queryset.)
173 |
174 | ```python
175 | class AccessListViewSet(NetBoxModelViewSet):
176 | queryset = models.AccessList.objects.prefetch_related('tags')
177 | serializer_class = AccessListSerializer
178 | ```
179 |
180 | Recall that we added a `rule_count` field to `AccessListSerializer`; let's annotate the queryset appropriately to ensure that field gets populated (just as we did for the table column in step five). Remember to import Django's `Count` utility class.
181 |
182 | ```python
183 | from django.db.models import Count
184 | # ...
185 | class AccessListViewSet(NetBoxModelViewSet):
186 | queryset = models.AccessList.objects.prefetch_related('tags').annotate(
187 | rule_count=Count('rules')
188 | )
189 | serializer_class = AccessListSerializer
190 | ```
191 |
192 | Next, we'll add a view set for rules. In addition to `queryset` and `serializer_class`, we'll attach the filter set for this model as `filterset_class`. Note that we're also prefetching all related object fields in addition to tags to improve performance when listing many objects.
193 |
194 | ```python
195 | class AccessListRuleViewSet(NetBoxModelViewSet):
196 | queryset = models.AccessListRule.objects.prefetch_related(
197 | 'access_list', 'source_prefix', 'destination_prefix', 'tags'
198 | )
199 | serializer_class = AccessListRuleSerializer
200 | filterset_class = filtersets.AccessListRuleFilterSet
201 | ```
202 |
203 | ## Create the Endpoint URLs
204 |
205 | Finally, we'll create our API endpoint URLs. This works a bit differently from UI views: Instead of defining a series of paths, we instantiate a _router_ and register each view set to it.
206 |
207 | Create `api/urls.py` and import NetBox's `NetBoxRouter` and our API views:
208 |
209 | ```python
210 | from netbox.api.routers import NetBoxRouter
211 | from . import views
212 | ```
213 |
214 | Next, we'll define an `app_name`. This will be used to resolve API view names for our plugin.
215 |
216 | ```python
217 | app_name = 'netbox_access_list'
218 | ```
219 |
220 | Then, we create a `NetBoxRouter` instance and register each view with it using our desired URL. These are the endpoints that will be available under `/api/plugins/access-lists/`.
221 |
222 | ```python
223 | router = NetBoxRouter()
224 | router.register('access-lists', views.AccessListViewSet)
225 | router.register('access-list-rules', views.AccessListRuleViewSet)
226 | ```
227 |
228 | Finally, we expose the router's `urls` attribute as `urlpatterns` so that it will be detected by the plugins framework.
229 |
230 | ```python
231 | urlpatterns = router.urls
232 | ```
233 |
234 | :green_circle: **Tip:** The base URL for our plugin's REST API endpoints is determined by the `base_url` attribute of the plugin config class that we created in step one.
235 |
236 | With all of our REST API components now in place, we should be able to make API requests. (Note that you may first need to provision a token for authentication.) You can quickly verify that our endpoints are working properly by navigating to in your browser while logged into NetBox. You should see the two available endpoints; clicking on either will return a list of objects.
237 |
238 | :blue_square: **Note:** If the REST API endpoints do not load, try restarting the development server (`manage.py runserver`).
239 |
240 | 
241 |
242 | 
243 |
244 |
245 |
246 | :arrow_left: [Step 8: Filter Sets](/tutorial/step08-filter-sets.md) | [Step 10: GraphQL API](/tutorial/step10-graphql-api.md) :arrow_right:
247 |
248 |
249 |
250 |
--------------------------------------------------------------------------------
/tutorial/step10-graphql-api.md:
--------------------------------------------------------------------------------
1 | # Step 10: GraphQL API
2 |
3 | In addition to its REST API, NetBox also features a [GraphQL](https://graphql.org/) API. This can be used to conveniently request arbitrary collections of data about NetBox objects. NetBox's GraphQL API is built using the [Graphene](https://graphene-python.org/) and [`graphene-django`](https://docs.graphene-python.org/projects/django/en/latest/) library.
4 |
5 | :blue_square: **Note:** If you skipped the previous step, run `git checkout step09-rest-api`.
6 |
7 | Begin by creating `graphql.py`. This will hold our object type and query classes.
8 |
9 | ```bash
10 | $ cd netbox_access_lists/
11 | $ edit graphql.py
12 | ```
13 |
14 | We'll need to import several resources. First we need Graphene's `ObjectType` class, as well as NetBox's custom `NetBoxObjectType` which inherits from it. (The latter will be used for our model types.) We also need the `ObjectField` and `ObjectListField` classes provided by NetBox for our query. And finally, import our plugin's `models` and `filtersets` modules.
15 |
16 | ```python
17 | from graphene import ObjectType
18 | from netbox.graphql.types import NetBoxObjectType
19 | from netbox.graphql.fields import ObjectField, ObjectListField
20 | from . import filtersets, models
21 | ```
22 |
23 | ## Create the Object Types
24 |
25 | Subclass `NetBoxObjectType` to create two object type classes, one for each of our models. Just like with the REST API serilizers, create a child `Meta` class on each defining its `model` and `fields`. However, instead of explicitly listing each field by name, in our case we can use the special value `__all__` to indicate that we want to include all available model fields. Additionally, declare `filterset_class` on `AccessListRuleType` to attach the filter set.
26 |
27 | ```python
28 | class AccessListType(NetBoxObjectType):
29 |
30 | class Meta:
31 | model = models.AccessList
32 | fields = '__all__'
33 |
34 |
35 | class AccessListRuleType(NetBoxObjectType):
36 |
37 | class Meta:
38 | model = models.AccessListRule
39 | fields = '__all__'
40 | filterset_class = filtersets.AccessListRuleFilterSet
41 | ```
42 |
43 | ## Create the Query
44 |
45 | Then we need to create our query class. Subclass Graphene's `ObjectType` class and define two fields for each model: an object field and a list field.
46 |
47 | ```python
48 | class Query(ObjectType):
49 | access_list = ObjectField(AccessListType)
50 | access_list_list = ObjectListField(AccessListType)
51 |
52 | access_list_rule = ObjectField(AccessListRuleType)
53 | access_list_rule_list = ObjectListField(AccessListRuleType)
54 | ```
55 |
56 | Then we just need to expose our query class to the plugins framework as `schema`:
57 |
58 | ```python
59 | schema = Query
60 | ```
61 |
62 | :green_circle: **Tip:** The path to the query class can be changed by setting `graphql_schema` in the plugin's configuration class.
63 |
64 | To try out the GraphQL API, open `` in a browser and enter the following query:
65 |
66 | ```
67 | query {
68 | access_list_list {
69 | id
70 | name
71 | rules {
72 | index
73 | action
74 | description
75 | }
76 | }
77 | }
78 | ```
79 |
80 | You should receive a response showing the ID, name, and rules for each access list in NetBox. Each rule will list its index, action, and description. Experiment with different queries to see what other data you can request. (Refer back to the model definitions for inspiration.)
81 |
82 | 
83 |
84 | This completes the plugin development tutorial. Well done! Now you're all set to make a plugin of your own!
85 |
86 |
87 |
88 | :arrow_left: [Step 9: REST API](/tutorial/step09-rest-api.md) | [Step 11: Search](/tutorial/step11-search.md) :arrow_right:
89 |
90 |
91 |
92 |
--------------------------------------------------------------------------------
/tutorial/step11-search.md:
--------------------------------------------------------------------------------
1 | # Step 11: NetBox v3.4 Features
2 |
3 | NetBox version 3.4, released in December 2022, introduced a greatly improved global search engine, which includes the ability for plugins to register their own models. In this step, we'll add search indexers for our custom models so that they appear in NetBox's global search results.
4 |
5 | :warning: **Warning:** This feature requires NetBox v3.4 or later. If you haven't already, be sure to set `min_version = '3.4.0'` in `NetBoxAccessListsConfig`.
6 |
7 | :blue_square: **Note:** If you skipped the previous step, run `git checkout step10-graphql`.
8 |
9 | ## Create Search Indexes
10 |
11 | Our plugin has two models: `AccessList` and `AccessListRule`. We'd like users to be able to search instances of both models using NetBox's global search feature. To enable this, we need to declare and register a `SearchIndex` subclass for each model.
12 |
13 | Begin by creating `search.py` in the plugin's root directory, alongside `models.py`.
14 |
15 | ```bash
16 | $ cd netbox_access_lists/
17 | $ edit search.py
18 | ```
19 |
20 | Within this file, we'll import NetBox's `SearchIndex` class as well as our own models. Then, we'll create a subclass of `SearchIndex` for each model:
21 |
22 | ```python
23 | from netbox.search import SearchIndex
24 | from .models import AccessList, AccessListRule
25 |
26 | class AccessListIndex(SearchIndex):
27 | model = AccessList
28 |
29 | class AccessListRuleIndex(SearchIndex):
30 | model = AccessListRule
31 | ```
32 |
33 | There's a bit more to enabling search, though. We also need to tell NetBox which fields to search for each model, and how important each field is (also known as its _precedence_). The latter is accomplished by assigning a numerical weight.
34 |
35 | Consider our `AccessList` model. It has three interesting database fields: `name`, `default_action`, and `comments`. How should we treat these when searching for objects in NetBox? This can be somewhat subjective, but generally we want to assign higher precedence (_lower_ weights) to important fields, and omit fields that we don't care about. If you're unsure what weights to assign, have a look around the core NetBox code base for similar examples.
36 |
37 | * `name`: This is an important field, so we'll give it a high precedence of `100`.
38 | * `default_action` This is a choice selection field. While very useful for _filtering_, we wouldn't typically expect users to search for these values. We'll exclude this field from the search index.
39 | * `comments`: It's always recommended to include user comments in the search index, however we'll assign this field a much lower precedence of `5000` as any matches are less likely to be pertinent.
40 |
41 | After selecting our search fields and their precedences, we should have something like this:
42 |
43 | ```python
44 | class AccessListIndex(SearchIndex):
45 | model = AccessList
46 | fields = (
47 | ('name', 100),
48 | ('comments', 5000),
49 | )
50 |
51 | class AccessListRuleIndex(SearchIndex):
52 | model = AccessListRule
53 | fields = (
54 | ('description', 500),
55 | )
56 | ```
57 |
58 | Why did we exclude the source and destination parameters from `AccessListRuleIndex`? The source and destination prefixes are related objects, so we want to avoid caching their values locally: If the related object is changed, our cached copy can become outdated. And we omit the source and destination port numbers because matching on common integer values can produce a ton of irrelevant search results. All of these values are better matched using specific filters rather than general purpose search.
59 |
60 | ## Register the Indexers
61 |
62 | Finally, we need to register our indexers so that NetBox knows to run them. At the top of `search.py`, import the `register_search` decorator. Then, use it to wrap both of our index classes:
63 |
64 | ```python
65 | from netbox.search import SearchIndex, register_search
66 | from .models import AccessList, AccessListRule
67 |
68 | @register_search
69 | class AccessListIndex(SearchIndex):
70 | model = AccessList
71 | fields = (
72 | ('name', 100),
73 | ('comments', 5000),
74 | )
75 |
76 | @register_search
77 | class AccessListRuleIndex(SearchIndex):
78 | model = AccessListRule
79 | fields = (
80 | ('description', 500),
81 | )
82 | ```
83 |
84 | With our indexers now registered, we can run the `reindex` management command to index any existing objects. (New objects created from this point forward will be registered automatically upon creation.)
85 |
86 | ```
87 | $ ./manage.py reindex netbox_access_lists
88 | Reindexing 2 models.
89 | Indexing models
90 | netbox_access_lists.accesslist... 1 entries cached.
91 | netbox_access_lists.accesslistrule... 3 entries cached.
92 | ```
93 |
94 | Now we can search for access lists and rules using NetBox's global search function.
95 |
96 | 
97 |
98 |
99 |
100 | :arrow_left: [Step 10: GraphQL API](/tutorial/step10-graphql-api.md)
101 |
102 |
103 |
--------------------------------------------------------------------------------