WordPressのウィジェット作成方法に関する情報のまとめ

過去に「WordPressのウィジェットを作成するときの最低限の基本形について」という記事を公開しました。

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

これを書いた当初から3年が過ぎました。WordPressの機能が拡張されていくにつれウィジェット関連の実装も少し変わってきています。こちらの記事内容は古い点が数ヵ所ある状態でした。(そして書き方がなんか雑)

ですので、あらためてウィジェット作成に関する情報をまとめることにしました

ウィジェット作成に関する情報のまとめ

ウィジェットを自作するのは殆どがプログラマかと思われるので、なるべくそういった層に向けた書き方にするのでご了承ください。

ウィジェットのクラス構成と登録

ウィジェットを構成するプログラムコードは以下になります。(まずは管理画面にウィジェットを表示するだけの最低限な内容になります)

WP_Widget」クラスを継承し任意の名前でサブクラスを作成します。これと合わせて「widgets_init」フックでウィジェットの登録処理を行います。

上記の2つのコードを記述すると、一先ず管理画面のウィジェット一覧に「テンプレートウィジェット」というウィジェットが現れます(勿論オプション設定はまだ無いです)。

以降、ウィジェットでプログラミングが必要な4つのメソッドについて説明いたします。

  1. コンストラクタ: __construct()
  2. ウィジェットをWebページに出力: widget()
  3. 管理画面のウィジェット設定フォームを出力: form()
  4. ウィジェットオプションのデータ検証/無害化: update()

1.コンストラクタ: __construct()

ウィジェットの初期化処理(各種設定)を行います。やることは大まかに分けて3項目。

  1. ウィジェットの情報用の設定値を配列で用意
  2. ウィジェットの操作用の設定値を配列で用意
  3. 親クラスのコンストラクタで初期化

3項目をコード化した例です。

A.情報用の設定値

情報用の設定値は以下のように扱われます。

情報用の設定値($widget_options)
classname出力するウィジェットのクラス名を指定します。デフォルトはクラス名になっており、大文字はすべて小文字になります(lowercase)。「Widget_Template」なら「class=”widget_template”」となります。
description管理画面で表示するウィジェットの説明文です。指定しなければ親クラスのコンストラクタで指定する$nameが適用されます。
customize_selective_refreshカスタマイズページでリアルタイムにウィジェット要素のHTMLを更新する機能「セレクティブリフレッシュ」へ対応の有無を設定します。デフォルトはfalseです。
B.操作用の設定値

操作用の設定値の「width」「height」はウィジェットの設定フォームのサイズに影響が出ます

操作用の設定値($control_options)
widthウィジェット設定ページ(外観 > ウィジェット)、カスタマイズページ(外観 > カスタマイズ)両方で扱われる値です。各々のページで挙動が違います。

  • ウィジェット設定ページ: 親要素に横幅が収まりきらないとき、設定フォームを開いた時の横幅に割り当てられる。
  • カスタマイズページ: サイドバーに横幅が収まりきらないとき、設定フォームが右側にフェードイン表示される。(UIが変わる。通常のUIはアコーディオン)
heightこちらはカスタマイズページ(外観 > カスタマイズ)でのみ扱われ、ウィジェット設定ページ(外観 > ウィジェット)では無視されます。カスタマイズページでwidthの値により「右側にフェードイン表示される」UIに変更された場合にのみ、設定フォームの高さが”min-height”で確保されるようになります。

操作用の設定値の参考画像を用意したので、こちらを見ていただければ分かりやすいでしょう。

widthの値が収まらないと設定フォームの領域が広がる

 

widthの値がカスタマイズページのサイドバーに収まらないと右側に設定フォームがフェードイン表示される

 

heightの値はカスタマイズページ&UI変更時のみ有効。このように高さがmin-heightで確保される
C.親クラスのコンストラクタで初期化

親クラスのコンストラクタに各設定を渡して初期化します。

親クラスのコンストラクタ
parent::__construct( $id_base, $name, $widget_options, $control_options )
$id_base出力するウィジェットのidのベースとなる文字列を指定します。falseでデフォルトとなります。デフォルトはクラス名を使用しますが、クラス名によってIDの付き方が変わります。例えばクラス名が「Template_Widget」なら「id=”template_widget-{id}”」と設定されます(大文字は小文字に変換)。例外として「Widget_Template」のように接頭辞が”Widget”となっており、かつアンダースコア(_)で区切られている場合は”Widget_”が排除され「id=”template-{id}”」となります。
$name管理画面で表示するウィジェットの名前になります。falseを指定すると空の文字列を出力します(つまりウィジェット名は表示されません)
$widget_options上述した、ウィジェットの情報用の設定値を配列で渡します。(任意)
$control_options上述した、ウィジェットの操作用の設定値を配列で渡します。(任意)

コンストラクタ以外の関数、「widget()」「form()」「update()」は実装する機能によってコードが結構変わってしまうので簡単なサンプルコードを記述します。

2.ウィジェットをWebページに出力: widget()

ウィジェットの内容をWebページに出力(HTML表示)する関数です

例としてタイトル、テキストエリアを表示するコード(WordPress標準のテキストウィジェットとほぼ同様)です。

処理内容はシンプルです。設定フォーム(次で説明する関数)に入力してあるオプション「タイトル」「テキスト」を取得して、それをウィジェット用のHTMLタグで囲って出力しています。(ウィジェット用のHTMLは$argsに、オプションは$instanceに引数で渡ってきます)

引数の説明
ウィジェットの内容を出力
widget( $args, $instance )
$argsregister_sidebar()で登録した値が渡ってきます。

  • 「$args[‘before_widget’]」でウィジェット開始タグ
  • 「$args[‘after_widget’]」でウィジェット終了タグ
  • 「$args[‘before_title’]」でタイトル開始タグ
  • 「$args[‘after_title’]」でタイトル終了タグ

これらで登録したウィジェット用のタグが取得できるので、出力時に使います。(他にもサイドバーのIDや名前も値にあります)

$instance 管理画面で入力したオプションが渡ってきます。このオプションは次の「form()」関数で用意しましょう。

3.管理画面のウィジェット設定フォームを出力: form()

widget()でWebページに表示するための、オプションを入力する設定フォーム出力関数です

引数$instanceにはWordPressに保存されているオプション値が渡ってくるので、そのまま扱います。

この関数での主な処理は3ステップです。

  1. デフォルトのオプション値を定義し(8行目)、WordPressに保存されている現在のオプション値と結合します(14行目)。値が未定義のオプション値を無くすためです。
  2. 必要であればオプション値の無害化を行います(17行目)。
  3. 設定フォームを出力します。(20行目以降)

3ステップ目の設定フォームの出力コードでは2つのメソッドを使用します。

  • labelのfor属性/inputのid属性には「$this->get_field_id( ‘フィールドネーム’ )
  • inputのname属性には「$this->get_field_name( ‘フィールドネーム’ )

この”フィールドネーム”引数にはオプションで使用している文字列を渡しましょう。今回の例だと「title」と「text」になります。

(「input」「textarea」タグに”widefat”というクラスが指定されていますが、これは要素を横幅一杯に表示するCSSプロパティが設定されています。WordPressで用意されているクラスです。また、各フォームはpタグで囲うと綺麗に整います)

4.ウィジェットオプションのデータ検証/無害化: update()

この関数もwidget()やform()同様、ウィジェット機能によってコードが変わってしまいます。が、内容はウィジェットオプションのデータ検証(バリデーション)/無害化(サニタイズ)を行うための関数です。安全な値を返してWordPressに保存してもらいます。保存処理は自動的に行ってくれます。

タイトル、テキストを無害化して返す処理です。

タイトルは余計なHTMLタグや改行を排除するsanitize_text_field()で無害化し、テキストはHTML操作の権限が低いユーザに対してのみ無害化するwp_kses_post()を使っています。

データ検証/無害化

ウィジェットに入力するオプション値は、型によってデータ検証/無害化の方法が変わってくるので『データ検証 – WordPress Codex 日本語版』を参考にすると良いでしょう。ユーザ権限については『ユーザーの種類と権限 – WordPress Codex 日本語版』にまとめられています。

(※WordPressでは「サニタイズ(sanitize)」という言葉が使われておりますが、実際はエスケープ処理が殆どです。誤解を招きやすい言葉で自分もよく混乱してしまうのですが関数名にならってそのまま「サニタイズ」としています)

ウィジェットのテンプレート

それでは、上述のコードをすべてまとめたウィジェットのテンプレートです。

まとめたコードではwidget()内でタイトルに「widget_title」フィルターを追加してます。これはデフォルトで用意されてるウィジェット全てに適用されているので、テンプレートも対応する形にしました(フィルターの用途はタイトルのテキスト直前にアイコン表示などでしょうか)。

こちらをそのままfunctions.phpにコピペすると簡易なウィジェットが実装されます。以上、ご参考になれば。

ウィジェットAPIの公式ドキュメント

最後にAPIの公式ドキュメントのリンクを貼っておきます。最新のWordPressバージョン(2017年4月7日現在は4.7.3)の各デフォルトウィジェットに新たなコードが追加されていますが、まだ説明文は見当たらなかったのもあってまとめた次第です。

英語版:Widgets API « WordPress Codex

日本語版:WordPress ウィジェット API – WordPress Codex 日本語版

最終更新日:2017年4月12日

コメント

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

トラックバック

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

Trackback: https://increment-log.com/widget-create-summary/trackback/