Header Widgets#

class BasicHeader(header_level: int | None = None, header_type: str | None = None, header_text: str | None = None, css_class: str | None = None, css_id: str | None = None, badge_text: str | None = None, badge_class: str | None = None, badge_rounded_pill: bool | None = None, **kwargs: Any)[source]#

Bases: TemplateWidget

The base header class for all header widgets in the wildewidgets library.

This class provides the core functionality for rendering HTML headers with various styling options, including optional badges. All other header classes inherit from this class.

Example

from wildewidgets import BasicHeader

header = BasicHeader(
    header_text="Welcome to the Dashboard",
    header_level=1,
    badge_text="New",
    badge_class="success"
)
template_name#

Path to the Django template used for rendering

Type:

str

header_level#

HTML heading level (1-6) to use

Type:

int

header_type#

Type of header styling (“h” for standard, “display” for larger)

Type:

str

header_text#

The text content of the header

Type:

str | None

css_class#

CSS classes to apply to the header container

Type:

str

css_id#

Optional ID attribute for the header element

Type:

str | None

badge_text#

Optional text for a badge beside the header

Type:

str | None

badge_class#

Bootstrap color class for the badge (e.g., “primary”, “warning”)

Type:

str

badge_rounded_pill#

Whether to style the badge as a rounded pill

Type:

bool

Keyword Arguments:

  • header_level – the header depth, as in h1, h2, h3…

  • header_type – the Boostrap 5 header class, either h-, or display-.

  • header_text – the text of the header.

  • css_class – any css classes to apply to the header.

  • css_id – an ID to add to the header div.

  • badge_text – text to add in a badge to the right of the main header text.

  • badge_class – the css class to add to the badge.

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

Prepare the context data for template rendering.

Processes header settings and adds them to the template context. Sets the appropriate header class based on the header type and level, and includes all other header properties.

Parameters:

**kwargs – Initial context dictionary

Returns:

Updated context dictionary with header properties

Return type:

dict

class CardHeader(widget: wildewidgets.widgets.base.Block | None = None, **kwargs: Any)[source]#

Bases: HeaderWithWidget

A header specifically designed for Bootstrap card components.

This provides an H2 header with appropriate styling for use as a card header, with the option to include an action button or other widget.

Example

from wildewidgets import CardHeader, LinkButton

header = CardHeader(
    header_text="User Details",
    widget=LinkButton(text="Edit", url="/users/123/edit/")
)
class HeaderWithCollapseButton(collapse_id: str | None = None, button_text: str | None = None, button_class: str | None = None, **kwargs: Any)[source]#

Bases: BasicHeader

A header with a button that toggles a Bootstrap collapsible element.

This combines a heading element with a button that expands or collapses a target element when clicked. The collapsible element must be defined elsewhere in your template.

Deprecated:

This class is deprecated since version 0.13.45. Use HeaderWithWidget with the add_collapse_button method instead.

Example

from wildewidgets import HeaderWithCollapseButton

header = HeaderWithCollapseButton(
    header_text="Advanced Options",
    header_level=3,
    collapse_id="advanced-options",
    button_text="Toggle"
)
template_name#

Path to the template for rendering this widget

Type:

str

collapse_id#

ID of the collapsible element to toggle

Type:

str | None

button_text#

Text displayed on the button

Type:

str | None

button_class#

Bootstrap contextual class for the button

Type:

str | None

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

Prepare the context data for template rendering.

Adds collapse button specific variables to the context dictionary.

Parameters:

**kwargs – Initial context dictionary from parent class

Returns:

Updated context with collapse_id, button_text, and button_class

Return type:

dict

class HeaderWithFormButton(url: str | None = None, button_text: str | None = None, **kwargs: Any)[source]#

Bases: BasicHeader

A header with an attached form submission button.

This combines a heading element with a button that submits a form when clicked. The form must be defined elsewhere in your template.

Deprecated:

This class is deprecated since version 0.13.45. Use HeaderWithWidget with the add_form_button method instead.

Example

from wildewidgets import HeaderWithFormButton

header = HeaderWithFormButton(
    header_text="Dangerous Action",
    header_level=3,
    url="/api/delete-all/",
    button_text="Delete All"
)
template_name#

Path to the template for rendering this widget

Type:

str

url#

The URL that the form will submit to

Type:

str | None

button_text#

The text displayed on the button

Type:

str | None

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

Prepare the context data for template rendering.

Adds form button specific variables to the context dictionary.

Parameters:

**kwargs – Initial context dictionary from parent class

Returns:

Updated context with url and button_text

Return type:

dict

class HeaderWithLinkButton(url: str | None = None, link_text: str | None = None, button_class: str | None = None, **kwargs: Any)[source]#

Bases: BasicHeader

A header with an attached link button.

This combines a heading element with a button that links to a specified URL. The button appears to the right of the header text.

Deprecated:

This class is deprecated since version 0.13.45. Use HeaderWithWidget with the add_link_button method instead.

Example

from wildewidgets import HeaderWithLinkButton

header = HeaderWithLinkButton(
    header_text="Users",
    header_level=2,
    url="/users/add/",
    link_text="Add User",
    button_class="success"
)
template_name#

Path to the template for rendering this widget

Type:

str

url#

The URL that the button links to

Type:

str | None

link_text#

The text displayed on the button

Type:

str | None

button_class#

Bootstrap contextual class for the button

Type:

str

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

Prepare the context data for template rendering.

Adds link button specific variables to the context dictionary.

Parameters:

**kwargs – Initial context dictionary from parent class

Returns:

Updated context with url, link_text, and button_class

Return type:

dict

class HeaderWithModalButton(**kwargs: Any)[source]#

Bases: BasicHeader

A header widget with a button that triggers a Bootstrap modal.

This class combines a heading element with a button that opens a modal dialog when clicked. The modal must be defined elsewhere in your template.

Deprecated:

This class is deprecated since version 0.13.45. Use HeaderWithWidget with the add_modal_button

template_name#

Path to the template for rendering this widget

Type:

str

modal_id#

ID of the modal to be triggered by the button

Type:

str | None

button_text#

Text to display on the button

Type:

str | None

button_class#

Bootstrap button class (e.g., “primary”, “secondary”)

Type:

str

Keyword Arguments:

**kwargs – Keyword arguments including modal_id, button_text, and button_class, plus any arguments for BasicHeader

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

Prepare the context data for template rendering.

Adds modal button specific variables to the context dictionary.

Parameters:

**kwargs – Initial context dictionary from parent class

Returns:

Updated context with modal_id, button_text, and button_class

Return type:

dict

class HeaderWithWidget(widget: wildewidgets.widgets.base.Block | None = None, **kwargs: Any)[source]#

Bases: BasicHeader

A header widget that can contain another widget (typically a button).

This flexible header class allows adding any widget (most commonly buttons) next to the header text. This is the recommended approach for creating headers with interactive elements.

Example

from wildewidgets import HeaderWithWidget, LinkButton

# Create a header with a link button
header = HeaderWithWidget(
    header_text="Products List",
    header_level=2,
    widget=LinkButton(text="Add Product", url="/products/add/")
)

# Or add the button after initialization
header = HeaderWithWidget(header_text="Products List")
header.add_link_button(text="Add Product", url="/products/add/")
Parameters:

widget – Widget to display next to the header text

Keyword Arguments:

  • header_text – Text content of the header

  • header_level – HTML heading level (1-6)

  • **kwargs – Additional arguments passed to BasicHeader

add_collapse_button(**kwargs: Any) → None[source]#

Add a button that toggles a Bootstrap collapsible element.

This method creates a CollapseButton instance and adds it to the header. The button will toggle the visibility of the specified collapsible element.

Parameters:

**kwargs –

Arguments passed to wildewidgets.CollapseButton constructor. Common arguments include:

  • text: Button label text

  • target: Collapse target ID (with # prefix)

  • color: Bootstrap color class (default: “secondary”)

add_form_button(**kwargs: Any) → None[source]#

Add a form submission button to the header.

This method creates a FormButton instance and adds it to the header. The button will submit a form when clicked.

Parameters:

**kwargs –

Arguments passed to wildewidgets.FormButton constructor.

Common arguments include:

  • text: Button label text

  • action: Form submission URL

  • color: Bootstrap color class (default: “secondary”)

  • method: HTTP method (default: “post”)

  • confirm_text: Text for confirmation dialog (if needed)

Add a hyperlink button to the header.

This method creates a LinkButton instance and adds it to the header. The button will navigate to the specified URL when clicked.

Parameters:

**kwargs –

Arguments passed to wildewidgets.LinkButton constructor. Common arguments include:

  • text: Button label text

  • url: Target URL for the link

  • color: Bootstrap color class (default: “secondary”)

  • css_class: Additional CSS classes

add_modal_button(**kwargs: Any) → None[source]#

Add a button that triggers a Bootstrap modal dialog.

This method creates a ModalButton instance and adds it to the header. The button will open the specified modal when clicked.

Parameters:

**kwargs –

Arguments passed to wildewidgets.ModalButton constructor. Common arguments include:

  • text: Button label text

  • target: Modal ID to target (with # prefix)

  • color: Bootstrap color class (default: “secondary”)

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

Get the context data for rendering the template.

Adds the widget to the template context, along with other header properties.

Parameters:

**kwargs – Additional context variables

Returns:

Updated context dictionary including the widget

Return type:

dict

set_widget(widget: Block) → None[source]#

Set or replace the widget displayed next to the header.

This method allows setting any widget (not just buttons) to appear next to the header text. This provides flexibility beyond the specialized button methods.

Parameters:

widget – Any Block-derived widget to display in the header

class PageHeader(widget: wildewidgets.widgets.base.Block | None = None, **kwargs: Any)[source]#

Bases: HeaderWithWidget

Provides a standard page header.

This is an H1 header with a widget, typically used at the top of a page to provide a title and an action button or other interactive element.

Example

from wildewidgets import PageHeader, LinkButton

header = PageHeader(
    header_text="Welcome to the Dashboard",
    widget=LinkButton(text="Learn More", url="/about/")
)
class WidgetListLayoutHeader(widget: wildewidgets.widgets.base.Block | None = None, **kwargs: Any)[source]#

Bases: HeaderWithWidget

A specialized header for use with WidgetListLayout components.

This header is designed to match the styling of the WidgetListLayout component, providing consistent margins and header size. It can include an optional action button or other widget.

Example

from wildewidgets import WidgetListLayoutHeader, LinkButton

header = WidgetListLayoutHeader(
    header_text="Dashboard Widgets",
    widget=LinkButton(text="Add Widget", url="/widgets/add/")
)