Skip to content

ColumnWidget API

ColumnWidget(widget_id=None)

Bases: BaseWidget

Create a multi-column layout container for horizontally arranging multiple widgets.

This widget uses <table> elements to ensure maximum compatibility across various email clients. You can place any other widgets (such as TextWidget, CardWidget, ChartWidget, etc.) in the column layout to create complex and beautiful email layouts.

Core features
  • Auto columns: By default, it intelligently calculates the optimal number of columns based on the number of internal widgets.
  • Manual columns: You can also manually specify a fixed number of columns between 1 and 4.
  • Responsive: Layout automatically adjusts based on screen width, ensuring good experience on both desktop and mobile devices.
  • Spacing control: Can customize horizontal spacing between columns.
Auto column rules
  • 1 widget: 1 column
  • 2 widgets: 2 columns
  • 3 widgets: 3 columns
  • 4 widgets: 2 columns (2x2 grid)
  • 5-6 widgets: 3 columns
  • 7-8 widgets: 2 columns
  • 9+ widgets: 3 columns

Examples:

Create a two-column layout with a card on the left and chart on the right:

Python
from email_widget.widgets import ColumnWidget, CardWidget, ChartWidget
import matplotlib.pyplot as plt

# Prepare left card
left_card = (CardWidget()
             .set_title("Key Metrics")
             .add_metadata("User Growth", "+15%")
             .add_metadata("Revenue", "+12%"))

# Prepare right chart
plt.figure()
plt.plot([1, 2, 3], [4, 5, 2])
right_chart = ChartWidget().set_chart(plt)

# Create 2-column layout and add widgets
two_column_layout = (ColumnWidget()
                     .set_columns(2)
                     .set_gap("24px")
                     .add_widget(left_card)
                     .add_widget(right_chart))

# Assuming email is an Email object
# email.add_widget(two_column_layout)

Initialize ColumnWidget.

Parameters:

Name Type Description Default
widget_id Optional[str]

Optional Widget ID.

 None

Functions

add_widget(widget)

Add a widget to the column layout.

Parameters:

Name Type Description Default
widget BaseWidget

Widget instance to add.

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> column = ColumnWidget().add_widget(TextWidget().set_content("Left content"))
add_widgets(widgets)

Add multiple widgets to the column layout.

Parameters:

Name Type Description Default
widgets List[BaseWidget]

List of widget instances to add.

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> column = ColumnWidget().add_widgets([TextWidget(), ImageWidget()])
clear_widgets()

Clear all widgets in the column layout.

Returns:

Name Type Description
ColumnWidget ColumnWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> column = ColumnWidget().clear_widgets()
get_current_columns()

Get the current number of columns actually used.

If in auto mode, returns the number of columns calculated based on widget count; otherwise returns the manually set number of columns.

Returns:

Name Type Description
int int

Number of columns actually used.

Examples:

Python Console Session
>>> column = ColumnWidget().add_widgets([TextWidget(), TextWidget()])
>>> column.get_current_columns() # In auto mode, 2 widgets return 2 columns
get_effective_columns()

Get the actual effective number of columns.

If set to auto mode, calculates based on current widget count; otherwise returns manually set number of columns.

Returns:

Name Type Description
int int

Number of columns actually used.
get_template_context()

Get template context data required for rendering

get_widget_count()

Get the number of widgets in the column layout.

Returns:

Name Type Description
int int

Number of widgets.

Examples:

Python Console Session
>>> count = ColumnWidget().add_widget(TextWidget()).get_widget_count()
>>> print(count) # Output: 1
is_auto_mode()

Check if currently in auto column mode.

Returns:

Name Type Description
bool bool

True if in auto mode, False otherwise.

Examples:

Python Console Session
>>> column = ColumnWidget().is_auto_mode() # Default is True
remove_widget(widget_id)

Remove specified widget by widget ID.

Parameters:

Name Type Description Default
widget_id str

ID of the widget to remove.

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> column = ColumnWidget().remove_widget("my_text_widget")
remove_widget_by_index(index)

Remove widget at specified index.

Parameters:

Name Type Description Default
index int

Index of the widget to remove.

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

Returns self to support method chaining.

Raises:

Type Description
IndexError

If index is out of range.

Examples:

Python Console Session
>>> column = ColumnWidget().remove_widget_by_index(0) # Remove first widget
set_columns(columns)

Set the number of columns in the layout.

Parameters:

Name Type Description Default
columns int

Number of columns. -1 indicates auto mode, other values are limited between 1 and 4 columns.

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> column = ColumnWidget().set_columns(2) # Set to 2 columns
>>> column = ColumnWidget().set_columns(-1) # Auto mode
set_equal_width(equal=True)

Set whether columns have equal width.

Parameters:

Name Type Description Default
equal bool

Whether equal width, defaults to True.

 True

Returns:

Name Type Description
ColumnWidget ColumnWidget

Returns self to support method chaining.
Note

This method is currently only a reserved interface, column widths are always equally divided in actual rendering.

Examples:

Python Console Session
>>> column = ColumnWidget().set_equal_width(False)
set_gap(gap)

Set horizontal spacing between columns.

Parameters:

Name Type Description Default
gap str

CSS spacing value, such as "20px", "1em".

 required

Returns:

Name Type Description
ColumnWidget ColumnWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> column = ColumnWidget().set_gap("16px")