2022/02/27

WagtailでTableBlockを利用する方法

Wagtailで表形式の図表を挿入する方法を紹介します。

Table要素とは、表をグリッドの形で表示するもので、なにかを比較したり分類したりしてわかりやすく読者に内容を伝える場合に便利な表現方法の一つです。

Wagtailでも簡単にTable要素を導入することができます。今回はWagtailの管理画面からTable要素を編集できるようにするための実装を紹介します。

WagtailではTableBlockを利用することで、HTMLのtable要素をStreamField上から挿入することができます。管理画面上に表の要素が表示されたまま直感的に管理できるため、とても便利です。

TableBlockを導入する

まずはINSTALLED_APPSにwagtail.contrib.table_blockを追加します。

# settings/base.py

INSTALLED_APPS = [
    ...
    "wagtail.contrib.table_block", # 追加
]

あとは通常のStreamFieldへのブロックの追加と同じように実装することができます。

以下の例では、記事ページ（ArticlePage）のコンテンツ部分をStreamFieldとして実装し、RichTextのブロックとTable要素のブロックを選択できるようにしています。

# models.py

from wagtail.admin.edit_handlers import StreamFieldPanel
from wagtail.contrib.table_block.blocks import TableBlock # 追加
from wagtail.core.fields import StreamField
from wagtail.core.models import Page


class ArticlePage(Page):
    ...
    content = StreamField(
        [
            ("richtext", blocks.RichTextBlock()),
            ("table", TableBlock()), # 追加
        ],
        null=True,
        blank=True,
    )

    content_panels = Page.content_panels + [
        ...
        StreamFieldPanel("content"),
    ]

ここまでの実装で、管理画面のコンテンツの編集ページからTableブロックを選択できるようになりました。

デフォルトでは以下のような表形式になっています。試しにデータを入力してみましょう。

Row headerとColumn headerはそれぞれ、最初の行と列をヘッダーとして扱うかどうかのチェックマークになります。Table captionはこの表のキャプション（見出し）です。

表の上で右クリックすることで、表に行と列を挿入したり、削除したりすることができます。

テンプレート上ではStreamFieldが自動的にTableBlockを判別して、HTMLのtable要素として必要なタグを生成してくれます。上のサンプルだと、以下のようなHTMLがテンプレートに挿入されます。

<div class="block-table">
  <table>
    <caption>期末テストの点数</caption>
    <thead>
      <tr>
        <th scope="col"></th>
        <th scope="col">太郎</th>
        <th scope="col">花子</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row">国語</th>
        <td>80</td>
        <td>90</td>
      </tr>
      <tr>
        <th scope="row">数学</th>
        <td>30</td>
        <td>65</td>
      </tr>
      <tr>
        <th scope="row">英語</th>
        <td>95</td>
        <td>60</td>
      </tr>
    </tbody>
  </table>
</div>

Tableのカスタマイズ

Wagtailでは、Tableを挿入する際のオプションをカスタマイズすることもできます。TableBlock()はtable_optionsというパラメータを取ることができ、その中でTableのデフォルトの設定をすることができます。

WagtailのTableBlockはHandsontableというライブラリを利用して作成されており、オプションで設定できる内容もHandsontableに準じます。Wagtailで設定できる内容と、デフォルトの設定は以下の通りです。

# デフォルトのオプション
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,
}


# オプションの指定方法は以下の通り
# TableBlockのtable_optionsに、上記の形式のdictionaryを指定する
class SampleBlock(StreamBlock):
    ...
    table = TableBlock(table_options=new_table_options)

minSpareRows - 空のグリッドの末尾に追加する行数。デフォルトは0。
startRows - 新しいテーブルのデフォルトの行の数。
startCols - 新しいテーブルのデフォルトの列の数。
colHeaders - TrueかFalseで指定する。新しく作成したテーブルの最初の列をヘッダーとして扱うかどうかを指定。Admin上のチェックボックスで上書きすることが可能。
rowHeaders - TrueかFalseで指定する。新しく作成したテーブルの最初の行をヘッダーとして扱うかどうかを指定。Admin上のチェックボックスで上書きすることが可能。
contextMenu - Admin上で右クリックした時に表示される選択肢の設定。こちらのリストのキーを指定可能。
editor - セルのデータタイプを指定する。textの他に、dateやcheckboxが指定可能。
stretchH - 列の幅がどのように広がるかを指定する。noneの場合は広がらない。lastの場合は最後の列だけ広がる。allの場合は全ての列が等しく広がる。デフォルトはall。
height - グリッドのデフォルトの高さ。デフォルトは108。startRowsで行数を変更した場合にはこちらの値も調整すると良い。
language - 言語設定。デフォルトでは、django.utils.translation.get_languageの設定を反映する。
renderer - Handsontableが使用するセルのレンダラーの指定。
autoColumnSize - autoColumnSizeプラグインの設定。デフォルトはFalse。

Handsontableの設定ドキュメントはこちらです。オプションの指定方法や内容がわからなければ参照してください。