Skip to content

# `nautobot.apps.ui`

Utilities for apps to integrate with and extend the existing Nautobot UI.

## `nautobot.apps.ui.AncestorsBreadcrumbs`

Bases: `Breadcrumbs`

Breadcrumbs class which can render list of ancestors of given instance.

Default behavior: - render breadcrumb item with link to the list view - dynamically add list of `InstanceBreadcrumbItem` from `ancestors()` - adds standard breadcrumb item with link to the details

### `get_ancestors_items(instance)`

Create breadcrumb items for all ancestor objects of the given instance.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`instance` | `TreeModel` | Object from context. | required

Returns:

Type | Description
--- | ---
`list[BaseBreadcrumbItem]` | list[BaseBreadcrumbItem]: Breadcrumb items for each ancestor of the instance.

### `get_detail_items(context)`

Build breadcrumb items for a detail view, including the model, its ancestors, and the instance itself.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`context` | `Context` | Template or view context containing the current object. | required

Returns:

Type | Description
--- | ---
`list[BaseBreadcrumbItem]` | list[BaseBreadcrumbItem]: Ordered breadcrumb items for the given instance.

### `get_items_for_action(items, action, detail, context)`

Get the breadcrumb items for a specific action, 'detail' or to asterisk (*) if present.

For detail action it calls `self.get_detail_items()` method. For other actions, it calls parent class method.

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
`context` | `Context` | The view or template context. | required

Returns:

Type | Description
--- | ---
`list[BaseBreadcrumbItem]` | list[BaseBreadcrumbItem]: List of breadcrumb items for the action.

## `nautobot.apps.ui.AsyncStatsPanel`

Bases: `Panel`

### `__init__(*, api_url_name, body_content_template_path='components/panel/async_stats_panel_body.html', **kwargs)`

Instantiate an `AsyncStatsPanel`.

This appears like a regular `StatsPanel`, but (to improve UI performance and UX in cases where the stats tabulation may be time-consuming) makes a separate AJAX call to the given `api_url_name` to retrieve the stats, and populates the panel client-side with the response.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`api_url_name` | `str` | The API URL to call, e.g. `"dcim-api:location_stats"`. This API is expected to return, at minimum, a list of dicts, where each child dict has keys `title`, `count`, and `ui_url`. Refer to `StatsSerializer` and `LocationViewSet.stats` for an example implementation. | required

### `should_render(context)`

Always render this panel.

## `nautobot.apps.ui.Banner`

Class that may be returned by a registered plugin_banners function.

## `nautobot.apps.ui.BannerClassChoices`

Bases: `ChoiceSet`

Styling choices for custom banners.

## `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 formatting 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.

### `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 `Panel.__init__`. | `{}`

## `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").

Special breadcrumb item actions

- `*` - if no other action was found, items from `*` will be used
- `detail` action is used when there is no dedicated action for given request and there is `context['detail'] = True` set in context

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='components/breadcrumbs.html', detail_item_label=None)`

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. | `'components/breadcrumbs.html'`
`detail_item_label` | `Union[Callable[[Context], str], WithStr, None]` | Custom label for last built-in breadcrumb item with link to the object details. | `None`

### `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 pairs. | 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 `view_action` and related state. | 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 `render()`. | required

Returns:

Type | Description
--- | ---
`dict` | A dictionary of extra context variables.

### `get_items_for_action(items, action, detail, context)`

Get the breadcrumb items for a specific action, 'detail' or 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
`context` | `Context` | The view or template context. | 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', javascript_template_path=None, attributes=None, size=None, link_includes_pk=True, context_object_key=None, render_on_tab_id='__all__', **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 `reverse()` call when the button is rendered. For more complex link construction, you can subclass this and override the `get_link()` method. | `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 `"mdi-plus-bold"`. | `None`
`template_path` | `str` | Template to render for this button. | `'components/button/default.html'`
`javascript_template_path` | `str` | JavaScript template to render and include with this button. Does not need to include the wrapping `<script>...</script>` tags as those will be added automatically. | `None`
`attributes` | `dict` | Additional HTML attributes and their values to attach to the button. | `None`
`size` | `str` | The size of the button (e.g. `xs` or `sm`), used to apply a Bootstrap-style sizing. | `None`
`render_on_tab_id` | `str` | The (only) tab that this button should appear on. | `'__all__'`

### `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.

## `nautobot.apps.ui.ButtonColorChoices`

Bases: `ChoiceSet`

Map standard button color choices to Bootstrap color classes

## `nautobot.apps.ui.Component`

Common base class for renderable components (tabs, panels, etc.).

### `__init__(*, weight, required_permissions=None)`

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
`required_permissions` | `list` | Permissions such as `["dcim.add_consoleport"]`. The component will only be rendered if the user has these permissions. | `None`

### `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 `format_html()` or `format_html_join()`.

### `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.

The default implementation here checks for `self.required_permissions` if any.

Returns:

Type | Description
--- | ---
`bool` | `True` (default) if this component should be rendered.

## `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 DataTablePanel.

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 `context_columns_key`. If neither are specified, the keys of the first dict in the data will be used. | `None`
`context_columns_key` | `str` | The key in the render context that stores the columns list, if any. Mutually exclusive with `columns`. If neither are specified, the keys of the first dict in the data will be used. | `None`
`column_headers` | `list` | List of column header labels, in the same order as `columns` data. Mutually exclusive with `context_column_headers_key`. | `None`
`context_column_headers_key` | `str` | The key in the render context that stores the column headers. Mutually exclusive with `column_headers`. | `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. | `''`
`hide_if_empty` | `bool` | Do not render this tab if the related_object_attribute is an empty queryset. | `False`

### `should_render_content(context)`

A DistinctViewTab should only render its content if the view in question is active.

## `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.

### `render_body_content(context)`

Render groups of key-value pairs to HTML.

### `render_header_extra_content(context)`

Add a "Collapse All" button to the header.

## `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. Default: "object".
`instance` | `Union[Callable[[Context], Optional[Model]], Model, None]` | 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.InstanceParentBreadcrumbItem` `dataclass`

Bases: `InstanceBreadcrumbItem`

Breadcrumb item prepared to be "parent" or "group" of given model.

It will create a breadcrumb item to the object list but will try to filter it by given parent.

Attributes:

Name | Type | Description
--- | --- | ---
`parent_key` | `str` | Instance attribute to get the parent instance. Default: "parent".
`parent_query_param` | `Optional[str]` | Query param name under which parent lookup key will be added into breadcrumb url. If None, will be the same as `parent_key`.
`parent_lookup_key` | `Optional[str]` | Parent attribute which will be used to build the url and filter the instance list url. Can be set to None to use parent as key.

Examples:

    >>> InstanceParentBreadcrumbItem()
    ("/dcim/devices?parent=<parent.pk>", "Parent")  # Assuming that under "object" there is a Device instance and has "parent"
    >>> InstanceParentBreadcrumbItem(parent_key="group", parent_lookup_key="name")
    ("/dcim/devices?group=<group_name>", "Group")  # Assuming that under "object" there is a Device instance and has "group"

### `__post_init__()`

Set `parent_query_param` if not filled.

### `get_label(context)`

Get the label (display text) for the breadcrumb from instance and provided parent.

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 and provided parent.

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, key_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` if it will be derived dynamically by `get_data()` or from `context_data_key` instead. | `None`
`context_data_key` | `str` | The render context key that will contain the data, if `data` wasn't provided. | `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 `{key: [list of transform functions]}`, used to specify custom rendering of specific key values without needing to implement a new subclass for this purpose. Many of the `templatetags.helpers` functions are suitable for this purpose; examples: `[render_markdown, placeholder]` - render the given text as Markdown, or render a placeholder if blank `[humanize_speed, placeholder]` - convert the given kbps value to Mbps or Gbps for display | `None`
`key_transforms` | `dict` | A mapping of original field names to custom display names to be used when rendering keys For example: {'content_types': 'Content Type'}. | `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 `"filter=value"`, or `""` if none is known.

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 key `termination_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 `""` to indicate that this value should be skipped entirely, i.e. not displayed in the table at all. May return `placeholder(value)` to display a consistent placeholder representation of any unset value.

Behavior is influenced by:

- `self.value_transforms` - if it has an entry for the given `key`, then the given functions provided there will be used to render the `value`, 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 of `None`, 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. By default: "object".
`action` | `str` | Action to use when resolving a model-based route (default: "list").
`label_type` | `Literal['singular', 'plural']` | Whether to use `verbose_name` or `verbose_name_plural`.
`reverse_kwargs` | `Union[dict[str, Any], Callable[[Context], dict[str, Any]], None]` | Keyword arguments passed to `reverse()`.
`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`

Bases: `NavMenuButton`

Add button subclass.

### `__init__(*args, **kwargs)`

Ensure button properties.

## `nautobot.apps.ui.NavMenuBase`

Bases: `ABC`

Base class for navigation classes.

### `fixed_fields` `abstractmethod` `property`

Tuple of (name, attribute) entries describing fields that may not be altered after declaration.

### `initial_dict` `abstractmethod` `property`

Attributes to be stored when adding this item to the nav menu data for the first time.

## `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`

Bases: `NavMenuButton`

Import button subclass.

### `__init__(*args, **kwargs)`

Ensure button properties.

## `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 `Panel` instances to include in this layout by default. Standard `extras` Panels (custom fields, relationships, etc.) do not need to be specified as they will be automatically included. | `()`
`layout` | `str` | One of the `LayoutChoices` values, indicating the layout of the "main" tab for this view. | `DEFAULT`
`extra_buttons` | `list` | Optional list of `Button` instances. Standard detail-view "actions" dropdown (clone, edit, delete) does not need to be specified as it will be automatically included. | `None`
`extra_tabs` | `list` | Optional list of `Tab` instances. Standard `extras` Tabs (advanced, contacts, dynamic-groups, metadata, etc.) do not need to be specified as they will be automatically included. | `None`

## `nautobot.apps.ui.ObjectFieldsPanel`

Bases: `KeyValueTablePanel`

A panel that renders a table of object instance attributes and their values.

### `__init__(*, fields='__all__', additional_fields=(), 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__"` to display fields automatically. Note that ManyToMany fields and reverse relations are not included in `"__all__"` at this time, nor are any hidden fields, nor the specially handled `id`, `created`, `last_updated` fields on most models. When a list is specified, it may include model `@property` attributes and nested lookups (if desired) in addition to concrete model fields; when using `fields="__all__"`, such additional attributes and lookups may be specified with the `additional_fields` parameter. | `'__all__'`
`additional_fields` | `list` | Only relevant if `fields == "__all__"`, in which case it can specify additional non-default fields to include such as reverse relations, `@property` attributes, nested lookups, etc. | `()`
`exclude_fields` | `list` | Only relevant if `fields == "__all__"`, in which case it excludes the given fields. | `()`
`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, `fields` is permitted to include field names that don't actually exist on the provided object; otherwise an exception will be raised at render time. | `False`
`label` | `str` | If omitted, the provided object's `verbose_name` will be rendered as the label (see `render_label()`). | `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 `{}` if no object is present.

### `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 `BaseTextPanel.__init__`. | `{}`

## `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, distinct=False, 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 (`BaseTable`) instance. Mutually exclusive with `table_class`, `table_filter`, `table_attribute`. | `None`
`table_class` | `obj` | The table class that will be instantiated and rendered e.g. CircuitTable, DeviceTable. Mutually exclusive with `context_table_key`. | `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 `location_type`, because `Location.objects.filter(location_type=obj)` gives the desired queryset. Mutually exclusive with `table_attribute`. For example, in ProviderNetwork detail view, for an ObjectsTablePanel of related Circuits, this would be `["circuit_termination_a__provider_network", "circuit_termination_z__provider_network"]` because `Circuit.objects.filter(Q(circuit_termination_a__provider_network=instance) | Q(circuit_termination_z__provider_network=instance))` gives the desired queryset. | `None`
`table_attribute` | `str` | The attribute of the detail view instance that contains the queryset to initialize the table class. e.g. `dynamic_groups`. Mutually exclusive with `table_filter`. | `None`
`distinct` | `bool` | If True, apply `.distinct()` to the table queryset. | `False`
`select_related_fields` | `list` | list of fields to pass to table queryset's `select_related` method. | `None`
`prefetch_related_fields` | `list` | list of fields to pass to table queryset's `prefetch_related` method. | `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 `get_paginate_count()` (which is user's preference or a global setting). | `None`
`paginate` | `bool` | If False, do not attach a paginator to the table and render all rows (or up to `max_display_count` if provided). Defaults to True. | `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 `add` route. | `'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 `table_filter` if unset. Used to populate URLs. | `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 `return_url` when users navigate away from the tab and redirect them back to the correct one. | `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 `data-form-id` attribute on each `FormButton`. | `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='', css_class='default', 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. | `''`
`css_class` | `str` | Panel variant to render as, e.g. "default", "warning", "info". | `'default'`
`section` | `str` | One of the `SectionChoices` values, indicating the layout section this Panel belongs to. | `FULL_WIDTH`
`body_id` | `str` | HTML element `id` to attach to the rendered body wrapper of the panel. | `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 `div` or `table`) as well as its contents. Generally you won't override this as a user. | `'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`.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`filter_name` | `str` | 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`. | required
`related_models` | `str` | a list of model classes and/or tuples of (model_class, query_string). e.g. `[Device, Prefix, (Circuit, "circuit_terminations__location__in")]` | `None`

### `render_body_content(context)`

Transform self.related_models to a dictionary with key, value pairs as follows: { : [related_object_model_class_list_url_1, related_object_count_1, related_object_title_1], : [related_object_model_class_list_url_2, related_object_count_2, related_object_title_2], : [related_object_model_class_list_url_3, related_object_count_3, related_object_title_3], ... }

### `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 `Panel` components to potentially display within this tab. | `()`
`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 `SectionChoices`. | 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.

### `should_render_content(context)`

Only render a main-view Tab if the active request is for the main object view rather than a separate action.

## `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:

    [
        {
            "title": "<title>",
            "url": "<url for the tab link>",
        },
        {
            "title": "<title>",
            "url": "<url for the tab link>",
        },
    ]

### `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 `TextPanel`. | `'text'`
`kwargs` | `dict` | Additional keyword arguments passed to `BaseTextPanel.__init__`. | `{}`

## `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` | `Union[dict, Context]` | Render context. | required
`mode` | `ModeType` | Rendering mode: "html" or "plain". | `'html'`

Returns:

Type | Description
--- | ---
`str` | HTML fragment or plain text, depending on `mode`.

## `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` won't be found in the context.
`view_name_key` | `Optional[str]` | (Optional[str]): Key to get the `view_name` from the context.
`reverse_kwargs` | `Union[dict[str, Any], Callable[[Context], dict[str, Any]], None]` | Keyword arguments passed to `reverse()`.
`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.context_object_attr(attr_path, context_key='object')`

Helper function that creates callable to fetch the object from context and then nested attributes.

Useful for composing breadcrumbs. For example:

    context = Context({"object": Device.objects.first()})
    breadcrumbs = Breadcrumbs(items={"detail": [
        InstanceBreadcrumbItem(instance=context_object_attr("location.location_type")),
        InstanceBreadcrumbItem(instance=context_object_attr("location")),
    ]})

Will render: - url to the device.location.location_type detail page - url to the device.location detail page

Examples:

    >>> context_object_attr("location.name")
    lambda context: context['object'].location.name
    >>> context_object_attr("location.name", context_key="device")
    lambda context: context['device'].location.name

## `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 `"components/tab/label_wrapper.html"`. | 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:

    >>> render_component_template(self.label_wrapper_template_path, context, tab_id=self.tab_id, label="Hello")