Structure Widgets#

Bases: Block

Renders a Bootstrap 5 Card.

This widget creates a Bootstrap card component with optional header, title, subtitle, and body content.

template_name#

The Django template to use for rendering this widget

Type:: str

block#

The name of the block in the template for CSS styling

Type:: str

header#

Optional header widget to display at the top of the card

Type:: wildewidgets.widgets.headers.BasicHeader | None

header_text#

Optional text to use for a simple header (if header is not provided)

Type:: str | None

header_css#

Optional CSS classes to apply to the header

Type:: str | None

card_title#

Optional title for the card

Type:: str | None

card_subtitle#

Optional subtitle for the card

Type:: str | None

widget#

The main widget to display in the card body (required)

Type:: wildewidgets.widgets.base.Widget | None

widget_css#

Optional CSS classes to apply to the widget

Type:: str | None

overflow#

CSS overflow attribute for the card

Type:: str

Example

from wildewidgets import CardWidget, Block

# Simple card with just a widget
card = CardWidget(
    widget=Block("Card content"),
    card_title="My Card",
    card_subtitle="Card subtitle"
)

# Card with a header and custom widget CSS
card = CardWidget(
    header_text="Card Header",
    widget=Block("Card content"),
    widget_css="p-4"
)

Parameters:

*blocks – Child blocks to include in the card body

Keyword Arguments:

header – Optional header widget to display at the top of the card
header_text – Optional text to use for a simple header (if header is not provided)
header_css – Optional CSS classes to apply to the header
card_title – Optional title for the card
card_subtitle – Optional subtitle for the card
widget – The main widget to display in the card body (required)
widget_css – Optional CSS classes to apply to the widget
overflow – CSS overflow attribute for the card

get_context_data(*args, **kwargs)[source]#

Prepare the context data for template rendering.

Adds the card components (header, title, subtitle, widget) to the context.

Parameters:

*args – Positional arguments passed to parent method
**kwargs – Keyword arguments passed to parent method

Returns:

The updated context dictionary with card-specific data

Return type:

dict

Raises:

ImproperlyConfigured – If no widget is defined for the card

set_header(header)[source]#

Set or replace the header widget displayed at the top of the card.

Parameters:: header – The header widget to display

set_widget(widget, css_class=None)[source]#

Set or replace the main widget displayed in the card body.

Parameters:

widget – The widget to display in the card body
css_class – Optional CSS classes to apply to the widget

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

template_name: str = 'wildewidgets/card_block.html'#: The name of the template to use to render this block

Bases: Block

A Bootstrap Collapse widget.

This widget creates a collapsible content area that can be toggled open or closed by a CollapseButton or other trigger element. It’s useful for hiding content that isn’t immediately relevant but might be needed later.

Note

A CollapseWidget needs a trigger element (like a wildewidgets.CollapseButton) with the data-toggle=”collapse” attribute and a data-target pointing to this widget’s ID.

Example

from wildewidgets import CollapseWidget, CardHeader, CrispyFormWidget

collapse_id = 'my-collapse-id'
collapse = CollapseWidget(
    CrispyFormWidget(form=form),
    css_id=collapse_id,
    css_class="pt-3",
)

header = CardHeader(header_text="Services")
header.add_collapse_button(
    text="Manage",
    color="primary",
    target=f"#{collapse_id}",
)

block: str = 'collapse'#: The Django template to use for rendering this widget.

class HorizontalLayoutBlock(*blocks, align: str | None = None, justify: str | None = None, flex_size: str | None = None, **kwargs)[source]#

Bases: Block

A container that aligns child widgets horizontally using flexbox.

This widget creates a horizontal layout for its child widgets using Bootstrap’s flexbox utilities. It provides options for controlling vertical and horizontal alignment, as well as responsive behavior.

Example

from wildewidgets import HorizontalLayoutBlock, LabelBlock, Block

# Create a layout with right-aligned items and centered vertical alignment
layout = HorizontalLayoutBlock(
    LabelBlock("Label"),
    Block("Content 1"),
    Block("Content 2"),
    justify="end",
    align="center",
    flex_size="md",  # Stack vertically on screens smaller than medium
    css_class="mt-3"
)

Parameters:

*blocks – Child blocks to include in the horizontal layout

Keyword Arguments:

align – Vertical alignment of items
justify – Horizontal alignment of items
flex_size – Bootstrap viewport size below which items stack vertically
**kwargs – Additional keyword arguments passed to the parent class

VALID_ALIGNMENTS: Final[list[str]] = ['start', 'center', 'end', 'baseline', 'stretch']#: The valid column content justify-content- values

VALID_JUSTIFICATIONS: Final[list[str]] = ['start', 'center', 'end', 'between', 'around', 'evenly']#: The valid column content justify-content- values

align: str = 'center'#

start, center, end, baselin, stretch. See Bootstrap: Flex, justify content. If not supplied here and align is None, do whatever vertical aligment Bootstrap does by default.

Type:: How to align items veritcally within this widget. Valid choices

flex_size: str | None = None#: the Boostrap viewport size below which this will be a vertical list instead of a horizontal one.

justify: str = 'between'#: How to align items horizontally within this widget. Valid choices: start, : center, end, between, around, evenly. See Bootstrap: Flex, justify content. If not supplied here and justify is None, do whatever horizontal aligment Bootstrap does by default.

class ListModelCardWidget(*args, list_model_widget_class: type[wildewidgets.widgets.base.Widget] | None = None, list_model_header_class: type[wildewidgets.widgets.base.Widget] | None = None, placeholder: str | None = None, **kwargs)[source]#

Bases: CardWidget

A card widget containing a filterable list of model instances.

This widget creates a card with a header containing a filter input field and a body containing a list of model instances. The filter input allows users to filter the list by typing.

Example

from wildewidgets import ListModelCardWidget
from myapp.models import Author
from myapp.widgets import AuthorListWidget

# Basic usage with default list widget
widget = ListModelCardWidget(
    queryset=Author.objects.all()[:10]
)

# Custom list widget and placeholder
widget = ListModelCardWidget(
    queryset=Author.objects.all(),
    list_model_widget_class=AuthorListWidget,
    placeholder="Search authors...",
    item_label="author"
)

Parameters:

*args – Positional arguments passed to parent class

Keyword Arguments:

list_model_widget_class – Optional custom widget class for the list model
list_model_header_class – Optional custom header widget class
placeholder – Placeholder text for the filter input field
**kwargs – Keyword arguments passed to parent class

list_model_widget_class#

The Widget subclass to use for the list model widget.

alias of ListModelWidget

get_list_model_header(*args, **kwargs)[source]#

Create the header widget with filter input.

If list_model_header_class is defined, it uses that. Otherwise, it creates a default header with a filter input field.

Parameters:

*args – Positional arguments for the header
**kwargs – Keyword arguments for the header

Returns:

The header widget instance

Return type:

Widget

get_list_model_widget(*args, **kwargs)[source]#

Create the list model widget.

Parameters:

*args – Positional arguments for the list model widget
**kwargs – Keyword arguments for the list model widget

Returns:

The list model widget instance

Return type:

Widget

SCRIPT: str = '\nvar filter_input = document.getElementById("{filter_id}");\nfilter_input.onkeyup = function(e) {{\n var filter = e.target.value.toLowerCase();\n document.querySelectorAll("{query} label").forEach(label => {{\n var test_string = label.innerText.toLowerCase();\n if (test_string.includes(filter)) {{\n label.closest(\'.listmodelwidget__item\').classList.remove(\'d-none\');\n }}\n else {{\n label.closest(\'.listmodelwidget__item\').classList.add(\'d-none\');\n }}\n }});\n let children = document.querySelectorAll("{query} li");\n for (let i=0; i < children.length; i++) {{\n let child = children[i];\n child.classList.remove(\'border-top\');\n }};\n for (let i=0; i < children.length; i++) {{\n let child = children[i];\n if (child.classList.contains(\'d-none\')) {{\n }}\n else {{\n child.classList.add(\'border-top\');\n break;\n }}\n }};\n}};\n\n'#: The script to use for filtering the list of objects.

list_model_header_class: type[Widget] | None = None#: The Widget subclass to use for the header.

class ListModelWidget(*args, remove_url: str | None = None, **kwargs: Any)[source]#

Bases: MultipleModelWidget

A widget that displays a list of model instances.

This widget creates an unordered list of items, with each item displaying a single model instance. It can optionally include buttons for removing items.

Example

from wildewidgets import ListModelWidget
from django.urls import reverse

# Create a list with remove buttons
widget = ListModelWidget(
    queryset=parent.children.all(),
    item_label='child',
    remove_url=reverse('remove_child') + "?id={}",
)

# Create a read-only list with custom model widget
widget = ListModelWidget(
    queryset=Author.objects.all(),
    model_widget=AuthorWidget,
    item_label='author'
)

Parameters:

*args – Positional arguments passed to parent class

Keyword Arguments:

remove_url – Optional URL format string for removing items (with {} placeholder for ID)
**kwargs – Keyword arguments passed to parent class

Raises:

ValueError – If model_widget is not defined and no model instance is provided
ImproperlyConfigured – If neither model nor queryset is defined

get_confirm_text(instance: Model) → str[source]#

Get the confirmation text for removing a specific model instance.

This text is used in the confirmation dialog when removing an item.

Parameters:: instance – The model instance to get the confirmation text for
Returns:: The confirmation text for removing the instance
Return type:: str

get_model_subblock(instance: Model)[source]#

Create a block for displaying a model instance.

If the model instance has a get_absolute_url method, the text will be wrapped in a link to that URL.

Parameters:: instance – The model instance to create a block for
Returns:: A block for displaying the model instance
Return type:: Block

get_model_widget(object: Model, **kwargs) → Widget[source]#

Create a widget for a specific model instance.

If model_widget is defined, it uses that. Otherwise, it creates a default widget with the instance text and an optional remove button.

Parameters:: object – The model instance to create a widget for
Keyword Arguments:: **kwargs – Additional keyword arguments for the widget
Returns:: The widget for displaying the model instance
Return type:: Widget
Raises:: ValueError – If obj is None and model_widget is not defined

get_object_text(instance: Model) → str[source]#

Get the display text for a specific model instance.

Parameters:: instance – The model instance to get the display text for
Returns:: The display text for the instance (defaults to str(instance))
Return type:: str

get_remove_url(instance: Model) → str[source]#

Get the URL for removing a specific model instance.

Parameters:: instance – The model instance to get the remove URL for
Returns:: The URL for removing the instance, or an empty string if not configured
Return type:: str

block: str = 'list-group'#: The name of the block in the template for CSS styling.

name: str = 'wildewidgets-list-model-widget'#: Another name for this widget, used in addition to the block name.

remove_url: str | None = None#: The url to “POST” to in order to delete or remove the object.

show_no_items: bool = True#: If True, show a message when there are no items in the list.

tag: str = 'ul'#: The HTML tag to use for the container

Bases: Block

Base class for widgets that display multiple model instances.

This abstract class provides common functionality for widgets that display a list of model instances, such as PagedModelWidget and ListModelWidget.

Note

Either model or queryset must be provided, but not both.

Example

from wildewidgets import MultipleModelWidget
from myapp.models import MyModel
from myapp.widgets import MyModelWidget

class MyListWidget(MultipleModelWidget):
    model = MyModel
    model_widget = MyModelWidget
    ordering = "-created_at"
    item_label = "item"

Parameters:

*blocks – Child blocks to include in the widget

Keyword Arguments:

model – The Django model class to query for instances
queryset – A pre-defined queryset to use for fetching model instances
ordering – The ordering to apply to the queryset (default is None)
model_widget – The widget class to use for rendering each model instance
model_kwargs – Optional keyword arguments to pass to the model widget
item_label – The label to use for each instance (default is “item”)

Raises:

ImproperlyConfigured – If both model and queryset are defined, or if neither is defined, or if model_widget is not defined.

get_item_label(instance: Model) → str[source]#

Get the label to use for a specific model instance.

This label is used in confirmation dialogs and other UI elements.

Parameters:: instance – The model instance to get the label for
Returns:: The label for the instance (defaults to the class’s item_label)
Return type:: str

get_model_widget(object: Model, **kwargs) → Widget[source]#

Create a widget for a specific model instance.

This method creates and returns a widget for displaying a single model instance.

Parameters:

object – The model instance to create a widget for
**kwargs – Additional keyword arguments to pass to the widget constructor

Returns:

The widget for displaying the model instance

Return type:

Widget

Raises:

ImproperlyConfigured – If model_widget is not defined and this method is not overridden

get_model_widgets(instances: list[Model]) → list[Widget][source]#

Create widgets for a list of model instances.

Parameters:: instances – List of model instances to create widgets for
Returns:: List of widgets for displaying the model instances
Return type:: list[Widget]

get_queryset() → list[Model] | QuerySet[source]#

Get the queryset of model instances to display.

This method fetches the model instances to display, either from the provided queryset or by querying the model.

Returns:: The model instances to display
Return type:: list[Model] | QuerySet
Raises:: ImproperlyConfigured – If neither model nor queryset is defined

item_label: str = 'item'#: The label to use for each instance. This is used in the confirmation dialog when deleting instances.

model: type[Model] | None = None#: If this is defined, do self.model.objects.all() to get our list of instances. Define either this or queryset, but not both.

model_kwargs: dict[str, Any] = {}#: When instantiating model_widget, pass this dict into the widget constructor as the keyword arguments

model_widget: type[Widget] | None = None#: Use this widget class to render each model instance.

ordering: str | tuple[str, ...] | None = None#: The ordering to use for the queryset. This will be applied to both model and queryset

queryset: QuerySet | None = None#: Use this queryset to get our list of instances. Define either this or model, but not both.

class PageTabbedWidget(*blocks, slug_suffix: str | None = None, overflow: str | None = None, **kwargs)[source]#

Bases: Block

Implements a Tabler Tabbed Card.

This widget creates a tabbed interface where the active tab displays a widget, and other tabs are links to other pages. When those links are followed, the corresponding tab becomes active on the new page. This way, only the active widget needs to be rendered.

Example

from wildewidgets import PageTabbedWidget, TabConfig, Block

tab = PageTabbedWidget()
tab.add_link_tab('My First Tab', 'my_first_page_url')
tab.add_link_tab('My Second Tab', 'my_second_page_url')
tab.add_active_tab('My Third Tab', widget)

Parameters:

*blocks – Child blocks to include in the tabbed interface

Keyword Arguments:

slug_suffix – Optional suffix for the slug in the URL to differentiate between multiple instances of this widget on the same page
overflow – CSS overflow attribute for the widget (default is “auto”)
**kwargs – Additional keyword arguments passed to the parent class

add_active_tab(name: str, widget: Block) → None[source]#

Add a tab that displays a widget.

Creates a tab that is initially active and displays the specified widget.

Parameters:

name – The display name of the tab
widget – The widget to display when this tab is active

add_link_tab(name: str, url: str) → None[source]#

Add a tab that links to another page.

Creates a tab that, when clicked, navigates to the specified URL. This is used for tabs that are not currently active.

Parameters:

name – The display name of the tab
url – The URL to navigate to when the tab is clicked

get_context_data(*args, **kwargs)[source]#

Prepare the context data for template rendering.

Adds the tabs, widget, and unique identifier to the template context.

Parameters:

*args – Positional arguments passed to parent method
**kwargs – Keyword arguments passed to parent method

Returns:

The updated context dictionary with tab-specific data

Return type:

dict

block: str = 'card'#: The name of the block in the template for CSS styling.

overflow: str = 'auto'#: The CSS overflow attribute for the widget.

slug_suffix: str | None = None#: The suffix to use for the slug in the URL. This is used to differentiate between multiple instances of this widget on the same page. This is set to a random number between 0 and 10000 if not provided.

template_name: str = 'wildewidgets/page_tab_block.html'#: The Django template to use for rendering this widget.

class PagedModelWidget(*blocks, page_kwarg: str | None = None, paginate_by: int | None = None, extra_url: dict[str, Any] | None = None, **kwargs)[source]#

Bases: MultipleModelWidget

A widget that displays a paginated list of model instances.

This widget creates a paginated list of widgets, with each widget displaying a single model instance. It includes pagination controls for navigating between pages.

Example

from wildewidgets import PagedModelWidget, MyObjectWidget

widget = PagedModelWidget(
    queryset=mymodel.myobject_set.all(),
    paginate_by=10,
    page_kwarg='page',
    model_widget=MyObjectWidget,
    model_kwargs={'foo': 'bar'},
    item_label="object",
    extra_url={
        'pk': mymodel.id,
        '#': 'objects',
    },
)

Parameters:

*blocks – Child blocks to include in the widget

Keyword Arguments:

model – The Django model class to query for instances (optional)
queryset – A pre-defined queryset to use for fetching model instances
ordering – The ordering to apply to the queryset (default is None)
model_widget – The widget class to use for rendering each model instance
model_kwargs – Optional keyword arguments to pass to the model widget
item_label – The label to use for each instance (default is “item”)
extra_url – Additional URL parameters to include in pagination links
page_kwarg – The GET parameter name for the page number (default is “page”)
paginate_by – Number of items per page (default is 25)
max_page_controls – Maximum number of page controls to display (default is 5)s

get_context_data(*args, **kwargs)[source]#

Prepare the context data for template rendering.

This method: 1. Handles pagination of the model instances 2. Creates widgets for the current page of instances 3. Prepares pagination controls and context 4. Adds any extra URL parameters for pagination links

Parameters:

*args – Positional arguments passed to parent method
**kwargs – Keyword arguments passed to parent method

Returns:

The updated context dictionary with pagination-specific data

Return type:

dict

Raises:

Http404 – If an invalid page number is requested

block: str = 'wildewidgets-paged-model-widget'#: The name of the block in the template for CSS styling.

max_page_controls: int = 5#: Extra parameters passed in the page links.

page_kwarg: str = 'page'#: The get argument for the page number. Defaults to page.

paginate_by: int = 25#: Number of widgets per page. Defaults to all widgets.

template_name: str = 'wildewidgets/paged_model_widget.html'#: The Django template to use for rendering this widget.

class TabConfig(name: str, widget: wildewidgets.widgets.base.Block | None = None, active: bool = False, link: str | None = None)[source]#

Bases: object

Used to configure the tabs in a PageTabbedWidget.

This class holds configuration for an individual tab within a tabbed interface, including its name, active state, and optional link.

Parameters:

name – The display name of the tab
widget – Optional block to display when this tab is active
active – Whether this tab should be initially active
link – Optional URL for linking to another page

name#: The display name of the tab

active#: Whether this tab is active (selected)

link#: URL for the tab if it links to another page

class TabbedWidget(*blocks, slug_suffix: str | None = None, overflow: str | None = None, **kwargs)[source]#

Bases: Block

Implements a Tabler Tabbed Card.

This widget creates a tabbed interface where all tabs are rendered client-side (unlike PageTabbedWidget which only renders the active tab). The tabs are switched using JavaScript, without page navigation.

Example

from wildewidgets import TabbedWidget, Block

widget1 = Block("This is the first widget")
widget2 = Block("This is the second widget")
tab = TabbedWidget()
tab.add_tab('My First Widget', widget1)
tab.add_tab('My Second Widget', widget2)

Parameters:

*blocks – Child blocks to include in the tabbed interface

Keyword Arguments:

slug_suffix – Optional suffix for the slug in the URL to differentiate between multiple instances of this widget on the same page
overflow – CSS overflow attribute for the widget (default is “auto”)
**kwargs – Additional keyword arguments passed to the parent class

add_tab(name: str, widget: Block) → None[source]#

Add a tab to the tabbed interface.

Creates a tab with the specified name that displays the specified widget when the tab is selected.

Parameters:

name – The display name of the tab
widget – The widget to display when this tab is selected

get_context_data(*args, **kwargs)[source]#

Prepare the context data for template rendering.

Adds the tabs and unique identifier to the template context.

Parameters:

*args – Positional arguments passed to parent method
**kwargs – Keyword arguments passed to parent method

Returns:

The updated context dictionary with tab-specific data

Return type:

dict

block: str = 'card'#: The name of the block in the template for CSS styling.

overflow: str = 'auto'#: The CSS overflow attribute for the widget.

slug_suffix: str | None = None#: The suffix to use for the slug in the URL. This is used to differentiate between multiple instances of this widget on the same page. If not provided, a random number between 0 and 10000 will be used. This is used to ensure that the tabs are unique on the page.

tabs: list[tuple[str, Block]]#: A list of tuples containing the name of the tab and the widget to display in that tab. Each tuple is of the form (name, widget), where name is a string and widget is a Block.

template_name: str = 'wildewidgets/tab_block.html'#: The Django template to use for rendering this widget.