Navigation#

class BasicMenu(*args, **kwargs)[source]#

Bases: WidgetInitKwargsMixin

Basic menu widget.

A basic menu requires only one class attribute defined, items:

class MainMenu(BasicMenu):

    items = [
        ('Users', 'core:home'),
        ('Uploads','core:uploads'),
    ]

items = []#: a list of tuples that define the items to list in the menu, where the first element is the menu item text and the second element is the URL name. A third optional element in the tuple can be a dictionary of get arguments

class DarkMenu(*args, **kwargs)[source]#: Bases: BasicMenu

class LightMenu(*args, **kwargs)[source]#: Bases: BasicMenu

class VerticalDarkMenu(*args, **kwargs)[source]#: Bases: BasicMenu

class BreadcrumbBlock(*args, title_class: Optional[str] = None, **kwargs)[source]#

Bases: Block

A block that renders a Bootstrap Breadcrumb component.

Typically how you will use this is to define a base set of breadcrumbs (which typically just has your home page in it), and then add additional breadcrumbs in your views.

Example:

from django.views import View
from wildewdigets import BreadcrumbItem, BreadcrumbBlock

class BaseBreadCrumbs(BreadcrumbBlock):

    def __init__(self, *args, **kwargs):
        self.add_breadcrumb('Home', url='/home')

class MyView(View):

    def get_context_data(self, **kwargs):
        kwargs = super().get_context_data(**kwargs)
        breadcrumbs = BaseBreadCrumbs()
        breadcrumbs.add_breadcrumb('MyView')
        kwargs['breadcrumbs'] = breadcrumbs
        return kwargs

Keyword Arguments:: title_class – Apply this string of CSS classes to each breadcrumb title

add_breadcrumb(title: str, url: Optional[str] = None) → None[source]#

Add a new breadcrumb item to this BreadcrumbBlock.

Example

>>> breadcrumbs = BreadcrumbBlock()
>>> breadcrumbs.add_breadcrumb('Home', url='/home'))
>>> breadcrumbs.add_breadcrumb('Project')

This will produce this HTML:

<nav aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-item"><a href="/home">Home</a></li>
    <li class="breadcrumb-item active">Project</li>
  </ol>
</nav>

Parameters:: title – the text for the breadcrumb item
Keyword Arguments:: url – the url for the breadcrumb item

flatten() → str[source]#: Return a string of the titles of all the breadcrumbs.

get_context_data(*args, **kwargs) → Dict[str, Any][source]#

Update the template context dictionary used when rendering this block.

Keyword Arguments:: **kwargs – the current context dictionary
Returns:: The updated context dictionary

aria_attributes: Dict[str, str] = {'label': 'breadcrumb'}#: Additional aria- attributes to set on this block

breadcrumbs#: The <ol> that holds our breadcrumbs

items: List[BreadcrumbItem] = []#: The list of BreadcrumbItem objects from which we will build our breadcrumb HTML

tag: str = 'nav'#: The name of the HTML element to use as our tag, e.g. div

title_class: Optional[str] = None#: Apply this string of CSS classes to each breadcrumb title

class BreadcrumbItem(title: str, url: Optional[str] = None)[source]#

Bases: object

A dataclass that is used to register crumbs with BreadcrumbBlock.

title: str#: The title for the breadcrumb

url: str = None#: The optional URL for the breadcrumb

class ClickableNavDropdownControl(menu_id: str, text: Optional[str] = None, icon: Optional[Union[str, TablerMenuIcon]] = None, url: Optional[str] = None, active: bool = False, **kwargs)[source]#

Bases: Block

This is a variation on NavDropdownControl for the cases when the text that controls the open and close of the related DropdownMenu is also a link that should be able to be clicked separately.

To implement that, this is a <div> with two different links in it:

A first link that link that links our text to url, optionally with an icon.
A second link that is just the up/down arrow for the dropdown control. Clicking this is what opens the submenu with CSS id menu_id.

Examples

No icon:

>>> control = ClickableNavDropdownControl(
    'the-menu-id',
    text='My Text',
    url='/destination'
)

With an icon:

>>> control2 = ClickableNavDropdownControl(
    'the-menu-id',
    text='My Text',
    url='/destination',
    icon='arrow-down-square-fill'
)

With a TablerMenuIcon:

>>> arrow_icon = TablerMenuIcon(icon='arrow-down-square-fill')
>>> control3 = ClickableNavDropdownControl(
    'the-menu-id',
    text='My Text',
    url='/destination',
    icon=arrow_icon
)

Parameters:

menu_id – The CSS Id to of the dropdown menu that this controls.

Keyword Arguments:

icon – either the name of a Bootstrap icon, or a TablerMenuIcon class or subclass
text – The label for the dropdown control
url – The URL for the item. For Django urls, you will typically do something like reverse('myapp:view') or reverse_lazy('myapp:view')

Raises:

ValueError – no text was supplied

collapse() → None[source]#: Set our aria-expanded attribute to false.

expand() → None[source]#: Set our aria-expanded attribute to true.

active: bool#: If this is True, this control itself is active, but nothing in the related DropdownMenu is

block: str = 'nav-item--clickable'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

icon: Optional[Union[str, TablerMenuIcon]] = None#: Either the name of a Bootstrap icon, or a TablerMenuIcon class or subclass

text: Optional[str] = None#: The actual name of the dropdown

url: Optional[str] = None#: The URL to associated with the control

class DropdownItem(text: Optional[str] = None, icon: Optional[str] = None, active: bool = False, item: Optional[MenuItem] = None, **kwargs)[source]#

Bases: Link

An entry in a DropdownMenu, a submenu class used in a NavDropdownItem of a Menu. This is a label with a link to a URL, with an optional icon preceding the label.

Typically, you won’t use this directly, but instead it will be created for you from a MenuItem specification when MenuItem.url is not None.

Examples

>>> icon = TablerMenuIcon(icon='target')
>>> item = DropdownItem(text='Page', url='/page', icon=icon)

>>> menu_item = MenuItem(text='Page', url='/page', icon='target')
>>> item = DropdownItem(item=menu_item)

Kewyword Args:: icon: Either the name of a Bootstrap icon, or a TablerMenuIcon object text: The text for the item active: True if this represents the page we’re currently on item: a MenuItem

Raises:: ValueError – one or more of the arguments failed validation

block: str = 'dropdown-item'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

icon: Optional[Union[str, TablerMenuIcon]] = None#: this is either the name of a bootstrap icon, or a TablerMenuIcon class or subclass

text: Optional[str] = None#: The text for the item.

class DropdownMenu(*items: MenuItem, button_id: Optional[str] = None, **kwargs)[source]#

Bases: Block

A Tabler dropdown menu.

Typically, you won’t use this directly, but instead it will be created for you from a MenuItem specification when MenuItem.url is not None.

Examples

>>> items = [
    MenuItem(text='One', url='/one', icon='1-circle'),
    MenuItem(text='Two', url='/two', icon='2-circle'),
    MenuItem(text='Three', url='/three', icon='3-circle'),
]
>>> button = NavDropdownControl(
    text='My Dropdown Menu',
    icon='arrow-down-square-fill',
    button_id='my-button'
)
>>> menu = DropdownMenu(*items, button_id=button.button_id)

Parameters:: *items – the list of MenuItem objects to insert into this menu
Keyword Arguments:: button_id – it CSS id for the button
Raises:: ValueError – one or more of the settings failed validation

add_item(text: Optional[str] = None, url: Optional[str] = None, icon: Optional[Union[str, TablerMenuIcon]] = None, active: bool = False, item: Optional[MenuItem] = None) → None[source]#

Add a new item to this DropdownMenu.

Kewyword Args:: icon: Either the name of a Bootstrap icon, or a TablerMenuIcon object text: The text for the item url: The URL for the item active: True if this represents the page we’re currently on item: a MenuItem

Raises:: ValueError – one or more of the settings failed validation

hide() → None[source]#: Force this dropdown menu to be hidden.

show() → None[source]#: Force this dropdown menu to be shown.

block: str = 'dropdown-menu'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

button_id: Optional[str] = None#: The id of the dropdown-toggle button that controls this menu

items: Iterable[MenuItem] = []#: A list of MenuItem objects to add to this dropdown menu

class Menu(*items: MenuItem, title: Optional[str] = None, title_tag: Optional[str] = None, title_css_classes: Optional[str] = None, **kwargs)[source]#

Bases: Block

A <div> with an optional title and a Bootstrap ``ul.navbar-nav` <https://getbootstrap.com/docs/5.2/components/navbar/>`_ for use in a Navbar.

Use this in any of these ways:

Subclass Menu and define items
Pass in the items kwargs to the constructor
Add items with add_item
Subclass Menu, define items, and add additional items with add_item

Examples

Subclassing:

class MyMenu(Menu):

    items = [
        MenuItem(text='One', url='/one', icon='1-circle'),
        MenuItem(text='Two', url='/two', icon='2-circle'),
        MenuItem(text='Three', url='/three', icon='3-circle'),
    ]

Constructor:

>>> menu = Menu(
    MenuItem(text='One', url='/one', icon='1-circle'),
    MenuItem(text='Two', url='/two', icon='2-circle'),
    MenuItem(text='Three', url='/three', icon='3-circle'),
)

Menu.add_item:

>>> menu = Menu()
>>> menu.add_item(MenuItem(text='One', url='/one', icon='1-circle'))
>>> menu.add_item(MenuItem(text='Two', url='/two', icon='2-circle'))
>>> menu.add_item(MenuItem(text='Three', url='/three', icon='3-circle'))

Parameters:

*items – the list of MenuItem objects to insert into this menu

Keyword Arguments:

title – the title for this menu
title_tag – the HTML tag to use for the title
title_css_classes – CSS classes to apply to the title

Raises:

ValueError – one or more of the settings failed validation

activate(text: str) → bool[source]#

If text is not a URL or path, Set MenuItem.active to True for the first item we find in our items (searching recursively) whose MenuItem.text matches text.

If text is a URL or path, Set MenuItem.active to True for the first item we find in our items (searching recursively) whose MenuItem.url matches text.

Parameters:: text – the text to search for among our items
Returns:: If we found a match, return True, otherwise return False.

add_item(item: MenuItem) → None[source]#

Add a single MenuItem to ourselves.

Parameters:: item – the menu item to add to ourselves.

build_menu(items: Iterable[MenuItem]) → None[source]#

Recurse through items and build out our menu and any submenus.

For each item in items, if item.items is not empty, add a submenu, otherwise add simple item.

Parameters:: items – the list of menu items to add to the list

get_content(**kwargs) → str[source]#: Actually build out the menu from our list of MenuItems. We do this in get_content instead of in __init__ so that we catch any menu items added via add_item after instantiation.

block: str = 'menu'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

css_class: str = 'me-1'#: A string of CSS classes to apply to this block

items: Iterable[MenuItem] = []#: The list of items in this menu

tag: str = 'div'#: The name of the HTML element to use as our tag, e.g. div

title: Optional[str] = None#: The title for this menu

title_css_classes: str = ''#: CSS classes to apply to the title

title_tag: str = 'h4'#: The HTML tag for this title

class MenuHeading(text: Optional[str] = None, **kwargs)[source]#

Bases: Block

A Tabler menu specific heading. This is a heading within a Menu that sepearates the actual menu items into groups.

Typically, you won’t use this directly, but instead it will be created for you from a MenuItem specification when MenuItem.url is None and MenuItem.items is empty.

Example

>>> heading = MenuHeading(text='My Heading')

Kewyword Args:: text: the text of the heading

block: str = 'nav-link nav-subtitle'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

css_class: str = 'nav-link my-1 fw-bold text-uppercase'#: A string of CSS classes to apply to this block

text: Optional[str] = None#: The text of the heading

class MenuItem(text: str, icon: ~typing.Optional[~typing.Union[str, ~wildewidgets.widgets.base.Block]] = None, url: ~typing.Optional[str] = None, items: ~typing.List[~wildewidgets.widgets.navigation.MenuItem] = <factory>, active: bool = False)[source]#

Bases: object

A menu item definition for a Menu. title is required, but the other attributes are not.

Note

We’re defining this dataclass so that you don’t need to build out the entire menu system with the appropriate blocks yourself, but instead can nest MenuItem objects and have us do it for you.

If no url is provided, we will consider this item to be a section title in the Menu.

set_active(text: str) → bool[source]#

If text looks like a URL or path, look at our url and set active to True if they are equal.

If text does not look like a URL or path, look at our text and set active to True.

If we find no match, set active to False, and try doing set_active on our items. Stop looking when we find the first item that matches text.

Parameters:: text – the value to which to compare our text
Returns:: If we actually did set someone’s active to True, return True, otherwise return False

active: bool = False#: Is this the page we’re currently on?

icon: Optional[Union[str, Block]] = None#: this is either the name of a bootstrap icon, or a Block

property is_active: bool#

Return True if we or any item in items have active equal to True.

Returns:: Whether this item is active.

items: List[MenuItem]#: a submenu under this menu item

text: str#: The text for the item. If url is not defined, this will define a heading within the menu

url: Optional[str] = None#: The URL for the item. For Django urls, you will typically do something like reverse('myapp:view') or reverse_lazy('myapp:view')

class NavDropdownControl(text: Optional[str] = None, icon: Optional[Union[str, TablerMenuIcon]] = None, active: bool = False, button_id: Optional[str] = None, **kwargs)[source]#

Bases: Link

This is a dropdown control that opens a submenu from within either a Menu or a :py:class`DropdownMenu` within a Menu. It consists of a label with optional icon in front, plus a arrow that toggles direction when the menu opens and closes.

Examples

No icon:

>>> control = NavDropdownControl(text='My Control')

With an icon:

>>> control2 = NavDropdownControl(text='My Control', icon='arrow-down-square-fill')

With a TablerMenuIcon:

>>> arrow_icon = TablerMenuIcon(icon='arrow-down-square-fill')
>>> control3 = NavDropdownControl(text='My Control', icon=arrow_icon)

Keyword Arguments:

icon – either the name of a Bootstrap icon, or a TablerMenuIcon class or subclass
text – The label for the dropdown control
button_id – The CSS Id to assign to this button. We need this to tie the button to the actual DropdownItem

Raises:

ValueError – no text was supplied

collapse() → None[source]#: Set our aria-expanded attribute to false.

expand() → None[source]#: Set our aria-expanded attribute to true.

active: bool#: This item is active, but nothing in the related DropdownMenu is

aria_attributes: Dict[str, str] = {'expanded': 'false'}#: Additional aria- attributes to set on this block

block: str = 'nav-link'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

button_id: Optional[str] = None#: The CSS Id to assign to this button. We need this to tie the button to the actual TablerDropdownItem

data_attributes: Dict[str, str] = {'auto-close': 'true', 'toggle': 'dropdown'}#: Additional data-bs- attributes to set on this block

icon: Optional[Union[str, TablerMenuIcon]] = None#: Either the name of a Bootstrap icon, or a TablerMenuIcon class or subclass

name: str = 'dropdown-toggle'#: The CSS class that will be added to this element to as an identifier for this kind of block

text: Optional[str] = None#: The actual name of the dropdown

class NavDropdownItem(*items: MenuItem, text: Optional[str] = None, icon: Optional[str] = None, url: Optional[str] = None, active: bool = False, **kwargs)[source]#

Bases: Block

An item in a Menu that opens a dropdown submenu.

Typically, you won’t use this directly, but instead it will be created for you from a MenuItem specification when MenuItem.items is not empty.

Examples

>>> sub_items = [
    MenuItem(text='One', url='/one', icon='1-circle'),
    MenuItem(text='Two', url='/two', icon='2-circle'),
    MenuItem(text='Three', url='/three', icon='3-circle'),
]
>>> item = NavDropdownItem(*sub_items, text='My Submenu', icon='target')
>>> menu = Menu(item)

Parameters:

*items – the list of MenuItem objects to insert into this menu

Keyword Arguments:

text – the text for the menu item
icon – this is either the name of a Bootstrap icon, or a TablerMenuIcon class or subclass

Raises:

ValueError – one or more of the settings failed validation

get_context_data(**kwargs) → Dict[str, Any][source]#

Overrides wildewidgets.widgets.base.Block.get_context_data.

Show our menu if either active is True or any item in our menu is active. We do this here instead of in our constructor so that any menu item activation that happens after instance construction time is accounted for.

hide() → None[source]#: Hide our menu.

show() → None[source]#: Show our menu.

active#: The control for opening the dropdown menu is active, but nothing in the related DropdownMenu is active

block: str = 'nav-item dropdown'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

control: Union[NavDropdownControl, ClickableNavDropdownControl]#: The control that opens and closes menu

icon: Optional[Union[str, TablerMenuIcon]] = None#: this is either the name of a bootstrap icon, or a TablerMenuIcon class or subclass

items: Iterable[MenuItem] = []#: The list of items in this dropdown menu

menu: DropdownMenu#: The DropdownMenu that control opens

tag: str = 'li'#: The name of the HTML element to use as our tag, e.g. div

text: Optional[str] = None#: The actual name of the dropdown

url: Optional[str] = None#: The URL for the control text. Use this if you want text to be clickable separately from opening the dropdown menu

class NavItem(text: Optional[str] = None, icon: Optional[Union[str, TablerMenuIcon]] = None, url: Optional[str] = None, active: bool = False, item: Optional[MenuItem] = None, **kwargs)[source]#

Bases: Block

An entry in a Menu, the top level menu class used in a Navbar in the menu section. This is a label with a link to a URL, with an optional icon preceding the label.

Typically, you won’t use this directly, but instead it will be created for you from a MenuItem specification.

If url and the url kwarg are None, this will be a heading instead of an item that links to a URL.

Examples

With keyword arguments:

>>> icon = TablerMenuIcon(icon='target')
>>> item = NavItem(text='Page', url='/page', icon=icon)

With a MenuItem:

>>> menu_item = MenuItem(text='Page', url='/page', icon='target')
>>> item2 = NavItem(item=menu_item)

Adding a in-menu heading:

>>> item3 = NavItem(text='My Heading')

Kewyword Args:: icon: Either the name of a Bootstrap icon, or a TablerMenuIcon object text: The text for the item url: The URL for the item active: True if this represents the page we’re currently on item: a MenuItem

Raises:: ValueError – one or more of the settings failed validation

block: str = 'nav-item'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

icon: Optional[Union[str, TablerMenuIcon]] = None#: Either the name of a Bootstrap icon, or a TablerMenuIcon object

tag: str = 'li'#: The name of the HTML element to use as our tag, e.g. div

text: Optional[str] = None#: The text for the item.

url: Optional[str] = None#: The URL for the item.

class NavLinkToggle(text: Optional[str] = None, icon: Optional[Union[str, TablerMenuIcon]] = None, active: bool = False, collapse_id: Optional[str] = None, **kwargs)[source]#

Bases: Link

This is a control for a wildewidgets.widgets.structure.CollapseWidget that is some text with an open/closed indicator. Clicking on the text opens or closes the CollapseWidget.

This differs from wildewidgets.widgets.buttons.CollapseButton in that it doesn’t have button styling, and has the open/closed indicator.

Keyword Arguments:

icon – Either the name of a Bootstrap icon, or a TablerMenuIcon object
text – The text for the item
active – True if this represents the page we’re currently on
collapse_id – the CSS id of the wildewidgets.widgets.structure.CollapseWidget

collapse() → None[source]#: Set our aria-expanded attribute to false.

expand() → None[source]#: Set our aria-expanded attribute to true.

active: bool#: This item is active, but nothing in the related DropdownMenu is

aria_attributes: Dict[str, str] = {'expanded': 'false'}#: Additional aria- attributes to set on this block

block: str = 'nav-link'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

collapse_id: Optional[str] = None#: The CSS id of the Collapse that we control

data_attributes: Dict[str, str] = {'toggle': 'collapse'}#: Additional data-bs- attributes to set on this block

icon: Optional[Union[str, TablerMenuIcon]] = None#: Either the name of a Bootstrap icon, or a TablerMenuIcon class or subclass

name: str = 'nav-link-toggle'#: The CSS class that will be added to this element to as an identifier for this kind of block

text: Optional[str] = None#: The title for the link

class Navbar(*blocks: Block, contents_id: Optional[str] = None, branding: Optional[Block] = None, hide_below_viewport: Optional[str] = None, container_size: Optional[str] = None, dark: Optional[bool] = None, background_color: Optional[str] = None, **kwargs)[source]#

Bases: Block

A horizontal Bootstrap Navbar.

Examples

With a subclass:

class MyMenu(Menu):
    items = [MenuItem(text='One', url='/one', icon='target)]

class MyNavbar(Navbar):
    branding = LinkedImage(src='/static/branding.png', alt='My Brand', url='#')
    contents = [MyMenu()]

With Navbar constructor arguments:

>>> branding = LinkedImage(src='/static/branding.png', alt='My Brand', url='#')
>>> items = [MenuItem(text='One', url='/one'), ... ]
>>> menu = Menu(*items)
>>> sidebar = Navbar(menu, branding=branding)

Adding menus later:

>>> items2 = [MenuItem(text='Foo', url='/foo'), ... ]
>>> menu2 = Menu(*items)
>>> sidebar.add_to_menu_section(menu2)

Note

You can add other things to the menu section than just menus. For instance, a search form:

class SearchFormBlock(Block):
    ...

class MyMenu(Menu):
    items = [MenuItem(text='One', url='/one', icon='target)]

class MyNavbar(Navbar):
    branding = LinkedImage(src='/static/branding.png', alt='My Brand', url='#')
    contents = [SearchFormBlock(), MyMenu()]

Parameters:

*blocks – a list of wildewidget.Block (or subclass) instances to be added to this container

Keyword Arguments:

branding – A block that will be displayed at the top of the container. A good choice might be a LinkedImage or Image
logo_width – The width for the logo image. Any valid value for CSS width will be accepted.
title – A title. If logo is None, this will be used in its place. If logo is not None, this will be used as the image alt attribute.
contents_id – the CSS id of the menu container. Typically you won’t need to change this unless you have namespace collisions with other CSS ids on your page.

activate(text: str) → bool[source]#

Loop through all the Menu blocks in menu_container and set the first menu item we find that matches text to be active.

Parameters:: text – the value to which to compare to menu items
Returns:: If we actually did set an item to be active, return True, otherwise return False

add_blocks() → None[source]#

Overrides wildewidgets.widgets.base.Block.add_blocks.

We’re overriding wildewidgets.widgets.base.Block.add_blocks here so that it does nothing because we need to add menus not to our top level tag content, but only to the menu section of ourselves, :py;attr:menu_container.

menu_container doesn’t exist yet when we run the constructor for wildewidgets.widgets.base.Block, which is where add_blocks runs.

add_to_menu_section(block: Block) → None[source]#

Add a block to the menu specfic section of the sidebar, menu_container. The menu specific section will be hidden and controlled by the hamburger menu when we drop below a specific viewport.

Warning

Use this to add your blocks to this Navbar instead of using add_block.

Parameters:: block – the block to add to the menu section

build_brand() → None[source]#: Build our .navbar-brand block and add it to inner, our content container. We’re doing this in a method here so we can override it in subclasses.

VALID_BACKGROUND_COLORS: List[str] = ['blue', 'azure', 'indigo', 'purple', 'pink', 'red', 'orange', 'yellow', 'lime', 'green', 'teal', 'cyan', 'white']#: Valid background colors. Note that these are Tabler colors, not Bootstrap colors. We use Tabler colors because Tabler also defines an appropriate foreground color for each background color.

VALID_BREAKPOINTS: List[str] = ['sm', 'md', 'lg', 'xl', 'xxl']#: Valid values for navbar-expand-. From Navbar: How It Works

background_color: Optional[str] = None#

#1d273b

Type:: If dark is True, set the background color. Default

block: str = 'navbar'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

branding: Optional[Block] = None#: This is the branding block at the start of the navbar

container_size: str = 'fluid'#: The width of our actual navbar

contents: Iterable[Block] = []#: A list of blocks to include in our sidebar

contents_id: str = 'sidebar-menu'#: the CSS id of the menu container. Typically you won’t need to change this unless you have namespace collisions with other CSS ids on your page.

dark: bool = False#: Set to True to use a dark background instead of light

hide_below_viewport: str = 'lg'#: The viewport size at which our menu container collapses to be hidden, requiring the hamburger menu to show

menu_container: Block#: This is the container for all menus

tag: str = 'aside'#: The name of the HTML element to use as our tag, e.g. div

class NavbarMixin[source]#

Bases: object

This is a Django class based view mixin that offers methods and attributes for managing how your Navbar classes get rendered in your template.

To use MenuMixin, you must, in the template for your view, render the menu and submenu context parameters with the wildewidgets template tag. These will be the Navbar subclasses that MenuMixin.get_context_data adds to the template context. For example:

<html>
  <head>
    {# wildewdigets css and js requirements #}
  </head>
  <body>
    {% wildewidgets menu %}
    <div class="page">
        ...
        {% wildewidgets submenu %}
        ...
    </div>
  </body>
</html

Example

This is the most basic example of how to use NavbarMixin to manage a Navbar with a Menu inside it and have one of the menu items be marked as active:

from django.views import View
from django.urls import reverse_lazy
from wildewidgets import (
    TablerVerticalNavbar,
    Menu,
    MenuItem,
    NavbarMixin
)

class MainMenu(Menu):
    items = [
        MenuItem(
            text='Projects',
            icon='bookshelf',
            url=reverse_lazy('myapp:project--list')
        ),
        MenuItem(
            text='Users',
            icon='users',
            url=reverse_lazy('myapp:users--list')
        )
    ]

class NavigationSidebar(TablerVerticalNavbar):
    branding = LinkedImage(
        image_src=static("myapp/images/logo.png"),
        image_width='100%',
        image_alt="My App",
        url="/"
    )

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.add_to_menu_section(MainMenu())


class MyView(NavbarMixin, View):

    navbar_class = NavigationSidebar
    menu_item = 'Projects'

    ...

This defines our navbar NavigationSidebar, adds MainMenu` to it, assigns it as our main menu (via ``MyView.navbar_class), and activates the “Projects” item in the main menu (via MyView.menu_item).

If we wanted to have a secondary navbar also, just define a new Navbar subclass, with a secondary_menu_item:

class SecondaryMenu(Menu):
    ...

class ContextualNavbar(Navbar):
    ...

class MyView(NavbarMixin, View):

    navbar_class = NavigationSidebar
    menu_item = 'Projects'
    secondary_navbar_class = ContextualNavbar
    secondary_menu_item = 'The item'

    ...

navbar_class#

The Navbar` subclass that acts as our primary navigation

alias of Navbar

get_context_data(**kwargs) → Dict[str, Any][source]#

Add our main navbar and our secondary navbar (if we have one) to the context data for our view as the menu and submenu kwargs, respectively

Returns:: The updated context data.

get_menu_item() → Optional[str][source]#

Return the text or URL of an item to set active among the menus in our main Navbar class.

Returns:: The class of the Navbar subclass to use for our main menu.

get_navbar() → Navbar[source]#

Instantiate and return our Navbar subclass for our main navbar.

Returns:: The instantiated Navbar subclass instance to use for our main navbar.

get_navbar_class() → Type[Navbar][source]#

Return the Navbar subclass for the main menu. Overriding this will allow you to programmatically determine your at view time.

Returns:: The class of the Navbar subclass to use for our main menu.

get_secondary_menu_item() → Optional[str][source]#: Return the text of an item to set active in our secondary menu

get_secondary_navbar() → Optional[Navbar][source]#

Instantiate and return our Navbar subclass for our secondary navbar.

Returns:: The instantiated Navbar subclass instance to use for our secondary menu, if any.

get_secondary_navbar_class() → Optional[Type[Navbar]][source]#

Return our Navbar subclass for the secondary navbar.

Returns:: The class of the Navbar subclass to use for our secondary navbar, if any.

menu_item: Optional[str] = None#: The text or URL of an item in one of our navbar_class menus to set active

secondary_menu_item: Optional[str] = None#: The text or URL of an item in one of our secondary_navbar_class menus to set active

secondary_navbar_class: Optional[Type[Navbar]] = None#: The Navbar subclass that holds our secondary menus

class NavigationTogglerButton(target: Optional[str] = None, label: Optional[str] = None, **kwargs)[source]#

Bases: Block

The navbar-toggler button for hiding and showing menus in responsive Bootstrap Navbar containers , styled with some Tabler styling. This is the hamburger icon that causes the menus to appear and disappear when we drop below a specific viewport size.

Example:

>>> toggler = NavigationTogglerButton(target='the_target')

Keyword Arguments:

target – the CSS id of the tag to toggle
label – the ARIA label of this button

aria_attributes: Dict[str, str] = {'expanded': 'false'}#: Additional aria- attributes to set on this block

attributes: Dict[str, str] = {'type': 'button'}#: Additional HTML attributes to set on this block

block: str = 'navbar-toggler'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

css_class: str = 'collapsed'#: A string of CSS classes to apply to this block

data_attributes: Dict[str, str] = {'toggle': 'collapse'}#: Additional data-bs- attributes to set on this block

label: str = 'Toggle navigation'#: The ARIA label for this button

tag: str = 'button'#: The name of the HTML element to use as our tag, e.g. div

target: Optional[str] = None#: The CSS id of the tag that this button toggles

class TablerVerticalNavbar(*args, wide: Optional[bool] = None, **kwargs)[source]#

Bases: Navbar

Make this a Tabler vertical dark navbar.

Make the navbar vertical instead of horizontal
dark is always True
Fix width of sidebar at 15rem, unless wide is True, when we set it to 18rem.
CSS position is always fixed.
Supply some open/close animations.

Some caveats:

container_size is ignored

Example

>>> branding = LinkedImage(
    src='/static/branding.png',
    alt='My Brand',
    url='https://example.com',
    width='100%`
)
>>> items = [MenuItem(text='One', url='/one'), ... ]
>>> menu = TablerMenu(*items)
>>> sidebar = TablerVerticalNavbar(menu, branding=branding)

Keyword Arguments:: wide – If True, make the navbar width be 18rem instead of 15rem

build_brand() → None[source]#

Overrides Navbar.build_brand.

Wrap our branding in an <h1> and give that <h1> the navbar-brand class because that’s how Tabler does it.

block: str = 'navbar navbar-vertical'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

dark: bool = True#: Set to True to use a dark background instead of light

wide: bool = False#: Make the navbar 18rem wide instead of 15rem

is_url(text: str) → bool[source]#

if text looks like a URL or path, return True.

Parameters:: text – the string to check
Returns:: True if text looks like a URL or path, False otherwise.