nautobot.apps.ui
¶
Utilities for apps to integrate with and extend the existing Nautobot UI.
nautobot.apps.ui.Banner
¶
Class that may be returned by a registered plugin_banners function.
nautobot.apps.ui.BaseBreadcrumbItem
dataclass
¶
Base interface for breadcrumb items.
Attributes:
Name | Type | Description |
---|---|---|
should_render |
Callable[[Context], bool]
|
Callable to decide whether this item should be rendered or not. |
label |
Union[Callable[[Context], str], WithStr, None]
|
Optional override for the display label in the breadcrumb. |
label_key |
Optional[str]
|
Optional key to take label from the context. |
as_pair(context)
¶
Construct the (URL, label) pair for the breadcrumb.
Combines get_url()
and get_label()
and applies title casing to the label.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
Context object used to resolve the breadcrumb parts. |
required |
Returns:
Type | Description |
---|---|
str
|
tuple[str, Optional[str]]: A tuple of (URL, label), where URL may be an empty string |
str
|
if unresolved, and label is title-cased. |
get_label(context)
¶
Get the label (display text) for the breadcrumb.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
Label as a string. |
get_url(context)
¶
Get the URL for the breadcrumb item.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Type | Description |
---|---|
Optional[str]
|
Optional[str]: The URL as a string, or None. |
resolve_reverse_params(params, context)
staticmethod
¶
Resolves parameters for URL reversing, calling if callable, or returning as-is.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
params
|
ReverseParams
|
Dict or callable to resolve. |
required |
context
|
Context
|
Context for callables. |
required |
Returns:
Type | Description |
---|---|
dict[str, Any]
|
dict[str, Any]: Dictionary of parameters for URL reversing. |
reverse_view_name(view_name, context, reverse_kwargs=None, reverse_query_params=None)
¶
Reverse a Django view name into a URL, optionally adding query parameters.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
view_name
|
str
|
Django view name to reverse. |
required |
context
|
Context
|
Template context, used to resolve params if needed. |
required |
reverse_kwargs
|
ReverseParams
|
URL kwargs for reversing. |
None
|
reverse_query_params
|
ReverseParams
|
Query parameters to append. |
None
|
Returns:
Type | Description |
---|---|
Optional[str]
|
Optional[str]: The resolved URL as a string, or None if reversing fails. |
nautobot.apps.ui.BaseTextPanel
¶
Bases: Panel
A panel that renders a single value as text, Markdown, JSON, or YAML.
RenderOptions
¶
Bases: Enum
Options available for text panels for different type of rendering a given input.
Attributes:
Name | Type | Description |
---|---|---|
PLAINTEXT |
str
|
Plain text format (value: "plaintext"). |
JSON |
str
|
Dict will be dumped into JSON and pretty-formatted (value: "json"). |
YAML |
str
|
Dict will be displayed as pretty-formatted yaml (value: "yaml") |
MARKDOWN |
str
|
Markdown format (value: "markdown"). |
CODE |
str
|
Code format. Just wraps content within tags (value: "code"). |
__init__(*, render_as=RenderOptions.MARKDOWN, body_content_template_path='components/panel/body_content_text.html', render_placeholder=True, **kwargs)
¶
Instantiate BaseTextPanel.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
render_as
|
RenderOptions
|
One of BaseTextPanel.RenderOptions to define rendering function. |
MARKDOWN
|
render_placeholder
|
bool
|
Whether to render placeholder text if given value is "falsy". |
True
|
body_content_template_path
|
str
|
The path of the template to use for the body content. Can be overridden for custom use cases. |
'components/panel/body_content_text.html'
|
kwargs
|
dict
|
Additional keyword arguments passed to |
{}
|
nautobot.apps.ui.Breadcrumbs
¶
Base class responsible for generating and rendering breadcrumbs for a page.
This class supports flexible breadcrumb configuration through:
- items
: Default breadcrumb items per view action.
You can add more information to the breadcrumbs trail by passing appropriate
BreadcrumbItem
objects grouped by view action (e.g., "*", "list", "add", "edit").
Important
This class automatically adds the:
- InstanceBreadcrumbItem
at the end of detail
breadcrumbs
- ModelBreadcrumbItem
at the beginning of list
and detail
breadcrumbs
You can override this behavior by subclassing this class and updating
the list_breadcrumb_item
or detail_breadcrumb_item
attributes.
If you're using custom action other than list
/ detail
you need to remember to add above breadcrumbs
if you need them in your custom action.
Attributes:
Name | Type | Description |
---|---|---|
template |
str
|
Path to the template used to render the breadcrumb component. |
items |
dict[str, list[BreadcrumbItem]]
|
Default breadcrumb items per view action. |
__init__(items=None, template='inc/breadcrumbs.html')
¶
Initialize the Breadcrumbs configuration.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
items
|
Optional[dict[str, list[BreadcrumbItem]]]
|
Default breadcrumb items for each action. |
None
|
template
|
str
|
The template used to render the breadcrumbs. |
'inc/breadcrumbs.html'
|
filter_breadcrumbs_items(items, context)
¶
Filters out all items that both label and url are None or empty str.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
items
|
list[tuple[str, str]]
|
breadcrumb items pair.s |
required |
context
|
Context
|
The view or template context. |
required |
Returns:
Type | Description |
---|---|
list[tuple[str, str]]
|
A list of filtered breadcrumb items pairs. |
get_breadcrumbs_items(context)
¶
Compute the list of breadcrumb items for the given context.
Items are determined based on the view_action
in context.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The view or template context that holds |
required |
Returns:
Type | Description |
---|---|
list[tuple[str, str]]
|
A list of (url, label) tuples representing breadcrumb entries. |
get_extra_context(context)
¶
Provide additional data to include in the rendering context, based on the configuration of this component.
Context updated here will be applied to resolving url and labels.
Please ote that you can't override breadcrumb_items
here because items are generated after this method call.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current context passed to |
required |
Returns:
Type | Description |
---|---|
dict
|
A dictionary of extra context variables. |
get_items_for_action(items, action, detail)
staticmethod
¶
Get the breadcrumb items for a specific action, with fallback to 'detail' if not found and to asterisk (*) if present.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
items
|
BreadcrumbItemsType
|
Dictionary mapping action names to breadcrumb item lists. |
required |
action
|
str
|
Current action name (e.g., "list", "detail"). |
required |
detail
|
bool
|
Whether this is a detail view (for fallback). |
required |
Returns:
Type | Description |
---|---|
list[BaseBreadcrumbItem]
|
list[BaseBreadcrumbItem]: List of breadcrumb items for the action. |
is_label_not_blank(label)
staticmethod
¶
Check if label is not empty (only whitespace) or None.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
label
|
str
|
The label to check. |
required |
Returns:
Type | Description |
---|---|
bool
|
True if label is not None or empty (only whitespace), False otherwise. |
render(context)
¶
Render the breadcrumbs HTML.
This method updates the context with the generated breadcrumb items and any additional context from get_extra_context
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current rendering context. |
required |
Returns:
Type | Description |
---|---|
str
|
Rendered HTML for the breadcrumb component. |
nautobot.apps.ui.Button
¶
Bases: Component
Base class for UI framework definition of a single button within an Object Detail (Object Retrieve) page.
__init__(*, label, color=ButtonColorChoices.DEFAULT, link_name=None, icon=None, template_path='components/button/default.html', required_permissions=None, javascript_template_path=None, attributes=None, size=None, link_includes_pk=True, context_object_key=None, **kwargs)
¶
Initialize a Button component.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
label
|
str
|
The text of this button, not including any icon. |
required |
color
|
ButtonColorChoices
|
The color (class) of this button. |
DEFAULT
|
link_name
|
str
|
View name to link to, for example "dcim:locationtype_retrieve".
This link will be reversed and will automatically include the current object's PK as a parameter to the
|
None
|
context_object_key
|
str
|
The key in the render context that will contain the linked object. |
None
|
icon
|
str
|
Material Design Icons icon, to include on the button, for example |
None
|
template_path
|
str
|
Template to render for this button. |
'components/button/default.html'
|
required_permissions
|
list
|
Permissions such as |
None
|
javascript_template_path
|
str
|
JavaScript template to render and include with this button.
Does not need to include the wrapping |
None
|
attributes
|
dict
|
Additional HTML attributes and their values to attach to the button. |
None
|
size
|
str
|
The size of the button (e.g. |
None
|
get_extra_context(context)
¶
Add the relevant attributes of this Button to the context.
get_link(context)
¶
Get the hyperlink URL (if any) for this button.
Defaults to reversing self.link_name
with pk: obj.pk
as a kwarg, but subclasses may override this for
more advanced link construction.
render(context)
¶
Render this button to HTML, possibly including any associated JavaScript.
should_render(context)
¶
Render if and only if the requesting user has appropriate permissions (if any).
nautobot.apps.ui.ButtonColorChoices
¶
nautobot.apps.ui.Component
¶
Common base class for renderable components (tabs, panels, etc.).
__init__(*, weight)
¶
Initialize common Component properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
weight
|
int
|
A relative weighting of this Component relative to its peers. Typically lower weights will be rendered "first", usually towards the top left of the page. |
required |
get_extra_context(context)
¶
Provide additional data to include in the rendering context, based on the configuration of this component.
Returns:
Type | Description |
---|---|
dict
|
Additional context data. |
render(context)
¶
Render this component to HTML.
Note that not all Components are fully or solely rendered by their render()
method alone, for example,
a Tab has a separate "label" that must be rendered by calling its render_label_wrapper()
API instead.
Returns:
Type | Description |
---|---|
str
|
HTML fragment, normally generated by a call(s) to |
should_render(context)
¶
Check whether this component should be rendered at all.
This API is designed to provide "short-circuit" logic for skipping what otherwise might be expensive rendering. In general most Components may also return an empty string when actually rendered, which is typically also a means to specify that they do not need to be rendered, but may be more expensive to derive.
Returns:
Type | Description |
---|---|
bool
|
|
nautobot.apps.ui.DataTablePanel
¶
Bases: Panel
A panel that renders a table generated directly from a list of dicts, without using a django_tables2 Table class.
__init__(*, context_data_key, columns=None, context_columns_key=None, column_headers=None, context_column_headers_key=None, body_wrapper_template_path='components/panel/body_wrapper_table.html', body_content_template_path='components/panel/body_content_data_table.html', **kwargs)
¶
Instantiate a DataDictTablePanel.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context_data_key
|
str
|
The key in the render context that stores the data used to populate the table. |
required |
columns
|
list
|
Ordered list of data keys used to order the columns of the rendered table.
Mutually exclusive with |
None
|
context_columns_key
|
str
|
The key in the render context that stores the columns list, if any.
Mutually exclusive with |
None
|
column_headers
|
list
|
List of column header labels, in the same order as |
None
|
context_column_headers_key
|
str
|
The key in the render context that stores the column headers.
Mutually exclusive with |
None
|
nautobot.apps.ui.DistinctViewTab
¶
Bases: Tab
A Tab that doesn't render inline on the same page, but instead links to a distinct view of its own when clicked.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
url_name
|
str
|
The name of the URL pattern to link to, which will be reversed to generate the URL. |
required |
label_wrapper_template_path
|
str
|
Template path to render the tab label to HTML. |
'components/tab/label_wrapper_distinct_view.html'
|
related_object_attribute
|
str
|
The name of the related object attribute to count for the tab label. |
''
|
nautobot.apps.ui.DropdownButton
¶
Bases: Button
A Button that has one or more other buttons as children
, which it renders into a dropdown menu.
__init__(children, template_path='components/button/dropdown.html', **kwargs)
¶
Initialize a DropdownButton component.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
children
|
list[Button]
|
Elements of the dropdown menu associated to this DropdownButton. |
required |
template_path
|
str
|
Dropdown-specific template file. |
'components/button/dropdown.html'
|
get_extra_context(context)
¶
Add the children of this DropdownButton to the other Button context.
nautobot.apps.ui.GroupedKeyValueTablePanel
¶
Bases: KeyValueTablePanel
A KeyValueTablePanel that displays its data within collapsible accordion groupings, such as object custom fields.
Expects data in the form {grouping1: {key1: value1, key2: value2, ...}, grouping2: {...}, ...}
.
The special grouping ""
may be used to indicate top-level key/value pairs that don't belong to a group.
nautobot.apps.ui.HomePageBase
¶
Bases: ABC
Base class for homepage layout classes.
nautobot.apps.ui.HomePageGroup
¶
Bases: HomePageBase
, PermissionsMixin
Defines properties that can be used for a panel group.
__init__(name, permissions=None, items=None, weight=1000)
¶
Ensure group properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name
|
str
|
The name of the group. |
required |
permissions
|
list
|
The permissions required to view this group. |
None
|
items
|
list
|
List of items to be rendered in this group. |
None
|
weight
|
int
|
The weight of this group. |
1000
|
nautobot.apps.ui.HomePageItem
¶
Bases: HomePageBase
, PermissionsMixin
Defines properties that can be used for a panel item.
__init__(name, link=None, model=None, custom_template=None, custom_data=None, description=None, permissions=None, weight=1000)
¶
Ensure item properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name
|
str
|
The name of the item. |
required |
link
|
str
|
The link to be used for this item. |
None
|
model
|
str
|
The model to being used for this item to calculate the total count of objects. |
None
|
custom_template
|
str
|
Name of custom template. |
None
|
custom_data
|
dict
|
Custom data to be passed to the custom template. |
None
|
nautobot.apps.ui.HomePagePanel
¶
Bases: HomePageBase
, PermissionsMixin
Defines properties that can be used for a panel.
__init__(name, permissions=None, custom_data=None, custom_template=None, items=None, weight=1000)
¶
Ensure panel properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name
|
str
|
The name of the panel. |
required |
permissions
|
list
|
The permissions required to view this panel. |
None
|
custom_data
|
dict
|
Custom data to be passed to the custom template. |
None
|
custom_template
|
str
|
Name of custom template. |
None
|
items
|
list
|
List of items to be rendered in this panel. |
None
|
weight
|
int
|
The weight of this panel. |
1000
|
nautobot.apps.ui.InstanceBreadcrumbItem
dataclass
¶
Bases: BaseBreadcrumbItem
Breadcrumb via object instance from context.
Detail url for object instance taken from context. By default, instance_key
is set to object
.
Label will be generated from object, but you can still override it.
Attributes:
Name | Type | Description |
---|---|---|
instance_key |
Optional[str]
|
Context key to fetch a Django model instance for building the breadcrumb. |
instance |
Callable[[Context], Optional[Model]
|
Callable to fetch the instance from context. If |
should_render |
Callable[[Context], bool]
|
Callable to decide whether this item should be rendered or not. |
label |
Union[Callable[[Context], str], WithStr, None]
|
Optional override for the display label in the breadcrumb. |
label_key |
Optional[str]
|
Optional key to take label from the context. |
Examples:
>>> InstanceBreadcrumbItem()
("/dcim/devices/1234", "My Device") # Assuming that under "object" there is a Device instance
>>> InstanceBreadcrumbItem(label="Custom Device Label")
("/dcim/devices/1234", "Custom Device Label") # Assuming that under "object" there is a Device instance
get_instance(context)
¶
Get the instance depending on the settings.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Type | Description |
---|---|
Optional[Model]
|
Optional[Model]: Instance from context. |
get_label(context)
¶
Get the label (display text) for the breadcrumb from instance.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
Label as a string. |
get_url(context)
¶
Resolve the URL for the breadcrumb item based on the instance.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Type | Description |
---|---|
Optional[str]
|
Optional[str]: The URL as a string, or None. |
nautobot.apps.ui.KeyValueTablePanel
¶
Bases: Panel
A panel that displays a two-column table of keys and values, as seen in most object detail views.
__init__(*, data=None, context_data_key=None, hide_if_unset=(), value_transforms=None, body_wrapper_template_path='components/panel/body_wrapper_key_value_table.html', **kwargs)
¶
Instantiate a KeyValueTablePanel.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data
|
dict
|
The dictionary of key/value data to display in this panel.
May be |
None
|
context_data_key
|
str
|
The render context key that will contain the data, if |
None
|
hide_if_unset
|
list
|
Keys that should be omitted from the display entirely if they have a falsey value, instead of displaying the usual em-dash placeholder text. |
()
|
value_transforms
|
dict
|
Dictionary of
|
None
|
get_data(context)
¶
Get the data for this panel, by default from self.data
or the key "data"
in the provided context.
Subclasses may need to override this method if the derivation of the data is more involved.
Returns:
Type | Description |
---|---|
dict
|
Key/value dictionary to be rendered in this panel. |
queryset_list_url_filter(key, value, context)
¶
Get a filter parameter to use when hyperlinking queryset data to an object list URL to provide filtering.
Returns:
Type | Description |
---|---|
str
|
A URL parameter string of the form |
The default implementation returns ""
, which means "no appropriate filter parameter is known,
do not hyperlink the queryset text." Subclasses may wish to override this to provide appropriate intelligence.
Examples:
- For a queryset of VRFs in a Location detail view for instance
aaf814ef-2ef6-463e-9440-54f6514afe0e
, this might return the string"locations=aaf814ef-2ef6-463e-9440-54f6514afe0e"
, resulting in the hyperlinked URL/ipam/vrfs/?locations=aaf814ef-2ef6-463e-9440-54f6514afe0e
- For a queryset of Devices associated to Circuit Termination
4182ce87-0f90-450e-a682-9af5992b4bb7
by a Relationship with keytermination_to_devices
, this might return the string"cr_termination_to_devices__source=4182ce87-0f90-450e-a682-9af5992b4bb7"
, resulting in the hyperlinked URL/dcim/devices/?cr_termination_to_device__source=4182ce87-0f90-450e-a682-9af5992b4bb7
render_body_content(context)
¶
Render key-value pairs as table rows, using render_key()
and render_value()
methods as applicable.
render_key(key, value, context)
¶
Render the provided key in human-readable form.
The default implementation simply replaces underscores with spaces and title-cases it with bettertitle()
.
render_value(key, value, context)
¶
Render the provided value in human-readable form.
Returns:
Type | Description |
---|---|
str
|
String or HTML representation of the given value. May return |
Behavior is influenced by:
self.value_transforms
- if it has an entry for the givenkey
, then the given functions provided there will be used to render thevalue
, in place of any default processing and rendering for this data type.self.hide_if_unset
- any key in this list, if having a corresponding value ofNone
, will be omitted from the display (returning""
instead of a placeholder).
There is a lot of "intelligence" built in to this method to handle various data types, including:
- Instances of TreeModel
will display the full path from root to node (using render_ancestor_hierarchy()
)
- Instances of Status
, Role
and similar models will be represented as an appropriately-colored hyperlinked
badge (using hyperlinked_object_with_color()
)
- Instances of Tenant
will be hyperlinked and will also display their hyperlinked TenantGroup
if any
- Instances of other models will be hyperlinked (using hyperlinked_object()
)
- Model QuerySets will render the first several objects in the QuerySet (as above), and if more objects are
present, and self.queryset_list_url_filter()
returns an appropriate filter string, will render the link to
the filtered list view of that model.
- Etc.
nautobot.apps.ui.LayoutChoices
¶
Bases: ChoiceSet
Page (or more properly tab) column layout choices.
Attributes:
Name | Type | Description |
---|---|---|
TWO_OVER_ONE |
str
|
Half-width panels will be above full-width panels (value: 2-over-1) |
ONE_OVER_TWO |
str
|
Full-width panels will be above half-width panels (value: 1-over-2) |
DEFAULT |
str
|
Two columns of half-width panels on top; full-width panels below. (value of TWO_OVER_ONE) |
nautobot.apps.ui.ModelBreadcrumbItem
dataclass
¶
Bases: BaseBreadcrumbItem
Breadcrumb via model class / instance / name.
Based on model class, content type or dotted model name passed directly or taken automatically from context.
It will generate label based on model verbose_name
or verbose_name_plural
depending on model_label_type
.
If label
is set explicitly, it's returned as-is or called if callable.
Attributes:
Name | Type | Description |
---|---|---|
model |
Union[str, Type[Model], None, Callable[[Context], Union[str, Type[Model], None]]
|
Django model class, instance, or dotted path string or callable that returns one of this. |
model_key |
Optional[str]
|
Context key to fetch a model class, instance or dotted path string. |
action |
str
|
Action to use when resolving a model-based route (default: "list"). |
label_type |
Literal['singular', 'plural']
|
Whether to use |
reverse_kwargs |
Union[dict[str, Any], Callable[[Context], dict[str, Any]], None]
|
Keyword arguments passed to |
reverse_query_params |
Union[dict[str, Any], Callable[[Context], dict[str, Any]], None]
|
Keyword arguments added to the url. |
should_render |
Callable[[Context], bool]
|
Callable to decide whether this item should be rendered or not. |
label |
Union[Callable[[Context], str], WithStr, None]
|
Optional override for the display label in the breadcrumb. |
label_key |
Optional[str]
|
Optional key to take label from the context. |
Examples:
>>> ModelBreadcrumbItem(model=Device)
("/dcim/devices/", "Devices")
>>> ModelBreadcrumbItem(model="dcim.device")
("/dcim/devices/", "Devices")
>>> ModelBreadcrumbItem(model="dcim.device", label_type="singular", action="add")
("/dcim/devices/add", "Device")
get_label(context)
¶
Get the display name from the model's metadata.
Depending on the model_label_type
, either the verbose_name
or verbose_name_plural
will be returned. Accepts model class, instance or dotted path string.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
The verbose name of the model class for use as a label. |
get_url(context)
¶
Get the URL for the breadcrumb item based on the configuration: model, action, reverse kwargs, query params.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Type | Description |
---|---|
Optional[str]
|
Optional[str]: The URL as a string, or None. |
nautobot.apps.ui.NavMenuAddButton
¶
nautobot.apps.ui.NavMenuBase
¶
Bases: ABC
Base class for navigation classes.
nautobot.apps.ui.NavMenuButton
¶
Bases: NavMenuBase
, PermissionsMixin
This class represents a button within a NavMenuItem.
fixed_fields
property
¶
Tuple of (name, attribute) entries describing fields that may not be altered after declaration.
initial_dict
property
¶
Attributes to be stored when adding this item to the nav menu data for the first time.
__init__(link, title, icon_class, button_class=ButtonActionColorChoices.DEFAULT, permissions=None, weight=1000, query_params=None)
¶
Ensure button properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
link
|
str
|
The link to be used for this button. |
required |
title
|
str
|
The title of the button. |
required |
icon_class
|
str
|
The icon class to be used as the icon for the start of the button. |
required |
button_class
|
str
|
The button class defines to be used to define the style of the button. |
DEFAULT
|
permissions
|
list
|
The permissions required to view this button. |
None
|
weight
|
int
|
The weight of this button. |
1000
|
query_params
|
dict
|
Query parameters to be appended to the URL. |
None
|
nautobot.apps.ui.NavMenuGroup
¶
Bases: NavMenuBase
, PermissionsMixin
Ths class represents a navigation menu group. This is built up from a name and a weight value. The name is the display text and the weight defines its position in the navbar.
Items are each specified as a list of NavMenuItem instances.
fixed_fields
property
¶
Tuple of (name, attribute) entries describing fields that may not be altered after declaration.
initial_dict
property
¶
Attributes to be stored when adding this item to the nav menu data for the first time.
__init__(name, items=None, weight=1000)
¶
Ensure group properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name
|
str
|
The name of the group. |
required |
items
|
list
|
List of items to be rendered in this group. |
None
|
weight
|
int
|
The weight of this group. |
1000
|
nautobot.apps.ui.NavMenuImportButton
¶
nautobot.apps.ui.NavMenuItem
¶
Bases: NavMenuBase
, PermissionsMixin
This class represents a navigation menu item. This constitutes primary link and its text, but also allows for specifying additional link buttons that appear to the right of the item in the nav menu.
Links are specified as Django reverse URL strings. Buttons are each specified as a list of NavMenuButton instances.
fixed_fields
property
¶
Tuple of (name, attribute) entries describing fields that may not be altered after declaration.
initial_dict
property
¶
Attributes to be stored when adding this item to the nav menu data for the first time.
__init__(link, name, args=None, kwargs=None, query_params=None, permissions=None, buttons=(), weight=1000)
¶
Ensure item properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
link
|
str
|
The link to be used for this item. |
required |
name
|
str
|
The name of the item. |
required |
args
|
list
|
Arguments that are being passed to the url with reverse() method |
None
|
kwargs
|
dict
|
Keyword arguments are are being passed to the url with reverse() method |
None
|
query_params
|
dict
|
Query parameters to be appended to the URL. |
None
|
permissions
|
list
|
The permissions required to view this item. |
None
|
buttons
|
list
|
List of buttons to be rendered in this item. |
()
|
weight
|
int
|
The weight of this item. |
1000
|
nautobot.apps.ui.NavMenuTab
¶
Bases: NavMenuBase
, PermissionsMixin
Ths class represents a navigation menu tab. This is built up from a name and a weight value. The name is the display text and the weight defines its position in the navbar.
Groups are each specified as a list of NavMenuGroup instances.
fixed_fields
property
¶
Tuple of (name, attribute) entries describing fields that may not be altered after declaration.
initial_dict
property
¶
Attributes to be stored when adding this item to the nav menu data for the first time.
__init__(name, permissions=None, groups=None, weight=1000)
¶
Ensure tab properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name
|
str
|
The name of the tab. |
required |
permissions
|
list
|
The permissions required to view this tab. |
None
|
groups
|
list
|
List of groups to be rendered in this tab. |
None
|
weight
|
int
|
The weight of this tab. |
1000
|
nautobot.apps.ui.ObjectDetailContent
¶
Base class for UI framework definition of the contents of an Object Detail (Object Retrieve) page.
This currently defines the tabs and their panel contents, but does NOT describe the page title, breadcrumbs, etc.
Basic usage for a NautobotUIViewSet
looks like:
from nautobot.apps.ui import ObjectDetailContent, ObjectFieldsPanel, SectionChoices
class MyModelUIViewSet(NautobotUIViewSet):
queryset = MyModel.objects.all()
object_detail_content = ObjectDetailContent(
panels=[ObjectFieldsPanel(section=SectionChoices.LEFT_HALF, weight=100, fields="__all__")],
)
A legacy ObjectView
can similarly define its own object_detail_content
attribute as well.
extra_buttons
property
writable
¶
The extra buttons defined for this detail view, ordered by their weight
.
tabs
property
writable
¶
The tabs defined for this detail view, ordered by their weight
.
__init__(*, panels=(), layout=LayoutChoices.DEFAULT, extra_buttons=None, extra_tabs=None)
¶
Create an ObjectDetailContent with a "main" tab and all standard "extras" tabs (advanced, contacts, etc.).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
panels
|
list
|
List of |
()
|
layout
|
str
|
One of the |
DEFAULT
|
extra_buttons
|
list
|
Optional list of |
None
|
extra_tabs
|
list
|
Optional list of |
None
|
nautobot.apps.ui.ObjectFieldsPanel
¶
Bases: KeyValueTablePanel
A panel that renders a table of object instance attributes and their values.
__init__(*, fields='__all__', exclude_fields=(), context_object_key=None, ignore_nonexistent_fields=False, label=None, **kwargs)
¶
Instantiate an ObjectFieldsPanel.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
fields
|
(str, list)
|
The ordered list of fields to display, or |
'__all__'
|
exclude_fields
|
list
|
Only relevant if |
()
|
context_object_key
|
str
|
The key in the render context that will contain the object to derive fields from. |
None
|
ignore_nonexistent_fields
|
bool
|
If True, |
False
|
label
|
str
|
If omitted, the provided object's |
None
|
get_data(context)
¶
Load data from the object provided in the render context based on the given set of fields
.
Returns:
Type | Description |
---|---|
dict
|
Key-value pairs corresponding to the object's fields, or |
render_key(key, value, context)
¶
Render the verbose_name
of the model field whose name corresponds to the given key, if applicable.
render_label(context)
¶
Default to rendering the provided object's verbose_name
if no more specific label
was defined.
nautobot.apps.ui.ObjectTextPanel
¶
Bases: BaseTextPanel
Panel that renders text, Markdown, JSON or YAML from the given field on the given object in the context.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
object_field
|
str
|
The name of the object field to be rendered. None by default. |
None
|
kwargs
|
dict
|
Additional keyword arguments passed to |
{}
|
nautobot.apps.ui.ObjectsTablePanel
¶
Bases: Panel
A panel that renders a Table of objects (typically related objects, rather than the "main" object of a view). Has built-in pagination support and "Add" button at bottom of the Table.
It renders the django-tables2 classes with Nautobot additions. You can pass the instance of Table Class
already configured in context and set the context_table_key
or pass a Table Class to __init__
via table_class
.
When table_class
is set, you need to pass table_filter
or table_attribute
for fetching data purpose.
Data fetching can be optimized by using select_related_fields
, prefetch_related_fields
.
How Table is displayed can be changed by using include_columns
, exclude_columns
, table_title
,
hide_hierarchy_ui
, related_field_name
or enable_bulk_actions
.
Please check the Args list for further details.
__init__(*, context_table_key=None, table_class=None, table_filter=None, table_attribute=None, select_related_fields=None, prefetch_related_fields=None, order_by_fields=None, table_title=None, max_display_count=None, paginate=True, show_table_config_button=True, include_columns=None, exclude_columns=None, add_button_route='default', add_permissions=None, hide_hierarchy_ui=False, related_field_name=None, enable_bulk_actions=False, tab_id=None, body_wrapper_template_path='components/panel/body_wrapper_table.html', body_content_template_path='components/panel/body_content_objects_table.html', header_extra_content_template_path='components/panel/header_extra_content_table.html', footer_content_template_path='components/panel/footer_content_table.html', footer_buttons=None, form_id=None, include_paginator=False, **kwargs)
¶
Instantiate an ObjectsTable panel.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context_table_key
|
str
|
The key in the render context that will contain an already-populated-and-configured
Table ( |
None
|
table_class
|
obj
|
The table class that will be instantiated and rendered e.g. CircuitTable, DeviceTable.
Mutually exclusive with |
None
|
table_filter
|
(str, list)
|
The filter(s) to apply to the queryset to initialize the table class.
For example, in a LocationType detail view, for an ObjectsTablePanel of related Locations, this would
be |
None
|
table_attribute
|
str
|
The attribute of the detail view instance that contains the queryset to
initialize the table class. e.g. |
None
|
select_related_fields
|
list
|
list of fields to pass to table queryset's |
None
|
prefetch_related_fields
|
list
|
list of fields to pass to table queryset's |
None
|
order_by_fields
|
list
|
list of fields to order the table queryset by. |
None
|
max_display_count
|
int
|
Maximum number of items to display in the table.
If None, defaults to the |
None
|
paginate
|
bool
|
If False, do not attach a paginator to the table and render all rows
(or up to |
True
|
show_table_config_button
|
bool
|
If False, hide the small "Configure" button rendered in the panel header for this table. Defaults to True. |
True
|
table_title
|
str
|
The title to display in the panel heading for the table. If None, defaults to the plural verbose name of the table model. |
None
|
include_columns
|
list
|
A list of field names to include in the table display. |
None
|
exclude_columns
|
list
|
A list of field names to exclude from the table display. |
None
|
add_button_route
|
str
|
The route used to generate the "add" button URL. Defaults to "default",
which uses the default table's model |
'default'
|
add_permissions
|
list
|
A list of permissions required for the "add" button to be displayed. If not provided, permissions are determined by default based on the model. |
None
|
hide_hierarchy_ui
|
bool
|
Don't display hierarchy-based indentation of tree models in this table |
False
|
related_field_name
|
str
|
The name of the filter/form field for the related model that links back
to the base model. Defaults to the same as |
None
|
enable_bulk_actions
|
bool
|
Show the pk toggle columns on the table if the user has the appropriate permissions. |
False
|
tab_id
|
str
|
The ID of the tab this panel belongs to. Used to append to a |
None
|
footer_buttons
|
list
|
A list of Button or FormButton components to render in the panel footer. These buttons typically perform actions like bulk delete, edit, or custom form submission. |
None
|
form_id
|
str
|
A unique ID for this table's form; used to set the |
None
|
include_paginator
|
bool
|
If True, renders a paginator in the panel footer. |
False
|
get_extra_context(context)
¶
Add additional context for rendering the table panel.
This method processes the table data, configures pagination, and generates URLs for listing and adding objects. It also handles field inclusion/exclusion and displays the appropriate table title if provided.
nautobot.apps.ui.Panel
¶
Bases: Component
Base class for defining an individual display panel within a Layout within a Tab.
__init__(*, label='', section=SectionChoices.FULL_WIDTH, body_id=None, body_content_template_path=None, header_extra_content_template_path=None, footer_content_template_path=None, template_path='components/panel/panel.html', body_wrapper_template_path='components/panel/body_wrapper_generic.html', **kwargs)
¶
Initialize a Panel component that can be rendered as a self-contained HTML fragment.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
label
|
str
|
Label to display for this panel. Optional; if an empty string, the panel will have no label. |
''
|
section
|
str
|
One of the |
FULL_WIDTH
|
body_id
|
str
|
HTML element |
None
|
body_content_template_path
|
str
|
Template path to render the content contained within the panel body. |
None
|
header_extra_content_template_path
|
str
|
Template path to render extra content into the panel header, if any, not including its label if any. |
None
|
footer_content_template_path
|
str
|
Template path to render content into the panel footer, if any. |
None
|
template_path
|
str
|
Template path to render the Panel as a whole. Generally you won't override this. |
'components/panel/panel.html'
|
body_wrapper_template_path
|
str
|
Template path to render the panel body, including both its "wrapper"
(a |
'components/panel/body_wrapper_generic.html'
|
render(context)
¶
Render the panel as a whole.
Default implementation calls render_label()
, render_header_extra_content()
, render_body()
,
and render_footer_extra_content()
, then wraps them all into the templated defined by self.template_path
.
Typically you'll override one or more of the aforementioned methods in a subclass, rather than replacing this entire method as a whole.
render_body(context)
¶
Render the panel body including its HTML wrapper element(s).
Default implementation calls render_body_content()
and wraps that in the template defined at
self.body_wrapper_template_path
.
Normally you won't want to override this method in a subclass, instead overriding render_body_content()
.
render_body_content(context)
¶
Render the content to include in this panel's body.
Default implementation renders the template from self.body_content_template_path
if any.
render_footer_content(context)
¶
Render any non-default content to include in this panel's footer.
Default implementation renders the template from self.footer_content_template_path
if any.
render_header_extra_content(context)
¶
Render any additional (non-label) content to include in this panel's header.
Default implementation renders the template from self.header_extra_content_template_path
if any.
render_label(context)
¶
Render the label of this panel, if any.
nautobot.apps.ui.PermissionsMixin
¶
Ensure permissions through init.
__init__(permissions=None)
¶
Ensure permissions.
nautobot.apps.ui.SectionChoices
¶
Bases: ChoiceSet
Sections of a Layout to assign panels to. Placement of panels is determined by LayoutChoices
set on Tab.layout
Attributes:
Name | Type | Description |
---|---|---|
LEFT_HALF |
str
|
Left side, half-width (value: left-half) |
RIGHT_HALF |
str
|
Right side, half-width (value: right-half) |
FULL_WIDTH |
str
|
Full width (value: full-width) |
nautobot.apps.ui.StatsPanel
¶
Bases: Panel
__init__(*, filter_name, related_models=None, body_content_template_path='components/panel/stats_panel_body.html', **kwargs)
¶
Instantiate a StatsPanel
.
filter_name (str) is a valid query filter append to the anchor tag for each stat button.
e.g. the tenant
query parameter in the url /circuits/circuits/?tenant=f4b48e9d-56fc-4090-afa5-dcbe69775b13
.
related_models is a list of model classes and/or tuples of (model_class, query_string).
e.g. [Device, Prefix, (Circuit, "circuit_terminations__location__in"), (VirtualMachine, "cluster__location__in")]
render_body_content(context)
¶
Transform self.related_models to a dictionary with key, value pairs as follows:
{
should_render(context)
¶
Always should render this panel as the permission is reinforced in python with .restrict(request.user, "view")
nautobot.apps.ui.Tab
¶
Bases: Component
Base class for UI framework definition of a single tabbed pane within an Object Detail (Object Retrieve) page.
__init__(*, tab_id, label, panels=(), layout=LayoutChoices.DEFAULT, label_wrapper_template_path='components/tab/label_wrapper.html', content_wrapper_template_path='components/tab/content_wrapper.html', **kwargs)
¶
Initialize a Tab component.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tab_id
|
str
|
HTML ID for the tab content element, used to link the tab label and its content together. |
required |
label
|
str
|
User-facing label to display for this tab. |
required |
panels
|
tuple
|
Set of |
()
|
layout
|
str
|
One of the LayoutChoices values, describing the layout of panels within this tab. |
DEFAULT
|
label_wrapper_template_path
|
str
|
Template path to use for rendering the tab label to HTML. |
'components/tab/label_wrapper.html'
|
content_wrapper_template_path
|
str
|
Template path to use for rendering the tab contents to HTML. |
'components/tab/content_wrapper.html'
|
panels_for_section(section)
¶
Get the subset of this tab's panels that apply to the given layout section, ordered by their weight
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
section
|
str
|
One of |
required |
Returns:
Type | Description |
---|---|
list[Panel]
|
Sorted list of Panel instances. |
render(context)
¶
Render the tab's contents (layout and panels) to HTML.
render_label(context)
¶
Render the tab's label text in a form suitable for display to the user.
Defaults to just returning self.label
, but may be overridden if context-specific formatting is needed.
render_label_wrapper(context)
¶
Render the tab's label (as opposed to its contents) and wrapping HTML elements.
In most cases you should not need to override this method; override render_label()
instead.
nautobot.apps.ui.TemplateExtension
¶
This class is used to register App content to be injected into core Nautobot templates.
It contains methods and attributes that may be overridden by App authors to return template content.
The model
attribute on the class defines the which model detail/list pages this class renders content for.
It should be set as a string in the form <app_label>.<model_name>
.
model = None
class-attribute
instance-attribute
¶
The model (as a string in the form <app_label>.<model>
) that this TemplateExtension subclass applies to.
object_detail_buttons = None
class-attribute
instance-attribute
¶
List of Button instances to add to the specified model's detail view.
object_detail_panels = None
class-attribute
instance-attribute
¶
List of Panel instances to add to the specified model's detail view.
object_detail_tabs = None
class-attribute
instance-attribute
¶
List of Tab instances to add to the specified model's detail view.
__init__(context)
¶
Called automatically to instantiate a TemplateExtension with render context before calling left_page()
, etc.
The provided context typically includes the following keys:
- object - The object being viewed
- request - The current request
- settings - Global Nautobot settings
- config - App-specific configuration parameters
buttons()
¶
(Deprecated) Provide content that will be added to the existing list of buttons on the detail page view.
In Nautobot v2.4.0 and later, Apps can (should) instead register Button
instances in object_detail_buttons
,
instead of implementing a .buttons()
method.
Content should be returned as an HTML string. Note that content does not need to be marked as safe because this is automatically handled.
detail_tabs()
¶
(Deprecated) Provide a dict of tabs and associated views that will be added to the detail page view.
In Nautobot v2.4.0 and later, Apps can (should) instead implement the object_detail_tabs
attribute instead.
Tabs will be ordered by their position in the list.
Content should be returned as a list of dicts in the following format:
full_width_page()
¶
(Deprecated) Provide content that will be rendered within the full width of the detail page view.
In Nautobot v2.4.0 and later, Apps can (should) instead register Panel
instances in object_detail_panels
,
instead of implementing a .full_width_page()
method.
Content should be returned as an HTML string. Note that content does not need to be marked as safe because this is automatically handled.
left_page()
¶
(Deprecated) Provide content that will be rendered on the left of the detail page view.
In Nautobot v2.4.0 and later, Apps can (should) instead register Panel
instances in object_detail_panels
,
instead of implementing a .left_page()
method.
Content should be returned as an HTML string. Note that content does not need to be marked as safe because this is automatically handled.
list_buttons()
¶
Buttons that will be rendered and added to the existing list of buttons on the list page view. Content should be returned as an HTML string. Note that content does not need to be marked as safe because this is automatically handled.
render(template_name, extra_context=None)
¶
Convenience method for rendering the specified Django template using the default context data. An additional
context dictionary may be passed as extra_context
.
right_page()
¶
(Deprecated) Provide content that will be rendered on the right of the detail page view.
In Nautobot v2.4.0 and later, Apps can (should) instead register Panel
instances in object_detail_panels
,
instead of implementing a .right_page()
method.
Content should be returned as an HTML string. Note that content does not need to be marked as safe because this is automatically handled.
nautobot.apps.ui.TextPanel
¶
Bases: BaseTextPanel
Panel that renders text, Markdown, JSON or YAML from the given value in the context.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context_field
|
str
|
source field from context with value for |
'text'
|
kwargs
|
dict
|
Additional keyword arguments passed to |
{}
|
nautobot.apps.ui.Titles
¶
Base class for document titles and page headings.
This class provides a mechanism to define per-action title templates.
Titles can be dynamically rendered using context variables and template tags using the Django template engine and context.
Use the render()
method to obtain either rich (HTML) or plain (stripped of HTML) output.
There is a dedicated simple tag to render Titles
passed in the context['view_titles']
: {% render_title mode="html" %}
Attributes:
Name | Type | Description |
---|---|---|
titles |
dict[str, str]
|
Action-to-title-template mapping. |
template_plugins |
list[str]
|
List of Django template libraries to load before rendering. |
Parameters:
Name | Type | Description | Default |
---|---|---|---|
template_plugins
|
Optional[list[str]]
|
Template libraries to load into rendering. |
None
|
titles
|
dict
|
Action-to-template-string mappings that override or extend the defaults. |
None
|
template_plugins_str
property
¶
Return a concatenated string of Django {% load ... %} tags for all template plugins.
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
String containing {% load ... %} tags for the required template libraries. |
__init__(template_plugins=None, titles=None)
¶
Keyword arguments passed can either add new action-title pair or override existing titles.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
template_plugins
|
Optional[list[str]]
|
Extra Django template libraries to load before rendering. |
None
|
titles
|
Optional[dict[str, str]]
|
Custom or overriding mappings from action to template string. |
None
|
get_extra_context(context)
¶
Provide additional data to include in the rendering context, based on the configuration of this component.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Type | Description |
---|---|
dict
|
Additional context data. |
get_template_str(context)
¶
Determine the template string for the current action.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
Render context. |
required |
Returns:
Name | Type | Description |
---|---|---|
str |
str
|
The template string for the current action, or an empty string if not found. |
render(context, mode='html')
¶
Renders the title based on given context and current action.
If mode == "plain", the output will be stripped of HTML tags.
Make sure that needed context variables are in context and needed plugins are loaded.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
Render context. |
required |
mode
|
ModeType
|
Rendering mode: "html" or "plain". |
'html'
|
Returns:
Type | Description |
---|---|
str
|
HTML fragment or plain text, depending on |
nautobot.apps.ui.ViewNameBreadcrumbItem
dataclass
¶
Bases: BaseBreadcrumbItem
Breadcrumb via raw view name and optional params.
From raw viewname string that will be passed to the reverse method. You can pass reverse kwargs or query params. Label won't be generated automatically.
Attributes:
Name | Type | Description |
---|---|---|
view_name |
Union[str, Callable[[Context], str], None]
|
Django view name to reverse or callable taking context.
Can be used as fallback if |
view_name_key |
Optional[str]
|
(Optional[str]): Key to get the |
reverse_kwargs |
Union[dict[str, Any], Callable[[Context], dict[str, Any]], None]
|
Keyword arguments passed to |
reverse_query_params |
Union[dict[str, Any], Callable[[Context], dict[str, Any]], None]
|
Keyword arguments added to the url. |
should_render |
Callable[[Context], bool]
|
Callable to decide whether this item should be rendered or not. |
label |
Union[Callable[[Context], str], WithStr, None]
|
Optional override for the display label in the breadcrumb. |
label_key |
Optional[str]
|
Optional key to take label from the context. |
label_from_view_name |
bool
|
Try to resolve given view name and get the label from assosiacted model. |
Examples:
>>> ViewNameBreadcrumbItem(view_name="dcim:device_list")
("/dcim/devices/", "") # No label automatically generated
>>> ViewNameBreadcrumbItem(view_name="dcim:device_list", reverse_query_params={"filter": "some_value"}, label="Link")
("/dcim/devices/?filter=some_value", "Link")
get_url(context)
¶
Get the URL for the breadcrumb item based on the configuration: view name, context, reverse kwargs, query params.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
context
|
Context
|
The current template context. |
required |
Returns:
Type | Description |
---|---|
Optional[str]
|
Optional[str]: The URL as a string, or None. |
nautobot.apps.ui.render_component_template(template_path, context, **kwargs)
¶
Render the template located at the given path with the given context, possibly augmented via additional kwargs.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
template_path
|
str
|
Path to the template to render, for example |
required |
context
|
Context
|
Rendering context for the template |
required |
**kwargs
|
dict
|
Additional key/value pairs to extend the context with for this specific template. |
{}
|
Examples: