WordPress ダッシュボードに独自のウィジェットを追加

WordPress の管理画面のダッシュボードに独自のウィジェット（ボックス）を追加する方法を調べたので備忘録として残します。

ダッシュボードに独自のウィジェットを追加するには wp_add_dashboard_widget 関数を利用します。実行する場所は、wp_dashboard_setup アクション フックです。マルチサイトのネットワーク管理ダッシュボードへ追加する場合は、wp_network_dashboard_setup アクション フックです。

以下は、基本的な使い方です。functions.php などに記述してください。

function dashboard_hello_widget_setup() {
    wp_add_dashboard_widget(
        'hello_widget', // ウィジェットを一意識別するスラッグ
        'ようこそ', // ウィジェットのヘッダに表示される名前
        'dashboard_hello_widget' // ウィジェットのコンテンツを表示するように作成した関数の名前
    );
}

add_action( 'wp_dashboard_setup', 'dashboard_hello_widget_setup' );

function dashboard_hello_widget() {
    // ここでウィジェットの内容を出力する。
    echo 'Hello Widget!';
}

これだけでダッシュボードに独自のウィジェットを追加できます。とっても簡単です。

これだけでは寂しいので、ちょっとだけ実用になるウィジェットを作成してみたいとおもいます。

メモ ウィジェット

メモ（文字列）を登録して表示するだけの簡単なウィジェットです。

wp_add_dashboard_widget 関数には、ウィジェット オプション フォームを表示する関数を設定するオプションがあります。

このオプション フォームで文字列を登録します。

function dashboard_memo_widget_setup() {
    //if ( ! current_user_can( 'administrator' ) ) return;
    wp_add_dashboard_widget(
        'dashboard-memo-widget',
        'メモ',
        'dashboard_memo_widget',
        'dashboard_memo_widget_option_form'
    );
}

add_action( 'wp_dashboard_setup', 'dashboard_memo_widget_setup' );

function dashboard_memo_widget() {
    $memo = get_option( 'dashboard-memo-widget-memo', '' );
    if ( $memo === '' ) {
        echo '<p>メモはありません。<p>' . "\n";
    } else {
        echo '<p>' . nl2br( esc_textarea( $memo ) ) . '<p>' . "\n";
    }
}

function dashboard_memo_widget_option_form() {
    if ( isset( $_POST['dashboard-memo'] ) ) {
        update_option( 'dashboard-memo-widget-memo', $_POST['dashboard-memo'] );
    }
    $memo = get_option( 'dashboard-memo-widget-memo', '' );
    echo '<p><textarea id="dashboard-memo" class="widefat" name="dashboard-memo" rows="3">' . esc_textarea( $memo ) . '</textarea></p>';
}

Nonce の検証

公式オンライン マニュアルには特に記載がないのですが、ウィジェット オプション フォームには Nonce が設定されており検証もされています。よって、Nonce を手動で追加する必要はありません。