Base Widgets#

class Block(*blocks, tag: Optional[str] = None, name: Optional[str] = None, modifier: Optional[str] = None, css_class: Optional[str] = None, css_id: Optional[str] = None, empty: Optional[bool] = None, script: Optional[str] = None, attributes: Optional[Dict[str, str]] = None, data_attributes: Optional[Dict[str, str]] = None, aria_attributes: Optional[Dict[str, str]] = None)[source]#

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

>>> 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 wildewdigets 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, including other blocks, or plain strings

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: Union[str, Widget]) → 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, **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

get_script() → Optional[str][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: Dict[str, str] = {}#: Additional aria- attributes to set on this block

attributes: 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[Union[str, Widget]]#: The internal list of blocks that are this block’s content

contents: List[Union[str, 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: Optional[str] = None#: The CSS id for this block

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

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

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

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

script: Optional[str] = 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 widget

class Container(*blocks, size: Optional[str] = None, **kwargs)[source]#

Bases: Block

A Bootstrap container

Example:

>>> 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

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

class HTMLList(*args, items: Optional[List[str]] = None, **kwargs)[source]#

Bases: UnorderedList

An unordered HTML list.

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

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

To this:

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

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

Bases: Block

An <img>:

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

Example

>>> 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: Optional[str] = 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'#: block is the official wildewidgets name of the block; it can’t be changed by constructor kwargs

height: Optional[str] = None#: the value of the height attribute for the <img>

src: Optional[str] = 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. div

width: Optional[str] = None#: the value of the width attribute for the <img>

class Link(*contents: Union[str, Block], url: Optional[str] = None, role: Optional[str] = None, title: Optional[str] = None, target: Optional[str] = None, **kwargs)[source]#

Bases: Block

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

Example:

>>> 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: Union[str, Block, Iterable[Union[str, Block]]] = 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. div

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

title: Optional[str] = None#: The value of the title attribute for the link

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

class LinkedImage(image_src: Optional[str] = None, image_width: Optional[str] = None, image_alt: Optional[str] = None, **kwargs)[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:

>>> 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: Optional[str] = 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: Optional[str] = None#: The URL of the image. Typically this will be something like static('myapp/images/image.png')

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

class OrderedList(*blocks, tag: Optional[str] = None, name: Optional[str] = None, modifier: Optional[str] = None, css_class: Optional[str] = None, css_id: Optional[str] = None, empty: Optional[bool] = None, script: Optional[str] = None, attributes: Optional[Dict[str, str]] = None, data_attributes: Optional[Dict[str, str]] = None, aria_attributes: Optional[Dict[str, str]] = None)[source]#

Bases: UnorderedList

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

This wraps each item in contents with <li>.

Example

With constructor arguments:

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

With add_block:

>>> 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. div

class TemplateWidget(*args, title: Optional[Union[str, Widget]] = None, icon: Optional[str] = None, **kwargs)[source]#

Bases: Widget

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

Actually render us to a string. This is the method that the wildewidgets template tag will call (via wildewidgets.templatetags.wildewidgets.WildewidgetsNode.render) to render the widget into a containing template.

Returns:: Our rendered HTML.

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.

template_name: Optional[str] = None#: The name of the template to use to render this widget

class UnorderedList(*blocks, tag: Optional[str] = None, name: Optional[str] = None, modifier: Optional[str] = None, css_class: Optional[str] = None, css_id: Optional[str] = None, empty: Optional[bool] = None, script: Optional[str] = None, attributes: Optional[Dict[str, str]] = None, data_attributes: Optional[Dict[str, str]] = None, aria_attributes: Optional[Dict[str, str]] = None)[source]#

Bases: Block

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

This wraps each item in contents with <li>.

Example

With constructor arguments:

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

With add_block:

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

add_block(block: Union[str, Block], **kwargs) → None[source]#

Wrap block in an <li> wildewidgets.widgets.base.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. div

class Widget(*args, title: Optional[Union[str, Widget]] = None, icon: Optional[str] = None, **kwargs)[source]#

Bases: object

The base class from which all widgets should inherit.

class WidgetStream(widgets: Optional[List[Widget]] = None, **kwargs)[source]#

Bases: Block

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

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

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