WordPressのウィジェットを作成するときの最低限の基本形について

photo credit: itselea via photopin cc
photo credit: itselea via photopin cc

WordPressのウィジェットを自作する必要になったので色々調べた所、最低限の基本形が分かったのでメモです。

ウィジェット作成に必要な最低限の記述

ウィジェットを自作するときの最低限の記述は以下です。WordPressが用意しているウィジェット用のクラスを継承して作成します。

このソースコードを有効化しているWordPressテーマのfunctions.phpや自前のプラグインに貼り付けると、取り敢えず「外観 > ウィジェット」の一覧に「僕のウィジェット」という名前のウィジェットが現れます。

もちろん表示処理用の関数であるwidget()に記述をしていないので、このままでは有効化してもホームページには何も表示されません。

クラス「WP_Widget」について

継承元の親クラス「WP_Widget」はwp-includes/widgets.phpファイルで定義されています。ここで定義されているコンストラクタと3つの主要関数を、自作の子クラス「My_Widget」でオーバーライドします。

WordPressで最初から実装されてる各ウィジェット(「カレンダー」や「最新の投稿」など)も、このWP_Widgetクラスを継承して作られています。

コンストラクタについて

PHPのドキュメントには

PHP 5.3.3 以降、名前空間つきのクラス名の最後の部分と同じ名前のメソッドは コンストラクタとみなされなくなりました。 名前空間を使っていないクラスは今までと変わりません。

PHP: コンストラクタとデストラクタ – Manual』より一部抜粋

と記述されています。

ちょっと調べが甘く深くはまだ分からないのですが、他のプログラム言語のようにクラス名と同じ関数を記述して「これコンストラクタね!」とするのは今後控えた方が良いようです。なのでコンストラクタは予約された共通のコンストラクタ__construct()を使うことに。

ちなみにコンストラクタとは初期化処理専用の関数です。わざわざ初期化処理用の自作関数を用意して

と記述しなくても、コンストラクタはインスタンス生成時に自動的に実行されるので初期化処理のし忘れを防げます。詳しくはこちらが参考になります。

その他関数について

11行目: widget($args, $instance)

ウィジェットの表示処理を記述する関数です。

引数の$argsにはウィジェットの情報が渡されます。ダンプすると分かりますが、ウィジェットのタイトルやラッパー用タグが連想配列で入ってます(register_sidebar()関数に渡す引数がまさにコレです)。これらを必要に応じて出力します。

$instanceにはform()関数で出力した設定用フォームに入力された値が入ります。form()関数で何もフォームを出力せず、ウィジェットの管理画面から設定が保存されなければ中身はNULL(空)です。

14行目: update($new_instance, $old_instance)

ウィジェットの保存された新しい設定値を既に設定された値と比較したり、サニタイズしたりするための関数です。

$new_instanceには新しい設定値が、$old_instanceには既に設定された古い値が入ります。サニタイズは$new_instanceに行います。

17行目: form($instance)

管理画面の「外観 > ウィジェット」でウィジェットを有効化した時に表示される、設定フォームを出力するための関数です。

引数の$instanceには現在の設定値が渡されます。

基本形を少しだけ発展させる

上記の基本形のソースコードはあまりにも最低限なので、少し発展させてみましょう。

管理画面のウィジェットからタイトルを設定し、それを出力する処理を追加します。

参考になった(というよりもほぼコピーした)のはWordpress標準のテキストウィジェットです。テキストウィジェットのソースコードはwp-includes/default-widgets.phpの391行辺りで定義されてます。

やはり処理の流れは、28行目以降のform()関数で設定用フォームの出力をし、update()関数でサニタイズし(23行目)、10行目以降のwidget()関数で出力処理をしています。

そこまでソースコードも長くないので、1行ずつ処理を見ていけばウィジェット作成の基本的な部分が分かってくると思います。(解読のし易さも考えて本当に最低限にしました)

長々となってしまいましたが、ウィジェット作成の基本形はこんな感じになります。

最終更新日:2014年9月28日

コメント

「何かそこ違うよ」「こうした方が良い」っていう部分があったら指摘して頂けると嬉しいです。

トラックバック

トラックバックは現在ありません。

Trackback: https://increment-log.com/widget-make-model/trackback/