関数リファレンス/WP List Table

このクラスはWordPressの様々な管理画面上にあるリストテーブルを生成するために使われます。この機能を実装することは、Ajaxで動的に変更できる点と将来的にWordPressによってフックされる点において利点があります。

このクラスはまた、拡張・オーバーライドすることによって開発者も利用することができます。

このクラスはある種のフレームワークとして使われることを想定しており、データの読み込み、ソート、フィルターは手動で行う必要があります。とはいえ、WordPress標準のリスとテーブルを生成し、ページネーション、アクション、一括処理、フィルタリングといった機能を簡単に実装できるため、潜在的な力を秘めたツールです。

WP_List_Tableを使うために、まずそれを継承したクラスを作りましょう。あなたの作った新しいクラスはインスタンス化され、prepare_items()メソッドとdisplay()メソッドを必ず呼び出さなければなりません。

WordPressコアでは、拡張されたクラスを自動的に読み込んでインスタンス化する_get_list_table()関数を使うことによって、クラスを動的に読み込み・取得します。しかしながら、これはプライベート関数であるため、開発者は使ってはいけません。

開発者は_get_list_table()関数を直接使うことができないため、クラスを拡張し、手動でインスタンス化しなくてはなりません。

class Example_List_Table extends WP_List_Table {}
$example_lt = new Example_List_Table();

上記の例は何も出力しません。データおよび幾つかのメソッドを実装しないとWP_List_Tableは意味のあるテーブルを出力しません。

以下のプロパティはWP_List_Tableクラスに組み込まれています。

$items

表示したいデータを保存しておくために使われます。通常はprepare()メソッドでこの値がセットされます。

$_args

現在のテーブルに関する情報を配列として保存しておきます。通常、この値を直接いじることはありません。

$_pagination_args

テーブルのページネーションを行うために必要な情報を配列として保存します。通常、この値を直接いじることはありません。

$screen

現在のスクリーン名を保存する変数です。すべてのインスタンスにおいてスクリーン名を一致させたい場合に必要となります。

$_actions

キャッシュされた一括処理を保存します。直接いじることはありません。

$_pagination

ページネーション出力のキャッシュを保存します。直接いじることはありません。

これらのプロパティは組み込みのものではありませんが、幾つかのクラスメソッドによって必要とされます。拡張したクラスで定義してください。

$_column_headers

WordPressコアにおいて、このプロパティは自動で割り当てられます。開発者は必ずprepare_items() または __construct() において手動で定義するようにしてください。このプロパティは3つの値からなる配列です。はじめの値はカラムのスラッグとタイトルからなる配列（get_columns()を見てください）です。次がhiddenフィールドの値からなる配列です。そして最後がテーブルソートが可能なカラムの配列 (get_sortable_columns()メソッドを見てください)になります。

__construct( $args=array() )

コンストラクタ。デフォルトの変数とフィルターをセットします。開発者は必ずこれをオーバーライドし、親クラスのコンストラクタを呼び出して、単数系・複数形の名称とクラスがAjaxをサポートするか否かを設定してください。

ajax_user_can()

テーブルにパーミッション管理機能を持たせるためにオーバーライドすることができます。

prepare_items()

開発者はデータの取得、フィルタリング、ソート、ページネーションをするためにこのメソッドを使う必要があります。このメソッドはクラスを初期化して描画を開始する前に呼び出す必要があります。

set_pagination_args( $args )

このメソッドは内部的に呼び出され（通常はprepare_items()から）、ページネーションのための基本的な変数を設定します。利用できる変数には以下があります:

• total_items - 表示するアイテムの総数。通常はcount($data)といったシンプルなものになります。
• per_page - ページごとに表示する数
• total_pages - 総ページ数。空白のままでも構いませんし、次のように手動で計算しても構いません:ceil($total_items/$per_page)

get_pagination_arg( $key )

キーからページネーション変数を取得します。

has_items()

itemsプロパティが空でないかどうかを真偽値で返します。

no_items()

itemsが空のときに表示するメッセージを返します。

search_box( $text, $input_id )

検索ボックスを表示します。これを利用するにはリストテーブル（と検索ボックス）をformで包む必要があります。

get_views()

このテーブルで使われる値を連想配列で返します。

views()

ビューの名前を含む<ul>要素を描画します。

get_bulk_actions()

このメソッドを上書きし、テーブルで利用できる一括処理のリストからなる連想配列( action_slug => action_title)を設定できます。

bulk_actions()

呼び出されると、一括処理用のドロップダウンを出力します。これを使うにはリストテーブル（と検索ボックス）をformで包む必要があります。

current_action()

一括処理ドロップダウンで指定されている現在のアクションを返します。

row_actions( $actions, $always_visible = false )

このメソッドを呼び出し（通常はあなたが実装した他のメソッドから）、行アクションdivを追加します。$actionsパラメーターは連想配列で、キーにアクション名を、値にリンクを持ちます。

months_dropdown( $post_type )

$itemsを月でフィルタリングするための日付ドロップダウンを描画します。

view_switcher( $current_mode )

投稿タイプのビュースイッチボタン（リストビューと抜粋ビュー）を描画します。

comments_bubble( $post_id, $pending_comments )

コメントカウントバブルを描画します。

get_pagenum()

現在選択されているページ番号を返します。

get_items_per_page( $option, $default = 20 )

ページに表示するitemsの数を取得します。ユーザーも設定できます。

pagination( $which )

ページネーションのHTMLを生成し、_pageinationプロパティに割り当てます。一般的にこの関数を直接呼び出すことはありません。display()によって呼び出されます。

get_columns()

このメソッドをオーバーライドし、カラムの連想配列を返します。連想配列は次のフォーマットでなくてはなりません: 'slug' => 'Title' 通常はprepare_items()によって呼び出され、_column_headersプロパティを設定するのに使われます。

get_sortable_columns()

このメソッドをオーバーライドし、ソーティング可能にしたいカラムの配列を返してください。連想配列は次のフォーマットでなくてはなりません: 'slug'=>array('sortby',true) ２番目のプロパティの状態によってフィールドがすでにソートされた状態なのかが決まります。この関数は_colunmn_headersプロパティを設定するために使われます。

get_column_info()

この関数は_column_headersを組み立てるためにWordPressによって呼び出されます。一般的に開発者によっては使われません。その代わりに、prepare_items()で_column_headersを設定してください。

get_column_count()

表示されるカラムの数を返します。

print_column_headers( $with_id = true )

カラムのヘッダーを出力します。一般的にこの関数を直接呼び出すことはなく、display()メソッドの中で使われます。

display()

完全なリストテーブルをページに描画するために使われます。

get_table_classes()

テーブル要素に割当あてられるクラス名のリストを返します。テーブルのクラスをカスタマイズするためにオーバーライドしてください。

display_tablenav( $which )

テーブルナビゲーションをテーブルの上部または下部に出力します。display()の中で呼び出されるため、明示的に呼び出す必要はありません。

extra_tablenav( $which )

一括処理とページネーションコントロールの間に追加のコントローラーを出力したい場合はオーバーライドしてください。

display_rows_or_placeholder()

テーブルのtbody部分を生成します。display()の中で呼び出されるため、このメソッドを呼び出す必要はありません。

display_rows()

このメソッドはitemsをループし、テーブルの行としてページに出力します。一般的にこのメソッドはdisplay()の中で使われるため、呼び出す必要はありません。

single_row( $item )

itemsプロパティから一つのアイテムを取り出して出力します。一般的にこのメソッドはdisplay()の中で使われるため、呼び出す必要はありません。

single_row_columns( $item )

単一行に割り当てられた一つ一つのカラムを出力します。このメソッドはあなたの作った拡張クラスにカスタムメソッド（column_mycolumn()など）またはcolumn_default()メソッドが存在することを仮定しています。この双方とも基底クラスでは定義されておらず、拡張クラスにおいて実装しなければならないことを留意しておいてください。一般的にこのメソッドはdisplay()の中で使われるため、呼び出す必要はありません。

ajax_response()

Ajaxリクエストを扱います。

_js_vars()

クラスによって動的に定義されたJavascript変数を出力します。

column_default($item, $column_name)

このメソッドは基底クラスに定義されていませんが、拡張クラスで定義することができます。WP_List_Tablesがカラムを描画しようとしたとき（single_row_columns()内部）、まずカラム特定のメソッドの存在をチェックします。もし存在しなければ、このメソッドが変わりに使われます。このメソッドは2つの引数を受け取ります。一つは単数の$itemで、もう一つは$column_name（スラッグ）です。

column_$custom($item, $column_name)

カスタムカラムは開発者によって提供され、カラムを個別に取り扱うことができます。もしメソッド名がcolumn_movie_title()であれば、"movie_title"というスラッグを持つカラムを描画するときに使われます。column_default()と同様、2つの引数を受け取ります。単一の$item配列と$column_name（スラッグ）です。

詳細な例についてはCustom List Table Exampleをダウンロードしてください。

WP_List_TableはWordPress 3.1で実装されました。

WP_List_Table()は/wp-admin/includes/class-wp-list-table.phpにあります。