mirror/netbox-community-netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2024-05-10 07:54:54 +00:00
Code

Document templates supported for plugin use

Browse Source
This commit is contained in:
jeremystretch
2022-02-08 12:14:37 -05:00
parent 270288f730
commit d9b7c012a6
3 changed files with 197 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

195
docs/plugins/development/templates.md Normal file
View File

@ -0,0 +1,195 @@
# Templates
## Base Templates
The following template blocks are available on all templates.
| Name | Required | Description |
|--------------|----------|---------------------------------------------------------------------|
| `title` | Yes | Page title |
| `content` | Yes | Page content |
| `head` | - | Content to include in the HTML `<head>` element |
| `javascript` | - | Javascript content included at the end of the HTML `<body>` element |
!!! note
For more information on how template blocks work, consult the [Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#block).
### layout.html
Path: `base/layout.html`
NetBox provides a base template to ensure a consistent user experience, which plugins can extend with their own content. This is a general-purpose template that can be used when none of the function-specific templates below are suitable.
#### Blocks
| Name | Required | Description |
|-----------|----------|----------------------------|
| `header` | - | Page header |
| `tabs` | - | Horizontal navigation tabs |
| `modals` | - | Bootstrap 5 modal elements |
#### Example
An example of a plugin template which extends `layout.html` is included below.
```jinja2
{% extends 'base/layout.html' %}
{% block header %}
<h1>My Custom Header</h1>
{% endblock header %}
{% block content %}
<p>{{ some_plugin_context_var }}</p>
{% endblock content %}
```
The first line of the template instructs Django to extend the NetBox base template and inject our custom content within its `content` block.
!!! note
Django renders templates with its own custom [template language](https://docs.djangoproject.com/en/stable/topics/templates/#the-django-template-language). This is very similar to Jinja2, however there are some important distinctions of which authors should be aware. Be sure to familiarize yourself with Django's template language before attempting to create new templates.
## Generic View Templates
### object.html
Path: `generic/object.html`
This template is used by the `ObjectView` generic view to display a single object.
#### Blocks
| Name | Required | Description |
|---------------------|----------|----------------------------------------------|
| `breadcrumbs` | - | Breadcrumb list items (HTML `<li>` elements) |
| `object_identifier` | - | A unique identifier (string) for the object |
| `extra_controls` | - | Additional action buttons to display |
| `extra_tabs` | - | Additional tabs to include |
#### Context
| Name | Required | Description |
|----------|----------|----------------------------------|
| `object` | Yes | The object instance being viewed |
### object_edit.html
Path: `generic/object_edit.html`
This template is used by the `ObjectEditView` generic view to create or modify a single object.
#### Blocks
| Name | Required | Description |
|------------------|----------|-------------------------------------------------------|
| `form` | - | Custom form content (within the HTML `<form>` element |
| `buttons` | - | Form submission buttons |
#### Context
| Name | Required | Description |
|--------------|----------|-----------------------------------------------------------------|
| `object` | Yes | The object instance being modified (or none, if creating) |
| `form` | Yes | The form class for creating/modifying the object |
| `return_url` | Yes | The URL to which the user is redirect after submitting the form |
### object_delete.html
Path: `generic/object_delete.html`
This template is used by the `ObjectDeleteView` generic view to delete a single object.
#### Blocks
None
#### Context
| Name | Required | Description |
|--------------|----------|-----------------------------------------------------------------|
| `object` | Yes | The object instance being deleted |
| `form` | Yes | The form class for confirming the object's deletion |
| `return_url` | Yes | The URL to which the user is redirect after submitting the form |
### object_list.html
Path: `generic/object_list.html`
This template is used by the `ObjectListView` generic view to display a filterable list of multiple objects.
#### Blocks
| Name | Required | Description |
|------------------|----------|--------------------------------------------------------------------|
| `extra_controls` | - | Additional action buttons |
| `bulk_buttons` | - | Additional bulk action buttons to display beneath the objects list |
#### Context
| Name | Required | Description |
|------------------|----------|-----------------------------------------------------------------------|
| `model` | Yes | The object class |
| `table` | Yes | The table class used for rendering the list of objects |
| `permissions` | Yes | A mapping of add, change, and delete permissions for the current user |
| `action_buttons` | Yes | A list of buttons to display (options are `add`, `import`, `export`) |
| `filter_form` | - | The bound filterset form for filtering the objects list |
| `return_url` | - | The return URL to pass when submitting a bulk operation form |
### bulk_import.html
Path: `generic/bulk_import.html`
This template is used by the `BulkImportView` generic view to import multiple objects at once from CSV data.
#### Blocks
None
#### Context
| Name | Required | Description |
|--------------|----------|--------------------------------------------------------------|
| `model` | Yes | The object class |
| `form` | Yes | The CSV import form class |
| `return_url` | - | The return URL to pass when submitting a bulk operation form |
| `fields` | - | A dictionary of form fields, to display import options |
### bulk_edit.html
Path: `generic/bulk_edit.html`
This template is used by the `BulkEditView` generic view to modify multiple objects simultaneously.
#### Blocks
None
#### Context
| Name | Required | Description |
|--------------|----------|-----------------------------------------------------------------|
| `model` | Yes | The object class |
| `form` | Yes | The bulk edit form class |
| `table` | Yes | The table class used for rendering the list of objects |
| `return_url` | Yes | The URL to which the user is redirect after submitting the form |
### bulk_delete.html
Path: `generic/bulk_delete.html`
This template is used by the `BulkDeleteView` generic view to delete multiple objects simultaneously.
#### Blocks
| Name | Required | Description |
|-----------------|----------|---------------------------------------|
| `message_extra` | - | Supplementary warning message content |
#### Context
| Name | Required | Description |
|--------------|----------|-----------------------------------------------------------------|
| `model` | Yes | The object class |
| `form` | Yes | The bulk delete form class |
| `table` | Yes | The table class used for rendering the list of objects |
| `return_url` | Yes | The URL to which the user is redirect after submitting the form |

42
docs/plugins/development/views.md
View File

@ -71,47 +71,7 @@ A URL pattern has three components:
This makes our view accessible at the URL `/plugins/animal-sounds/random/`. (Remember, our `AnimalSoundsConfig` class sets our plugin's base URL to `animal-sounds`.) Viewing this URL should show the base NetBox template with our custom content inside it.
## Templates
### Plugin Views
NetBox provides a base template to ensure a consistent user experience, which plugins can extend with their own content. This template includes four content blocks:
* `title` - The page title
* `header` - The upper portion of the page
* `content` - The main page body
* `javascript` - A section at the end of the page for including Javascript code
For more information on how template blocks work, consult the [Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#block).
```jinja2
{% extends 'base/layout.html' %}
{% block content %}
{% with config=settings.PLUGINS_CONFIG.netbox_animal_sounds %}
<h2 class="text-center" style="margin-top: 200px">
{% if animal %}
The {{ animal.name|lower }} says
{% if config.loud %}
{{ animal.sound|upper }}!
{% else %}
{{ animal.sound }}
{% endif %}
{% else %}
No animals have been created yet!
{% endif %}
</h2>
{% endwith %}
{% endblock %}
```
The first line of the template instructs Django to extend the NetBox base template and inject our custom content within its `content` block.
!!! note
Django renders templates with its own custom [template language](https://docs.djangoproject.com/en/stable/topics/templates/#the-django-template-language). This is very similar to Jinja2, however there are some important differences to be aware of.
### Extending Core Views
## Extending Core Views
Plugins can inject custom content into certain areas of the detail views of applicable models. This is accomplished by subclassing `PluginTemplateExtension`, designating a particular NetBox model, and defining the desired methods to render custom content. Four methods are available:

1
mkdocs.yml
View File

@ -104,6 +104,7 @@ nav:
- Getting Started: 'plugins/development/index.md'
- Models: 'plugins/development/models.md'
- Views: 'plugins/development/views.md'
- Templates: 'plugins/development/templates.md'
- Tables: 'plugins/development/tables.md'
- Forms: 'plugins/development/forms.md'
- Filter Sets: 'plugins/development/filtersets.md'