CardWidget API

CardWidget(widget_id=None)

Bases: BaseWidget

Create a content card for displaying information in a structured way.

Cards are ideal for organizing and presenting information, commonly used for displaying data summaries, status updates, profiles, etc. They support titles, main content, icons, and one or more metadata entries.

Attributes:

Name	Type	Description
title	Optional[str]	The card's title.
content	str	The card's main content text.
icon	Optional[str]	Icon displayed before the title, can be Emoji or other characters.
metadata	Dict[str, str]	A key-value dictionary for displaying additional information at the bottom of the card.

Examples:

Create a card for displaying service status:

Python

from email_widget.widgets import CardWidget

card = CardWidget()
card.set_title("API Service Monitoring")
card.set_content("All services running normally, average response time 50ms.")
card.set_icon("✅")
card.add_metadata("Last Check Time", "2024-07-07 10:30:00")
card.add_metadata("Uptime", "99.99%")

# Using method chaining for more compact code:
server_status_card = (CardWidget()                              .set_title("Database Server")                              .set_content("Connection normal, disk space sufficient.")                              .set_icon("🗄️")                              .set_metadata({
                          "CPU Usage": "15%",
                          "Memory Usage": "2.5 GB / 16 GB"
                      }))

Initialize CardWidget.

Parameters:

Name	Type	Description	Default
widget_id	Optional[str]	Optional Widget ID.	None

Functions

add_metadata(key, value)

Add a metadata entry to the card.

Metadata is displayed at the bottom of the card in key-value pairs.

Parameters:

Name	Type	Description	Default
key	str	The metadata item's key (name).	required
value	str	The metadata item's value.	required

Returns:

Name	Type	Description
CardWidget	CardWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> card = CardWidget().add_metadata("Version", "1.0.0")

clear_metadata()

Clear all metadata from the card.

Returns:

Name	Type	Description
CardWidget	CardWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> card = CardWidget().clear_metadata()

get_template_context()

Get template context data required for rendering

set_content(content)

Set the card's main content text.

Parameters:

Name	Type	Description	Default
content	str	Card content text.	required

Returns:

Name	Type	Description
CardWidget	CardWidget	Returns self to support method chaining.

Raises:

Type	Description
ValueError	When content is empty.

Examples:

Python Console Session

>>> card = CardWidget().set_content("All services running normally.")

set_icon(icon)

Set the icon displayed before the title.

The icon can be any string (such as Emoji characters) or IconType enumeration value.

Parameters:

Name	Type	Description	Default
icon	Union[str, IconType]	Icon string or IconType enumeration.	required

Returns:

Name	Type	Description
CardWidget	CardWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> card = CardWidget().set_icon("✅")
>>> card = CardWidget().set_icon(IconType.DATA)

set_metadata(metadata)

Set all metadata for the card.

This method will replace all existing metadata.

Parameters:

Name	Type	Description	Default
metadata	Dict[str, str]	Dictionary containing all metadata items.	required

Returns:

Name	Type	Description
CardWidget	CardWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> card = CardWidget().set_metadata({"CPU": "15%", "Memory": "60%"})

set_status(status)

Set the card's status.

This status is typically used for internal logic or future visual indicators, currently does not directly affect card appearance.

Parameters:

Name	Type	Description	Default
status	StatusType	The card's status type.	required

Returns:

Name	Type	Description
CardWidget	CardWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> card = CardWidget().set_status(StatusType.SUCCESS)

set_title(title)

Set the card's title.

Parameters:

Name	Type	Description	Default
title	str	Card title text.	required

Returns:

Name	Type	Description
CardWidget	CardWidget	Returns self to support method chaining.

Raises:

Type	Description
ValueError	When title is empty.

Examples:

Python Console Session

>>> card = CardWidget().set_title("System Status")