Base Widgets#

Bases: TemplateWidget

Render a single HTML element.

All the constructor parameters can be set in a subclass of this class as class attributes. Parameters to the constructor override any defined class attributes.

Example

from wildewidgets import Block

block = Block(
    'Hello World',
    tag='a',
    name='foo',
    modifier='bar',
    css_class='blah dah',
    attributes={'href': 'https://example.com'}
)

When rendered in the template with the wildewidgets template tag, this will produce:

<a href="https://example.com" class="foo foo--bar blah dah">Hello World</a>

Parameters:

*blocks – any content to be rendered in the block, either other blocks, or plain strings, or a mix of both. If this is not specified, the contents attribute will be used instead. If you specify this, it will override contents.

Keyword Arguments:

tag – the name of the HTML element to use as our tag, e.g. div
name – This CSS class will be added to the classes to identify this block
modifier – If specified, also add a class named {name}--{modifier} to the CSS classes
css_class – a string of CSS classes to apply to the block
css_id – Use this as the id attribute for the block
attributes – Set any additional attributes for the block
data_attributes – Set data-bs- attributes for the block
aria_attributes – Set aria- attributes for the block
empty – if True, this element uses no close tag
script – Javascript to attach to this block

Raises:

ValueError – empty is True, but contents were added to this block

exception RequiredAttrOrKwarg(name: str)[source]#: Bases: ValueError

add_block(block: str | wildewidgets.widgets.base.Widget | wildewidgets.widgets.base.Block) → None[source]#

Add a block to our content. This will appear inside the tag for this block.

Parameters:: block – the block to add to our content

add_blocks() → None[source]#: Add each block in contents to our blocks list.

Note

This is here so it can be overridden.

add_class(css_class: str) → None[source]#

Add a CSS class to our _css_class attribute. This is a convenience method to allow us to add a class withouth having to do string manipulation.

Note

If you need to change name or modifier, set them directly instead of using this.

Parameters:: css_class – The CSS to add

get_context_data(*args: Any, **kwargs: Any) → 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

get_script() → str | None[source]#

Return any javascript to attach to this block.

Note

The Javascript will will appear in the HTML directly after the block appears. Do not surround this with a <script> tag; that will be done for you.

Returns:: The fully rendered Javascript for this block, if any.

remove_class(css_class: str) → None[source]#

Remove a CSS class from our _css_class attribute. This is a convenience method to allow us to remove a class withouth having to do string manipulation.

Note

This method can only remove things from _css_class. You can’t remove name, modifier or block with this method, since those are supposed to be purely informational.

Parameters:: css_class – The CSS to remove

aria_attributes: ClassVar[dict[str, str]] = {}#: Additional aria- attributes to set on this block

attributes: ClassVar[dict[str, str]] = {}#: Additional HTML attributes to set on this block

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

blocks: list[str | wildewidgets.widgets.base.Widget]#: The internal list of blocks that are this block’s content

contents: list[str | wildewidgets.widgets.base.Widget] = []#: A list of strings or Blocks that will be the content for this block

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

property css_classes: list[str]#

Return a list of our CSS classes.

Note

This excludes the set name, block and modifier classes. Read those directly from their attributes instead.

Returns:: The list of the CSS classes for this block, excluding the block, name and modifier classes.

css_id: str | None = None#: The CSS id for this block

data_attributes: ClassVar[dict[str, str]] = {}#: Additional data-bs- attributes to set on this block

empty: bool = False#: If True, this block uses no close tag

modifier: str | None = None#: If specified, also add a class named {name}--{modifier} to the CSS classes

name: str | None = None#: The CSS class that will be added to this element to as an identifier for this kind of block

script: str | None = None#: The Javascript to apply to this block. It will appear in the HTML directly after the block appears. Do not surround this with a <script> tag; that will be done for you.

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

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

class Container(*blocks: str | wildewidgets.widgets.base.Widget, size: str | None = None, **kwargs: Any)[source]#

Bases: Block

A Bootstrap container

Example

from wildewidgets import Container

c = Container(size='lg')

Keyword Arguments:: size – The max viewport size for the container, in bootstrap sizes, or fluid.
Raises:: ValueError – size was not one of the valid sizes

VALID_SIZES: Final[list[Literal['sm', 'md', 'lg', 'xl', 'xxl', 'fluid']]] = ['sm', 'md', 'lg', 'xl', 'xxl', 'fluid']#: The valid sizes for the Tabler container. These are the bootstrap sizes sm, md, lg, xl, xxl and fluid.

size: str | None = None#: The max viewport size for the container, in bootstrap sizes, or fluid.

class HTMLList(*args: Any, items: list[str] | None = None, **kwargs: Any)[source]#

Bases: UnorderedList

An unordered HTML list.

Deprecated since version 0.14.0: Use UnorderedList instead. Change this:

from wildewidgets import HTMLList, Link

items = ['foo', 'bar', 'baz', Link['barney', url='https://example.com]]
block = HTMLList(items=items)

To this:

from wildewidgets import UnorderedList, Link

items = ['foo', 'bar', 'baz', Link['barney', url='https://example.com]]
block = UnorderedList(*items)

class Image(src: str | None = None, height: str | None = None, width: str | None = None, alt: str | None = None, **kwargs: Any)[source]#

Bases: Block

An <img>:

<img src="image.png" alt="My Image" width="100%">

Example

from wildewidgets import Image
from django.templatetags.static import static

block = Image(src=static('myapp/images/img.png'), alt='The Image')

Keyword Arguments:

src – the URL of the image. Typically this will be something like static('myapp/images/image.png') The default is to use a placeholder image to remind you that you need to fix this.
height – the value of the height attribute for the <img>
width – the value of the width attribute for the <img>
alt – the value of the alt tag for the <img>. If this is not set either here or as a class attribute, we’ll raise ValueError to enforce WCAG 2.0 compliance.

Raises:

ValueError – no alt was provided

alt: str | None = None#: The value of the alt tag for the <img>. If this is not set either here or in our contructor kwargs, we’ll raise ValueError (to enforce ADA)

block: str = 'image'#: The CSS block name for this widget. This is used to identify the widget in the template and to apply CSS styles.

height: str | None = None#: the value of the height attribute for the <img>

src: str | None = None#: image to remind you that you need to fix this.

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

width: str | None = None#: the value of the width attribute for the <img>

Bases: Block

A simple <a> tag. We made it into its own block because we need <a> tags so often.

Example

from wildewidgets import Link

link = Link('click here', url='https://example.com')

Keyword Arguments:

contents – The contents of the <a>. This can be string, a Block, or an iterable of strings and Block objects.
url – The URL of the <a>
title – The value of the title tag for the link
role – The value of the role attribute for the link
target – The target for this link, aka the context in which the linked resource will open.

contents: str | wildewidgets.widgets.base.Block | collections.abc.Iterable[str | wildewidgets.widgets.base.Block] | None = None#: The contents of the <a>. This can be string, a Block, or an iterable of strings and Block objects.

role: str = 'link'#: The value of the role attribute for the link

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

target: str | None = None#: The target for this link, aka the context in which the linked resource will open.

title: str | None = None#: The value of the title attribute for the link

url: str = '#'#: The URL of the <a>

class LinkedImage(image_src: str | None = None, image_width: str | None = None, image_alt: str | None = None, **kwargs: Any)[source]#

Bases: Link

An <img> wrapped in an <a>:

<a href="#">
    <img src="image.png" alt="My Image" width="100%">
</a>

Note

If you want to modify the encapsulated image (to add css classes, for example), you can do so by modifying the attributes on image after constructing the LinkedImage:

from wildewidgets import LinkedImage
from django.templatetags.static import static

block = LinkedImage(
    image_src='image.png',
    image_alt='My Image',
    url='http://example.com'
)
block.image.add_class('my-extra-class')
block.image._css_id = 'the-image'

Keyword Arguments:

image_src – the URL of the image. Typically this will be something like static('myapp/images/image.png')
image_width – the value of the width attribute for the <img>
image_alt – the value of the alt tag for the <img>. If this is not set either here or as a class attribute, we’ll raise ValueError to enforce WCAG 2.0 compliance.

Raises:

ValueError – no alt was provided

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

image: Image#: The actual image block that we will wrap with an <a>

image_alt: str | None = None#: The value of the alt tag for the <img>. If this is not set either here or in our contructor kwargs, we’ll raise ValueError to enforce WCAG 2.0 compliance.

image_src: str | None = None#: The URL of the image. Typically this will be something like static('myapp/images/image.png')

image_width: str | None = None#: the value of the width attribute for the <img>.

Bases: UnorderedList

An HTML ordered list, aka a <ol> tag.

This wraps each item in contents with <li>.

Example

With constructor arguments:

… code-block:: python

from wildewidgets import OrderedList, Link

items = [‘foo’, ‘bar’, ‘baz’, Link[‘barney’, url=’https://example.com]] ul = OrderedList(*items)

With add_block:

from wildewidgets import OrderedList, Link

items = ['foo', 'bar', 'baz', Link['barney', url='https://example.com]]
ul = OrderedList()
for item in items:
    ul.add_block(item)

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

class TemplateWidget(*args: Any, title: str | wildewidgets.widgets.base.Widget | None = None, icon: str | None = None, **kwargs: Any)[source]#

Bases: Widget

A widget that renders content using a Django template.

This class extends Widget to provide template-based rendering capabilities. Subclasses should define a template_name that points to a valid Django template.

template_name#

Path to the Django template to use for rendering.

Type:: str | None

get_content(**kwargs: Any) → str[source]#

Render the widget using its template.

This method retrieves the appropriate template, populates the context with data from get_context_data(), and renders the template to a string.

Parameters:: **kwargs – Additional context data to include in the template.
Returns:: String containing the rendered HTML content.

get_template() → str[source]#

Return the name to the Django template we want to use to render this TemplateWidget.

Returns:: The name of the template to use to render us.
Raises:: ImproperlyConfigured – no template name was provided.

Bases: Block

An HTML unordered list, aka a <ul> tag.

This wraps each item in contents with <li>.

Example

With constructor arguments:

from wildewidgets import UnorderedList, Link

items = ['foo', 'bar', 'baz', Link['barney', url='https://example.com]]
ul = UnorderedList(*items)

With add_block:

from wildewidgets import UnorderedList, Link

items = ['foo', 'bar', 'baz', Link['barney', url='https://example.com]]
ul = UnorderedList()
for item in items:
    ul.add_block(item)

add_block(block: str | wildewidgets.widgets.base.Block, **kwargs: Any) → None[source]#

Wrap block in an <li> Block append it to blocks, using **kwargs as the keyword arguments for Block.

If block is already an <li>, just append it to blocks.

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

class Widget(*args: Any, title: str | wildewidgets.widgets.base.Widget | None = None, icon: str | None = None, **kwargs: Any)[source]#

Bases: object

The base class from which all widgets should inherit.

This class provides the foundation for all wildewidgets components. It defines the basic interface that all widgets must implement and provides common functionality.

title#

An optional title for the widget that can be displayed in UI elements.

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

icon#

A default icon identifier used for rendering widget-related icons.

Type:: str

get_content() → Any[source]#

Get the rendered content of this widget.

This method must be implemented by subclasses to produce the actual rendered content of the widget.

Raises:: NotImplementedError – This method must be implemented by subclasses.
Returns:: The rendered content (typically HTML).

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

Get the base context data for rendering the widget.

Parameters:: **kwargs – Context data to include.
Returns:: Dictionary of context data for template rendering.

get_title() → str | wildewidgets.widgets.base.Widget | None[source]#

Retrieve the widget’s title.

Returns:: The widget’s title string, widget object, or None if no title is set.

is_visible() → bool[source]#

Determine if this widget should be visible.

Can be overridden by subclasses to conditionally show/hide widgets.

Returns:: Boolean indicating whether this widget should be visible. Default is True.

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

Bases: Block

A widget that renders a stream of other widgets in sequence.

This widget allows you to place multiple widgets in a container and render them sequentially. It’s useful for creating widget dashboards or collections where multiple components need to be displayed in order.

Example

from wildewidgets import WidgetStream, Link, Image

stream = WidgetStream(
    widgets=[
        Link('Click here', url='https://example.com'),
        Image(src='https://example.com/image.png', alt='An image')
    ]
)

Note

The widgets in the stream are wrapped in a Block with the appropriate CSS class before being added to the stream. This allows for consistent styling and layout.

add_widget(widget: Widget, **kwargs: Any) → None[source]#

Add a widget to the stream.

The widget is wrapped in a Block with the appropriate CSS class before being added to the stream.

Parameters:

widget – The widget to add to the stream
**kwargs – Additional keyword arguments to pass to the Block constructor

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

Get the context data for rendering the template.

Adds the widgets list to the context data.

Parameters:

*args – Variable length argument list
**kwargs – Arbitrary keyword arguments

Returns:

Dictionary containing the context data for template rendering

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

property is_empty: bool#

Check if the widget stream contains any widgets.

Returns:: True if the widget stream is empty, False otherwise

template_name: str = 'wildewidgets/widget_stream.html'#: The name of the template to use to render this widget stream

widgets: list[wildewidgets.widgets.base.Widget] = []#: Default list of widgets to include in the stream