Layout Widget#

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

Bases: Block

A navigational index of widgets.

This widget creates a visual index or table of contents for a collection of widgets. Each entry in the index consists of a widget with an associated title and icon.

Note

This is not something that you would use directly. WidgetListLayout uses this internally when you add widgets to the main content area.

template_name#

Path to the template used to render the widget index

Type:: str

block#

CSS block name for styling

Type:: str

entries#

Default list of widget index items

Type:: list[wildewidgets.widgets.layout.WidgetIndexItem]

Parameters:: *args – Positional arguments passed to parent
Keyword Arguments:: **kwargs – Keyword arguments which may include ‘entries’ to initialize the index with a list of WidgetIndexItem objects

add_widget(widget: Widget, title: str | None = None, icon: str | None = None) → None[source]#

Add a widget to the index.

Adds the given widget to the index with an associated title and icon. If title or icon are not provided, they will be determined from the widget attributes or defaults.

Note

If the widget has an is_visible function that evaluates to False, the widget will not be added to the index.

Parameters:

widget – The widget to add to the index
title – Optional display title for the widget. If None, uses widget.title1 or the widget class name
icon – Optional icon identifier. If None, uses widget.icon or “gear”

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

Get context data for template rendering.

Adds the widget index entries to the template context.

Parameters:

*args – Positional arguments passed to parent
**kwargs – Additional context variables

Returns:

Updated context dictionary with entries

Return type:

dict

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

property is_empty: bool#

Check if the widget index is empty.

Returns:: True if the index contains no entries, False otherwise
Return type:: bool

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

class WidgetIndexItem(widget: Widget, title: str, icon: str = 'gear')[source]#

Bases: object

Data container for items in a widget index.

This dataclass represents a single entry in a widget index, combining a widget instance with its display title and icon.

widget#

The widget instance to be displayed in the index

Type:: wildewidgets.widgets.base.Widget

title#

Display title for the widget in the index

Type:: str

icon#

Icon identifier to display next to the widget title, defaults to “gear”

Type:: str

class WidgetListLayout(title: str, sidebar_title: str | None = None, sidebar_width: int | None = None, sidebar_breakpoint: str | None = None, **kwargs)[source]#

Bases: Block

Provides a two column layout. The first column is the sidebar containing links to the various widgets in the right column, and the second column is the main content, consisting of the contained widgets vertically stacked.

This is really the only class you need to use to create a page with a sidebar and a main content area. You can add widgets to the sidebar and the main content area, and they will be displayed in the appropriate places.

Example

from wildewidgets import WidgetListLayout
from django.urls import reverse
from core.widgets import Widget1, Widget2, Widget3

layout = WidgetListLayout('My Page')
layout.add_sidebar_form_button('Update', reverse('core:thing--update'))
layout.add_widget(Widget1(), title='another title')
layout.add_widget(Widget2(), title='the title', icon='stuff')
layout.add_widget(Widget3())

Keyword Arguments:

title – The title of the widget.
sidebar_title – the title of the sidebar column
sidebar_width – the width in columns of the sidebar column
sidebar_breakpoint – the breakpoint at which the sidebar will collapse to a hamburger menu. Defaults to “xl” (extra large).
**kwargs – Additional keyword arguments passed to the parent *wildewidgets.Block class

add_modal(modal: Widget) → None[source]#

Add a modal widget to the layout.

Modals are typically used for dialogs or secondary content that overlays the main content.

Parameters:: modal – The modal widget to add
Returns:: None

add_sidebar_bare_widget(widget: Widget) → None[source]#

Add a bare widget to the sidebar.

Bare widgets are added outside the Actions area and are not subject to special styling.

Parameters:: widget – The widget to add to the sidebar

add_sidebar_form_button(text: str, action: str, **kwargs) → None[source]#

Add a form button to the sidebar.

This method simplifies the addition of form buttons to the sidebar with appropriate styling and behavior.

Parameters:

text – The text to display on the button
action – The form action URL that the button should submit to
**kwargs – Additional keyword arguments for customization

add_sidebar_link_button(text: str, url: str, **kwargs) → None[source]#

Add a link button to the sidebar.

This method simplifies the addition of link buttons to the sidebar with appropriate styling and behavior.

Parameters:

text – The text to display on the button
url – The URL that the button should link to
**kwargs – Additional keyword arguments for customization

add_sidebar_widget(widget: Widget) → None[source]#

Add a widget to the sidebar.

This method adds the widget to the Actions area of the sidebar, typically used for secondary actions or information.

Parameters:: widget – The widget to add to the sidebar

add_widget(widget: Widget, title: str | None = None, icon: str | None = None) → None[source]#

Add a widget to the layout.

This method adds the widget to both the sidebar index and the main content area.

Parameters:

widget – The widget to add
title – Optional title for the widget
icon – Optional icon for the widget

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

Get context data for template rendering.

Provides the layout with the necessary context variables for rendering the title, sidebar, main content, and any modals.

Parameters:

*args – Positional arguments passed to parent
**kwargs – Additional context variables

Returns:

Updated context dictionary with layout components

Return type:

dict

sidebar_breakpoint: str = 'xl'#: The breakpoint at which the sidebar will collapse to a hamburger menu.

sidebar_title: str = 'Actions'#: The title of the sidebar column.

sidebar_width: int = 3#: The width of the sidebar column in Bootstrap grid columns.

template_name: str = 'wildewidgets/widget-list.html'#: The Django template to render this layout.

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

Bases: Block

The main content area in a widget list layout.

This widget represents the primary content area where widgets are displayed in a vertical stack. It’s typically used in conjunction with a sidebar widget to create a comprehensive layout.

Note

This is not something that you would use directly. WidgetListLayout uses this internally when you add widgets to the main area.

template_name#

Path to the template used to render the main widget list

Type:: str

block#

CSS block name for styling

Type:: str

css_class#

CSS class for the main content area

Type:: str

entry_css_class#

CSS class for individual widget entries

Type:: str | None

entry_title_css_class#

CSS class for widget entry titles

Type:: str | None

entries#

Default list of widget index items for the main content

Type:: list[wildewidgets.widgets.base.Widget]

Parameters:: *args – Positional arguments passed to parent
Keyword Arguments:: **kwargs – Keyword arguments which may include ‘entries’ to initialize the list with a list of WidgetIndexItem objects

add_widget(widget: Widget, title: str | wildewidgets.widgets.base.Widget | None = None) → None[source]#

Add a widget to the main content area.

This method also ensures that the widget has an associated title, either from the widget itself or as a provided argument.

Parameters:

widget – The widget to add to the main content area
title – Optional title for the widget. If provided, it will be set as the widget’s title attribute

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

Get context data for template rendering.

Provides the list of entries to be rendered in the main widget area.

Parameters:

*args – Positional arguments passed to parent
**kwargs – Additional context variables

Returns:

Updated context dictionary with entries and CSS classes

Return type:

dict

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

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

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

class WidgetListSidebarWidget(*args, title: str | None = None, width: int = 3, breakpoint: str = 'xl', bare_widgets: list[wildewidgets.widgets.base.Widget] | None = None, actions: list[wildewidgets.widgets.base.Widget] | None = None, **kwargs)[source]#

Bases: Block

A sidebar component for widget list layouts.

This widget creates a sidebar that can contain actions (typically buttons) and other widgets. It’s commonly used as part of a WidgetListLayout to provide navigation and action controls.

Note

This is not something that you would use directly. WidgetListLayout uses this internally when you add widgets to the sidebar area.

template_name#

Path to the template used to render the sidebar

Type:: str

block#

CSS block name for styling

Type:: str

css_class#

CSS classes to apply to the sidebar

Type:: str

actions#

Default list of action widgets to display

Type:: list[wildewidgets.widgets.base.Widget]

bare_widgets#

Default list of widgets to display without special styling

Type:: list[wildewidgets.widgets.base.Widget]

Parameters:

*args – Positional arguments passed to parent

Keyword Arguments:

title – Optional title for the sidebar
width – Column width for the sidebar, defaults to 3
breakpoint – Bootstrap breakpoint for responsive design
bare_widgets – Optional list of widgets to display without special styling
actions – Optional list of action widgets to display
**kwargs – Additional keyword arguments passed to parent

class Actions(widgets: list[wildewidgets.widgets.base.Widget] | None = None, **kwargs: Any)[source]#

Bases: WidgetStream

css_class: str = 'px-3 py-4 d-flex flex-column align-items-stretch border bg-white shadow-sm'#: A string of CSS classes to apply to this block

class Widgets(widgets: list[wildewidgets.widgets.base.Widget] | None = None, **kwargs: Any)[source]#

Bases: WidgetStream

block: str = 'widget-list__sidebar__widgets'#: The CSS block name for this widget stream

add_actions_widget(widget: Widget) → None[source]#: Add a widget to the sidebar inside the Actions box.

add_form_button(text: str, action: str, **kwargs) → None[source]#

Add wildewidgets.FormButton to the sidebar.

Parameters:

text – The text to display on the button.
action – The action to perform when the button is clicked.

Keyword Arguments:

**kwargs – any additional keyword arguments appropriate for wildewidgets.FormButton

add_link_button(text: str, url: str, **kwargs) → None[source]#

Add wildewidgets.LinkButton to the sidebar.

Parameters:

text – The text to display on the button.
url – The URL to link to.

Keyword Arguments:

**kwargs – any additional keyword arguments appropriate for wildewidgets.FormButton

add_widget(widget: Widget) → None[source]#: Add a widget to the sidebar outside the Actions box.

add_widget_to_index(widget: Widget, title: str | None = None, icon: str | None = None) → None[source]#

Add widget the index with title title and icon icon.

If title is None, look for a title on widget.title. If that is also None, default to the name of the widget class.

If icon is None, look for an icon on widget.icon. If that is also None, default to the Bootstrap Icons “gear” icon.

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

Update the template context dictionary used when rendering this block.

Parameters:: *args – positional arguments (ignored)
Keyword Arguments:: **kwargs – the current context dictionary
Returns:: The updated context dictionary

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

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

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