nautobot.apps.ui - Nautobot Documentation

Skip to content

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

Source code in `nautobot/extras/plugins/__init__.py`

    377
    378
    379
    380
    381
    382
    383
    384
    class Banner:
        """Class that may be returned by a registered plugin_banners function."""

        def __init__(self, content, banner_class=BannerClassChoices.CLASS_INFO):
            self.content = content
            if banner_class not in BannerClassChoices.values():
                raise ValueError("Banner class must be a choice within BannerClassChoices.")
            self.banner_class = banner_class

## `nautobot.apps.ui.BannerClassChoices`

Bases: `ChoiceSet`

Styling choices for custom banners.

Source code in `nautobot/extras/choices.py`

    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    class BannerClassChoices(ChoiceSet):
        """Styling choices for custom banners."""

        CLASS_SUCCESS = "success"
        CLASS_INFO = "info"
        CLASS_WARNING = "warning"
        CLASS_DANGER = "danger"

        CHOICES = (
            (CLASS_SUCCESS, "Success"),
            (CLASS_INFO, "Info"),
            (CLASS_WARNING, "Warning"),
            (CLASS_DANGER, "Danger"),
        )

## `nautobot.apps.ui.ButtonColorChoices`

Bases: `ChoiceSet`

Map standard button color choices to Bootstrap color classes

Source code in `nautobot/core/choices.py`

    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    class ButtonColorChoices(ChoiceSet):
        """
        Map standard button color choices to Bootstrap color classes
        """

        DEFAULT = "default"
        BLUE = "primary"
        GREY = "secondary"
        GREEN = "success"
        RED = "danger"
        YELLOW = "warning"
        BLACK = "dark"

        CHOICES = (
            (DEFAULT, "Default"),
            (BLUE, "Blue"),
            (GREY, "Grey"),
            (GREEN, "Green"),
            (RED, "Red"),
            (YELLOW, "Yellow"),
            (BLACK, "Black"),
        )

## `nautobot.apps.ui.HomePageBase`

Bases: `ABC`

Base class for homepage layout classes.

Source code in `nautobot/core/apps/__init__.py`

    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    class HomePageBase(ABC):
        """Base class for homepage layout classes."""

        @property
        @abstractmethod
        def initial_dict(self):  # to be implemented by each subclass
            return {}

        @property
        @abstractmethod
        def fixed_fields(self):  # to be implemented by subclass
            return ()

## `nautobot.apps.ui.HomePageGroup`

Bases: `HomePageBase`, `PermissionsMixin`

Defines properties that can be used for a panel group.

Source code in `nautobot/core/apps/__init__.py`

    336
    337
    338
    339
    340
    341
    342
    343
    344
    345
    346
    347
    348
    349
    350
    351
    352
    353
    354
    355
    356
    357
    358
    359
    360
    361
    362
    363
    364
    365
    366
    367
    368
    369
    370
    371
    372
    class HomePageGroup(HomePageBase, PermissionsMixin):
        """Defines properties that can be used for a panel group."""

        items = []

        @property
        def initial_dict(self):
            return {
                "items": {},
                "permissions": self.permissions,
                "weight": self.weight,
            }

        @property
        def fixed_fields(self):
            return ()

        def __init__(self, name, permissions=None, items=None, weight=1000):
            """
            Ensure group properties.

            Args:
                name (str): The name of the group.
                permissions (list): The permissions required to view this group.
                items (list): List of items to be rendered in this group.
                weight (int): The weight of this group.
            """
            super().__init__(permissions)
            self.name = name
            self.weight = weight

            if items is not None:
                if not isinstance(items, (list, tuple)):
                    raise TypeError("Items must be passed as a tuple or list.")
                elif not all(isinstance(item, HomePageItem) for item in items):
                    raise TypeError("All items defined in a group must be an instance of HomePageItem")
                self.items = items

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

Source code in `nautobot/core/apps/__init__.py`

    353
    354
    355
    356
    357
    358
    359
    360
    361
    362
    363
    364
    365
    366
    367
    368
    369
    370
    371
    372
    def __init__(self, name, permissions=None, items=None, weight=1000):
        """
        Ensure group properties.

        Args:
            name (str): The name of the group.
            permissions (list): The permissions required to view this group.
            items (list): List of items to be rendered in this group.
            weight (int): The weight of this group.
        """
        super().__init__(permissions)
        self.name = name
        self.weight = weight

        if items is not None:
            if not isinstance(items, (list, tuple)):
                raise TypeError("Items must be passed as a tuple or list.")
            elif not all(isinstance(item, HomePageItem) for item in items):
                raise TypeError("All items defined in a group must be an instance of HomePageItem")
            self.items = items

## `nautobot.apps.ui.HomePageItem`

Bases: `HomePageBase`, `PermissionsMixin`

Defines properties that can be used for a panel item.

Source code in `nautobot/core/apps/__init__.py`

    375
    376
    377
    378
    379
    380
    381
    382
    383
    384
    385
    386
    387
    388
    389
    390
    391
    392
    393
    394
    395
    396
    397
    398
    399
    400
    401
    402
    403
    404
    405
    406
    407
    408
    409
    410
    411
    412
    413
    414
    415
    416
    417
    418
    419
    420
    421
    422
    423
    424
    425
    426
    427
    428
    429
    430
    class HomePageItem(HomePageBase, PermissionsMixin):
        """Defines properties that can be used for a panel item."""

        items = []
        template_path = None

        @property
        def initial_dict(self):
            return {
                "custom_template": self.custom_template,
                "custom_data": self.custom_data,
                "description": self.description,
                "link": self.link,
                "model": self.model,
                "permissions": self.permissions,
                "template_path": self.template_path,
                "weight": self.weight,
            }

        @property
        def fixed_fields(self):
            return ()

        def __init__(
            self,
            name,
            link=None,
            model=None,
            custom_template=None,
            custom_data=None,
            description=None,
            permissions=None,
            weight=1000,
        ):
            """
            Ensure item properties.

            Args:
                name (str): The name of the item.
                link (str): The link to be used for this item.
                model (str): The model to being used for this item to calculate the total count of objects.
                custom_template (str): Name of custom template.
                custom_data (dict): Custom data to be passed to the custom template.
            """
            super().__init__(permissions)

            self.name = name
            self.custom_template = custom_template
            self.custom_data = custom_data
            self.description = description
            self.link = link
            self.model = model
            self.weight = weight

            if model is not None and custom_template is not None:
                raise ValueError("Cannot specify model and custom_template at the same time.")

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

Source code in `nautobot/core/apps/__init__.py`

    398
    399
    400
    401
    402
    403
    404
    405
    406
    407
    408
    409
    410
    411
    412
    413
    414
    415
    416
    417
    418
    419
    420
    421
    422
    423
    424
    425
    426
    427
    428
    429
    430
    def __init__(
        self,
        name,
        link=None,
        model=None,
        custom_template=None,
        custom_data=None,
        description=None,
        permissions=None,
        weight=1000,
    ):
        """
        Ensure item properties.

        Args:
            name (str): The name of the item.
            link (str): The link to be used for this item.
            model (str): The model to being used for this item to calculate the total count of objects.
            custom_template (str): Name of custom template.
            custom_data (dict): Custom data to be passed to the custom template.
        """
        super().__init__(permissions)

        self.name = name
        self.custom_template = custom_template
        self.custom_data = custom_data
        self.description = description
        self.link = link
        self.model = model
        self.weight = weight

        if model is not None and custom_template is not None:
            raise ValueError("Cannot specify model and custom_template at the same time.")

## `nautobot.apps.ui.HomePagePanel`

Bases: `HomePageBase`, `PermissionsMixin`

Defines properties that can be used for a panel.

Source code in `nautobot/core/apps/__init__.py`

    285
    286
    287
    288
    289
    290
    291
    292
    293
    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333
    class HomePagePanel(HomePageBase, PermissionsMixin):
        """Defines properties that can be used for a panel."""

        items = None
        template_path = None

        @property
        def initial_dict(self):
            return {
                "custom_template": self.custom_template,
                "custom_data": self.custom_data,
                "weight": self.weight,
                "items": {},
                "permissions": self.permissions,
                "template_path": self.template_path,
            }

        @property
        def fixed_fields(self):
            return ()

        def __init__(self, name, permissions=None, custom_data=None, custom_template=None, items=None, weight=1000):
            """
            Ensure panel properties.

            Args:
                name (str): The name of the panel.
                permissions (list): The permissions required to view this panel.
                custom_data (dict): Custom data to be passed to the custom template.
                custom_template (str): Name of custom template.
                items (list): List of items to be rendered in this panel.
                weight (int): The weight of this panel.
            """
            super().__init__(permissions)
            self.custom_data = custom_data
            self.custom_template = custom_template
            self.name = name
            self.weight = weight

            if items is not None and custom_template is not None:
                raise ValueError("Cannot specify items and custom_template at the same time.")
            if items is not None:
                if not isinstance(items, (list, tuple)):
                    raise TypeError("Items must be passed as a tuple or list.")
                elif not all(isinstance(item, (HomePageGroup, HomePageItem)) for item in items):
                    raise TypeError("All items defined in a panel must be an instance of HomePageGroup or HomePageItem")
                self.items = items
            else:
                self.items = []

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

Source code in `nautobot/core/apps/__init__.py`

    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333
    def __init__(self, name, permissions=None, custom_data=None, custom_template=None, items=None, weight=1000):
        """
        Ensure panel properties.

        Args:
            name (str): The name of the panel.
            permissions (list): The permissions required to view this panel.
            custom_data (dict): Custom data to be passed to the custom template.
            custom_template (str): Name of custom template.
            items (list): List of items to be rendered in this panel.
            weight (int): The weight of this panel.
        """
        super().__init__(permissions)
        self.custom_data = custom_data
        self.custom_template = custom_template
        self.name = name
        self.weight = weight

        if items is not None and custom_template is not None:
            raise ValueError("Cannot specify items and custom_template at the same time.")
        if items is not None:
            if not isinstance(items, (list, tuple)):
                raise TypeError("Items must be passed as a tuple or list.")
            elif not all(isinstance(item, (HomePageGroup, HomePageItem)) for item in items):
                raise TypeError("All items defined in a panel must be an instance of HomePageGroup or HomePageItem")
            self.items = items
        else:
            self.items = []

## `nautobot.apps.ui.NavContext`

Bases: `NavMenuBase`

Ths class represents a navigation menu tab for new ui.

Groups are each specified as a list of NavGrouping instances.

Source code in `nautobot/core/apps/__init__.py`

    671
    672
    673
    674
    675
    676
    677
    678
    679
    680
    681
    682
    683
    684
    685
    686
    687
    688
    689
    690
    691
    692
    693
    694
    695
    696
    697
    698
    699
    700
    701
    702
    703
    704
    705
    706
    class NavContext(NavMenuBase):
        """Ths class represents a navigation menu tab for new ui.

        Groups are each specified as a list of NavGrouping instances.
        """

        def __init__(self, name, groups, weight=1000):
            self.name = name
            self.groups = groups
            self.weight = weight
            self.validate()

        def validate(self):
            # NavContext name must belong in this group ("Inventory", "Networks", "Security", "Automation", "Platform")
            if self.name not in NAV_CONTEXT_NAMES:
                raise TypeError(f"`{self.name}` is an invalid context name, valid choices are: {NAV_CONTEXT_NAMES}")

            if self.groups:
                groups = self.groups
                if not isinstance(groups, (list, tuple)):
                    raise TypeError("Groups must be passed as a tuple or list.")
                elif not all(isinstance(group, NavGrouping) for group in groups):
                    raise TypeError("All groups defined in a NavContext must be an instance of NavGrouping")

        @property
        def initial_dict(self) -> dict:
            """Attributes to be stored when adding this item to the nav menu data for the first time."""
            return {
                "weight": self.weight,
                "data": {},
            }

        @property
        def fixed_fields(self) -> tuple:
            """Tuple of (name, attribute) entries describing fields that may not be altered after declaration."""
            return ()

### `fixed_fields: tuple` `property`

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

### `initial_dict: dict` `property`

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

## `nautobot.apps.ui.NavGrouping`

Bases: `NavMenuBase`, `PermissionsMixin`

Ths class represents a navigation menu group for the new ui. 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 navigation sidebar.

Items are each specified as a list of NavItem or NavGrouping instances.

Source code in `nautobot/core/apps/__init__.py`

    709
    710
    711
    712
    713
    714
    715
    716
    717
    718
    719
    720
    721
    722
    723
    724
    725
    726
    727
    728
    729
    730
    731
    732
    733
    734
    735
    736
    737
    738
    739
    740
    741
    742
    743
    class NavGrouping(NavMenuBase, PermissionsMixin):
        """
        Ths class represents a navigation menu group for the new ui. 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 navigation sidebar.

        Items are each specified as a list of NavItem or NavGrouping instances.
        """

        def __init__(self, name, items, weight=1000):
            self.name = name
            self.items = items
            self.weight = weight
            self.validate()

        def validate(self):
            if self.items:
                items = self.items
                if items is not None and not isinstance(items, (list, tuple)):
                    raise TypeError("Items must be passed as a tuple or list.")

                if not all(isinstance(item, (NavItem, self.__class__)) for item in items):
                    raise TypeError("All items defined in a NavGrouping must be an instance of NavItem or NavGrouping")

        @property
        def initial_dict(self) -> dict:
            """Attributes to be stored when adding this item to the nav menu data for the first time."""
            return {
                "weight": self.weight,
                "data": {},
            }

        @property
        def fixed_fields(self) -> tuple:
            """Tuple of (name, attribute) entries describing fields that may not be altered after declaration."""
            return ()

### `fixed_fields: tuple` `property`

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

### `initial_dict: dict` `property`

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

## `nautobot.apps.ui.NavItem`

Bases: `NavMenuBase`, `PermissionsMixin`

This class represents a navigation menu item for the new ui. This constitutes link and its text.

Links are specified as Django reverse URL strings.

Source code in `nautobot/core/apps/__init__.py`

    746
    747
    748
    749
    750
    751
    752
    753
    754
    755
    756
    757
    758
    759
    760
    761
    762
    763
    764
    765
    766
    767
    768
    769
    770
    771
    772
    773
    774
    775
    776
    777
    778
    779
    780
    781
    782
    783
    784
    class NavItem(NavMenuBase, PermissionsMixin):
        """
        This class represents a navigation menu item for the new ui. This constitutes link and its text.

        Links are specified as Django reverse URL strings.
        """

        def __init__(self, name, link, *args, permissions=None, weight=1000, **kwargs):
            self.name = name
            self.link = link
            self.permissions = permissions or []
            self.weight = weight
            self.args = args
            self.kwargs = kwargs

        @property
        def initial_dict(self) -> dict:
            """Attributes to be stored when adding this item to the nav menu data for the first time."""
            return {
                "name": self.name,
                "weight": self.weight,
                "permissions": self.permissions,
                "data": self.url(),
            }

        @property
        def fixed_fields(self):
            """Tuple of (name, attribute) entries describing fields that may not be altered after declaration."""
            return (
                ("name", self.name),
                ("permissions", self.permissions),
            )

        def url(self):
            try:
                return reverse(self.link, args=self.args, kwargs=self.kwargs)
            except NoReverseMatch as e:
                logger.error("Error in link construction for %s: %s", self.name, e)
                return ""

### `fixed_fields` `property`

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

### `initial_dict: dict` `property`

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

## `nautobot.apps.ui.NavMenuAddButton`

Bases: `NavMenuButton`

Add button subclass.

Source code in `nautobot/core/apps/__init__.py`

    639
    640
    641
    642
    643
    644
    645
    646
    647
    648
    649
    650
    651
    652
    class NavMenuAddButton(NavMenuButton):
        """Add button subclass."""

        def __init__(self, *args, **kwargs):
            """Ensure button properties."""
            if "title" not in kwargs:
                kwargs["title"] = "Add"
            if "icon_class" not in kwargs:
                kwargs["icon_class"] = ButtonActionIconChoices.ADD
            if "button_class" not in kwargs:
                kwargs["button_class"] = ButtonActionColorChoices.ADD
            if "weight" not in kwargs:
                kwargs["weight"] = 100
            super().__init__(*args, **kwargs)

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

Ensure button properties.

Source code in `nautobot/core/apps/__init__.py`

    642
    643
    644
    645
    646
    647
    648
    649
    650
    651
    652
    def __init__(self, *args, **kwargs):
        """Ensure button properties."""
        if "title" not in kwargs:
            kwargs["title"] = "Add"
        if "icon_class" not in kwargs:
            kwargs["icon_class"] = ButtonActionIconChoices.ADD
        if "button_class" not in kwargs:
            kwargs["button_class"] = ButtonActionColorChoices.ADD
        if "weight" not in kwargs:
            kwargs["weight"] = 100
        super().__init__(*args, **kwargs)

## `nautobot.apps.ui.NavMenuBase`

Bases: `ABC`

Base class for navigation classes.

Source code in `nautobot/core/apps/__init__.py`

    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    class NavMenuBase(ABC):  # replaces PermissionsMixin
        """Base class for navigation classes."""

        @property
        @abstractmethod
        def initial_dict(self) -> dict:  # to be implemented by each subclass
            """Attributes to be stored when adding this item to the nav menu data for the first time."""
            return {}

        @property
        @abstractmethod
        def fixed_fields(self) -> tuple:  # to be implemented by subclass
            """Tuple of (name, attribute) entries describing fields that may not be altered after declaration."""
            return ()

### `fixed_fields: tuple` `abstractmethod` `property`

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

### `initial_dict: 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 PluginMenuItem. Note that button colors should come from ButtonColorChoices.

Source code in `nautobot/core/apps/__init__.py`

    583
    584
    585
    586
    587
    588
    589
    590
    591
    592
    593
    594
    595
    596
    597
    598
    599
    600
    601
    602
    603
    604
    605
    606
    607
    608
    609
    610
    611
    612
    613
    614
    615
    616
    617
    618
    619
    620
    621
    622
    623
    624
    625
    626
    627
    628
    629
    630
    631
    632
    633
    634
    635
    636
    class NavMenuButton(NavMenuBase, PermissionsMixin):
        """
        This class represents a button within a PluginMenuItem. Note that button colors should come from
        ButtonColorChoices.
        """

        @property
        def initial_dict(self) -> dict:
            """Attributes to be stored when adding this item to the nav menu data for the first time."""
            return {
                "link": self.link,
                "icon_class": self.icon_class,
                "button_class": self.button_class,
                "weight": self.weight,
                "buttons": {},
                "permissions": self.permissions,
            }

        @property
        def fixed_fields(self) -> tuple:
            """Tuple of (name, attribute) entries describing fields that may not be altered after declaration."""
            return (
                ("button_class", self.button_class),
                ("icon_class", self.icon_class),
                ("link", self.link),
                ("permissions", self.permissions),
            )

        def __init__(
            self,
            link,
            title,
            icon_class,
            button_class=ButtonActionColorChoices.DEFAULT,
            permissions=None,
            weight=1000,
        ):
            """
            Ensure button properties.

            Args:
                link (str): The link to be used for this button.
                title (str): The title of the button.
                icon_class (str): The icon class to be used as the icon for the start of the button.
                button_class (str): The button class defines to be used to define the style of the button.
                permissions (list): The permissions required to view this button.
                weight (int): The weight of this button.
            """
            super().__init__(permissions)
            self.link = link
            self.title = title
            self.icon_class = icon_class
            self.weight = weight
            self.button_class = button_class

### `fixed_fields: tuple` `property`

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

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

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. | `ButtonActionColorChoices.DEFAULT`
`permissions` | `list` | The permissions required to view this button. | `None`
`weight` | `int` | The weight of this button. | `1000`

Source code in `nautobot/core/apps/__init__.py`

    611
    612
    613
    614
    615
    616
    617
    618
    619
    620
    621
    622
    623
    624
    625
    626
    627
    628
    629
    630
    631
    632
    633
    634
    635
    636
    def __init__(
        self,
        link,
        title,
        icon_class,
        button_class=ButtonActionColorChoices.DEFAULT,
        permissions=None,
        weight=1000,
    ):
        """
        Ensure button properties.

        Args:
            link (str): The link to be used for this button.
            title (str): The title of the button.
            icon_class (str): The icon class to be used as the icon for the start of the button.
            button_class (str): The button class defines to be used to define the style of the button.
            permissions (list): The permissions required to view this button.
            weight (int): The weight of this button.
        """
        super().__init__(permissions)
        self.link = link
        self.title = title
        self.icon_class = icon_class
        self.weight = weight
        self.button_class = button_class

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

Source code in `nautobot/core/apps/__init__.py`

    479
    480
    481
    482
    483
    484
    485
    486
    487
    488
    489
    490
    491
    492
    493
    494
    495
    496
    497
    498
    499
    500
    501
    502
    503
    504
    505
    506
    507
    508
    509
    510
    511
    512
    513
    514
    515
    516
    517
    518
    519
    class NavMenuGroup(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.
        """

        permissions = []
        items = []

        @property
        def initial_dict(self) -> dict:
            """Attributes to be stored when adding this item to the nav menu data for the first time."""
            return {
                "weight": self.weight,
                "items": {},
            }

        @property
        def fixed_fields(self) -> tuple:
            """Tuple of (name, attribute) entries describing fields that may not be altered after declaration."""
            return ()

        def __init__(self, name, items=None, weight=1000):
            """
            Ensure group properties.

            Args:
                name (str): The name of the group.
                items (list): List of items to be rendered in this group.
                weight (int): The weight of this group.
            """
            self.name = name
            self.weight = weight

            if items is not None and not isinstance(items, (list, tuple)):
                raise TypeError("Items must be passed as a tuple or list.")
            elif not all(isinstance(item, NavMenuItem) for item in items):
                raise TypeError("All items defined in a group must be an instance of NavMenuItem")
            self.items = items

### `fixed_fields: tuple` `property`

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

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

Source code in `nautobot/core/apps/__init__.py`

    503
    504
    505
    506
    507
    508
    509
    510
    511
    512
    513
    514
    515
    516
    517
    518
    519
    def __init__(self, name, items=None, weight=1000):
        """
        Ensure group properties.

        Args:
            name (str): The name of the group.
            items (list): List of items to be rendered in this group.
            weight (int): The weight of this group.
        """
        self.name = name
        self.weight = weight

        if items is not None and not isinstance(items, (list, tuple)):
            raise TypeError("Items must be passed as a tuple or list.")
        elif not all(isinstance(item, NavMenuItem) for item in items):
            raise TypeError("All items defined in a group must be an instance of NavMenuItem")
        self.items = items

## `nautobot.apps.ui.NavMenuImportButton`

Bases: `NavMenuButton`

Import button subclass.

Source code in `nautobot/core/apps/__init__.py`

    655
    656
    657
    658
    659
    660
    661
    662
    663
    664
    665
    666
    667
    668
    class NavMenuImportButton(NavMenuButton):
        """Import button subclass."""

        def __init__(self, *args, **kwargs):
            """Ensure button properties."""
            if "title" not in kwargs:
                kwargs["title"] = "Import"
            if "icon_class" not in kwargs:
                kwargs["icon_class"] = ButtonActionIconChoices.IMPORT
            if "button_class" not in kwargs:
                kwargs["button_class"] = ButtonActionColorChoices.IMPORT
            if "weight" not in kwargs:
                kwargs["weight"] = 200
            super().__init__(*args, **kwargs)

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

Ensure button properties.

Source code in `nautobot/core/apps/__init__.py`

    658
    659
    660
    661
    662
    663
    664
    665
    666
    667
    668
    def __init__(self, *args, **kwargs):
        """Ensure button properties."""
        if "title" not in kwargs:
            kwargs["title"] = "Import"
        if "icon_class" not in kwargs:
            kwargs["icon_class"] = ButtonActionIconChoices.IMPORT
        if "button_class" not in kwargs:
            kwargs["button_class"] = ButtonActionColorChoices.IMPORT
        if "weight" not in kwargs:
            kwargs["weight"] = 200
        super().__init__(*args, **kwargs)

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

Source code in `nautobot/core/apps/__init__.py`

    522
    523
    524
    525
    526
    527
    528
    529
    530
    531
    532
    533
    534
    535
    536
    537
    538
    539
    540
    541
    542
    543
    544
    545
    546
    547
    548
    549
    550
    551
    552
    553
    554
    555
    556
    557
    558
    559
    560
    561
    562
    563
    564
    565
    566
    567
    568
    569
    570
    571
    572
    573
    574
    575
    576
    577
    578
    579
    580
    class NavMenuItem(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.
        """

        @property
        def initial_dict(self) -> dict:
            """Attributes to be stored when adding this item to the nav menu data for the first time."""
            return {
                "name": self.name,
                "weight": self.weight,
                "buttons": {},
                "permissions": self.permissions,
                "args": [],
                "kwargs": {},
            }

        @property
        def fixed_fields(self) -> tuple:
            """Tuple of (name, attribute) entries describing fields that may not be altered after declaration."""
            return (
                ("name", self.name),
                ("permissions", self.permissions),
            )

        permissions = []
        buttons = []
        args = []
        kwargs = {}

        def __init__(self, link, name, args=None, kwargs=None, permissions=None, buttons=(), weight=1000):
            """
            Ensure item properties.

            Args:
                link (str): The link to be used for this item.
                name (str): The name of the item.
                args (list): Arguments that are being passed to the url with reverse() method
                kwargs (dict): Keyword arguments are are being passed to the url with reverse() method
                permissions (list): The permissions required to view this item.
                buttons (list): List of buttons to be rendered in this item.
                weight (int): The weight of this item.
            """
            super().__init__(permissions)
            self.link = link
            self.name = name
            self.weight = weight
            self.args = args
            self.kwargs = kwargs

            if not isinstance(buttons, (list, tuple)):
                raise TypeError("Buttons must be passed as a tuple or list.")
            elif not all(isinstance(button, NavMenuButton) for button in buttons):
                raise TypeError("All buttons defined in an item must be an instance or subclass of NavMenuButton")
            self.buttons = buttons

### `fixed_fields: tuple` `property`

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

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

Source code in `nautobot/core/apps/__init__.py`

    556
    557
    558
    559
    560
    561
    562
    563
    564
    565
    566
    567
    568
    569
    570
    571
    572
    573
    574
    575
    576
    577
    578
    579
    580
    def __init__(self, link, name, args=None, kwargs=None, permissions=None, buttons=(), weight=1000):
        """
        Ensure item properties.

        Args:
            link (str): The link to be used for this item.
            name (str): The name of the item.
            args (list): Arguments that are being passed to the url with reverse() method
            kwargs (dict): Keyword arguments are are being passed to the url with reverse() method
            permissions (list): The permissions required to view this item.
            buttons (list): List of buttons to be rendered in this item.
            weight (int): The weight of this item.
        """
        super().__init__(permissions)
        self.link = link
        self.name = name
        self.weight = weight
        self.args = args
        self.kwargs = kwargs

        if not isinstance(buttons, (list, tuple)):
            raise TypeError("Buttons must be passed as a tuple or list.")
        elif not all(isinstance(button, NavMenuButton) for button in buttons):
            raise TypeError("All buttons defined in an item must be an instance or subclass of NavMenuButton")
        self.buttons = buttons

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

Source code in `nautobot/core/apps/__init__.py`

    433
    434
    435
    436
    437
    438
    439
    440
    441
    442
    443
    444
    445
    446
    447
    448
    449
    450
    451
    452
    453
    454
    455
    456
    457
    458
    459
    460
    461
    462
    463
    464
    465
    466
    467
    468
    469
    470
    471
    472
    473
    474
    475
    476
    class NavMenuTab(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.
        """

        permissions = []
        groups = []

        @property
        def initial_dict(self) -> dict:
            """Attributes to be stored when adding this item to the nav menu data for the first time."""
            return {
                "weight": self.weight,
                "groups": {},
                "permissions": set(),
            }

        @property
        def fixed_fields(self) -> tuple:
            """Tuple of (name, attribute) entries describing fields that may not be altered after declaration."""
            return ()

        def __init__(self, name, permissions=None, groups=None, weight=1000):
            """
            Ensure tab properties.

            Args:
                name (str): The name of the tab.
                permissions (list): The permissions required to view this tab.
                groups (list): List of groups to be rendered in this tab.
                weight (int): The weight of this tab.
            """
            super().__init__(permissions)
            self.name = name
            self.weight = weight
            if groups is not None:
                if not isinstance(groups, (list, tuple)):
                    raise TypeError("Groups must be passed as a tuple or list.")
                elif not all(isinstance(group, NavMenuGroup) for group in groups):
                    raise TypeError("All groups defined in a tab must be an instance of NavMenuGroup")
                self.groups = groups

### `fixed_fields: tuple` `property`

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

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

Source code in `nautobot/core/apps/__init__.py`

    458
    459
    460
    461
    462
    463
    464
    465
    466
    467
    468
    469
    470
    471
    472
    473
    474
    475
    476
    def __init__(self, name, permissions=None, groups=None, weight=1000):
        """
        Ensure tab properties.

        Args:
            name (str): The name of the tab.
            permissions (list): The permissions required to view this tab.
            groups (list): List of groups to be rendered in this tab.
            weight (int): The weight of this tab.
        """
        super().__init__(permissions)
        self.name = name
        self.weight = weight
        if groups is not None:
            if not isinstance(groups, (list, tuple)):
                raise TypeError("Groups must be passed as a tuple or list.")
            elif not all(isinstance(group, NavMenuGroup) for group in groups):
                raise TypeError("All groups defined in a tab must be an instance of NavMenuGroup")
            self.groups = groups

## `nautobot.apps.ui.PermissionsMixin`

Ensure permissions through init.

Source code in `nautobot/core/apps/__init__.py`

    275
    276
    277
    278
    279
    280
    281
    282
    class PermissionsMixin:
        """Ensure permissions through init."""

        def __init__(self, permissions=None):
            """Ensure permissions."""
            if permissions is not None and not isinstance(permissions, (list, tuple)):
                raise TypeError("Permissions must be passed as a tuple or list.")
            self.permissions = set(permissions) if permissions else set()

### `__init__(permissions=None)`

Ensure permissions.

Source code in `nautobot/core/apps/__init__.py`

    278
    279
    280
    281
    282
    def __init__(self, permissions=None):
        """Ensure permissions."""
        if permissions is not None and not isinstance(permissions, (list, tuple)):
            raise TypeError("Permissions must be passed as a tuple or list.")
        self.permissions = set(permissions) if permissions else set()

## `nautobot.apps.ui.TemplateExtension`

This class is used to register plugin content to be injected into core Nautobot templates. It contains methods that are overridden by plugin authors to return template content.

The `model` attribute on the class defines the which model detail page this class renders content for. It should be set as a string in the form `<app_label>.<model_name>`. `render()` provides the following context data:

- object - The object being viewed
- request - The current request
- settings - Global Nautobot settings
- config - Plugin-specific configuration parameters

Source code in `nautobot/extras/plugins/__init__.py`

    274
    275
    276
    277
    278
    279
    280
    281
    282
    283
    284
    285
    286
    287
    288
    289
    290
    291
    292
    293
    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333
    334
    335
    336
    337
    338
    339
    340
    341
    342
    343
    344
    345
    346
    347
    348
    349
    350
    351
    352
    353
    class TemplateExtension:
        """
        This class is used to register plugin content to be injected into core Nautobot templates. It contains methods
        that are overridden by plugin authors to return template content.

        The `model` attribute on the class defines the which model detail page this class renders content for. It
        should be set as a string in the form `<app_label>.<model_name>`. `render()` provides the following context data:

        * object - The object being viewed
        * request - The current request
        * settings - Global Nautobot settings
        * config - Plugin-specific configuration parameters
        """

        model = None

        def __init__(self, context):
            self.context = context

        def render(self, 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`.
            """
            if extra_context is None:
                extra_context = {}
            elif not isinstance(extra_context, dict):
                raise TypeError("extra_context must be a dictionary")

            return get_template(template_name).render({**self.context, **extra_context})

        def left_page(self):
            """
            Content that will be rendered on the left of the detail 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.
            """
            raise NotImplementedError

        def right_page(self):
            """
            Content that will be rendered on the right of the detail 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.
            """
            raise NotImplementedError

        def full_width_page(self):
            """
            Content that will be rendered within the full width of the detail 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.
            """
            raise NotImplementedError

        def buttons(self):
            """
            Buttons that will be rendered and added to the existing list of buttons on the detail 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.
            """
            raise NotImplementedError

        def detail_tabs(self):
            """
            Tabs that will be rendered and added to the existing list of tabs on the detail page view.
            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>",
                },
            ]
            ```
            """
            raise NotImplementedError

### `buttons()`

Buttons that will be rendered and added to the existing list of buttons on the detail 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.

Source code in `nautobot/extras/plugins/__init__.py`

    326
    327
    328
    329
    330
    331
    332
    def buttons(self):
        """
        Buttons that will be rendered and added to the existing list of buttons on the detail 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.
        """
        raise NotImplementedError

### `detail_tabs()`

Tabs that will be rendered and added to the existing list of tabs on the detail page view. 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>",
        },
    ]

Source code in `nautobot/extras/plugins/__init__.py`

    334
    335
    336
    337
    338
    339
    340
    341
    342
    343
    344
    345
    346
    347
    348
    349
    350
    351
    352
    353
    def detail_tabs(self):
        """
        Tabs that will be rendered and added to the existing list of tabs on the detail page view.
        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>",
            },
        ]
        ```
        """
        raise NotImplementedError

### `full_width_page()`

Content that will be rendered within the full width of the detail 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.

Source code in `nautobot/extras/plugins/__init__.py`

    319
    320
    321
    322
    323
    324
    def full_width_page(self):
        """
        Content that will be rendered within the full width of the detail 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.
        """
        raise NotImplementedError

### `left_page()`

Content that will be rendered on the left of the detail 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.

Source code in `nautobot/extras/plugins/__init__.py`

    305
    306
    307
    308
    309
    310
    def left_page(self):
        """
        Content that will be rendered on the left of the detail 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.
        """
        raise NotImplementedError

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

Source code in `nautobot/extras/plugins/__init__.py`

    293
    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    def render(self, 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`.
        """
        if extra_context is None:
            extra_context = {}
        elif not isinstance(extra_context, dict):
            raise TypeError("extra_context must be a dictionary")

        return get_template(template_name).render({**self.context, **extra_context})

### `right_page()`

Content that will be rendered on the right of the detail 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.

Source code in `nautobot/extras/plugins/__init__.py`

    312
    313
    314
    315
    316
    317
    def right_page(self):
        """
        Content that will be rendered on the right of the detail 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.
        """
        raise NotImplementedError