TableBlock¶
The TableBlock module provides an HTML table block type for StreamField. This module uses handsontable 6.2.2 to provide users with the ability to create and edit HTML tables in Wagtail. Table blocks provides a caption field for accessibility.
Installation¶
Add "wagtail.contrib.table_block"
to your INSTALLED_APPS:
INSTALLED_APPS = [
...
"wagtail.contrib.table_block",
]
Basic Usage¶
After installation, the TableBlock module can be used in a similar fashion to other StreamField blocks in the Wagtail core.
Import the TableBlock from wagtail.contrib.table_block.blocks import TableBlock
and add it to your StreamField declaration.
class DemoStreamBlock(StreamBlock):
...
table = TableBlock()
Then, on your page template, the {% include_block %}
tag (called on either the individual block, or the StreamField value as a whole) will render any table blocks it encounters as an HTML <table>
element:
{% load wagtailcore_tags %}
{% include_block page.body %}
Or:
{% load wagtailcore_tags %}
{% for block in page.body %}
{% if block.block_type == 'table' %}
{% include_block block %}
{% else %}
{# rendering for other block types #}
{% endif %}
{% endfor %}
Advanced Usage¶
Default Configuration¶
When defining a TableBlock, Wagtail provides the ability to pass an optional table_options
dictionary. The default TableBlock dictionary looks like this:
default_table_options = {
'minSpareRows': 0,
'startRows': 3,
'startCols': 3,
'colHeaders': False,
'rowHeaders': False,
'contextMenu': [
'row_above',
'row_below',
'---------',
'col_left',
'col_right',
'---------',
'remove_row',
'remove_col',
'---------',
'undo',
'redo'
],
'editor': 'text',
'stretchH': 'all',
'height': 108,
'language': language,
'renderer': 'text',
'autoColumnSize': False,
}
Configuration Options¶
Every key in the table_options
dictionary maps to a handsontable option. These settings can be changed to alter the behaviour of tables in Wagtail. The following options are available:
minSpareRows - The number of rows to append to the end of an empty grid. The default setting is 0.
startRows - The default number of rows for a new table.
startCols - The default number of columns for new tables.
colHeaders - Can be set to
True
orFalse
. This setting designates if new tables should be created with column headers. Note: this only sets the behaviour for newly created tables. Page editors can override this by checking the “Column header” checkbox in the table editor in the Wagtail admin.rowHeaders - Operates the same as
colHeaders
to designate if new tables should be created with the first column as a row header. Just likecolHeaders
this option can be overridden by the page editor in the Wagtail admin.contextMenu - Enables or disables the Handsontable right-click menu. By default this is set to
True
. Alternatively you can provide a list or a dictionary with specific options.editor - Defines the editor used for table cells. The default setting is text.
stretchH - Sets the default horizontal resizing of tables. Options include, ‘none’, ‘last’, and ‘all’. By default TableBlock uses ‘all’ for the even resizing of columns.
height - The default height of the grid. By default TableBlock sets the height to
108
for the optimal appearance of new tables in the editor. This is optimised for tables withstartRows
set to3
. If you change the number ofstartRows
in the configuration, you might need to change theheight
setting to improve the default appearance in the editor.language - The default language setting. By default TableBlock tries to get the language from
django.utils.translation.get_language
. If needed, this setting can be overridden here.renderer - The default setting Handsontable uses to render the content of table cells.
autoColumnSize - Enables or disables the
autoColumnSize
plugin. The TableBlock default setting isFalse
.mergeCells - Can be set to
True
orFalse
, determined if merging cells is allowed. Remember to add'mergeCells'
to the'contextMenu'
option also.
A complete list of handsontable options can be found on the Handsontable website.
Changing the default table_options¶
To change the default table options just pass a new table_options dictionary when a new TableBlock is declared.
new_table_options = {
'minSpareRows': 0,
'startRows': 6,
'startCols': 4,
'colHeaders': False,
'rowHeaders': False,
'contextMenu': True,
'editor': 'text',
'stretchH': 'all',
'height': 216,
'language': 'en',
'renderer': 'text',
'autoColumnSize': False,
}
class DemoStreamBlock(StreamBlock):
...
table = TableBlock(table_options=new_table_options)
Supporting cell alignment¶
You can activate the alignment
option by setting a custom contextMenu
which allows you to set the alignment on a cell selection.
HTML classes set by handsontable will be kept on the rendered block. You’ll then be able to apply your own custom CSS rules to preserve the style. Those class names are:
Horizontal:
htLeft
,htCenter
,htRight
,htJustify
Vertical:
htTop
,htMiddle
,htBottom
new_table_options = {
'contextMenu': [
'row_above',
'row_below',
'---------',
'col_left',
'col_right',
'---------',
'remove_row',
'remove_col',
'---------',
'undo',
'redo',
'---------',
'copy',
'cut'
'---------',
'alignment',
],
}
class DemoStreamBlock(StreamBlock):
...
table = TableBlock(table_options=new_table_options)