2017/04/10カテゴリー:WordPress過去に「WordPressのウィジェットを作成するときの最低限の基本形について」という記事を公開しました。WordPressのウィジェットを作成するときの最低限の基本形についてこれを書いた当初から3年が過ぎました。WordPressの機能が拡張されていくにつれウィジェット関連の実装も少し変わってきています。こちらの記事内容は古い点が数ヵ所ある状態でした。(そして書き方がなんか雑)ですので、あらためてウィジェット作成に関する情報をまとめることにしました。update()データ検証/無害化ウィジェットのテンプレートウィジェットAPIの公式ドキュメントウィジェット作成に関する情報のまとめウィジェットのクラス構成と登録ウィジェットを構成するプログラムコードは以下になります。初期化処理(ウィジェットの各種設定)を行います。ウィジェットの内容をWebページに出力(HTML表示)します。管理画面のウィジェット設定フォームを出力します。ウィジェットオプションを安全な値で保存するためにデータ検証/無害化します。}}「WP_Widget」クラスを継承し任意の名前でサブクラスを作成します。これと合わせて「widgets_init」フックでウィジェットの登録処理を行います。);});上記の2つのコードを記述すると、一先ず管理画面のウィジェット一覧に「テンプレートウィジェット」というウィジェットが現れます(勿論オプション設定はまだ無いです)。以降、ウィジェットでプログラミングが必要な4つのメソッドについて説明いたします。__construct()ウィジェットの初期化処理(各種設定)を行います。やることは大まかに分けて3項目。親クラスのコンストラクタで初期化3項目をコード化した例です。初期化処理(ウィジェットの各種設定)を行います。'テンプレートウィジェットの説明文です。情報用の設定値は以下のように扱われます。classname出力するウィジェットのクラス名を指定します。デフォルトはクラス名になっており、大文字はすべて小文字になります(lowercase)。「Widget_Template」なら「class=”widget_template”」となります。description管理画面で表示するウィジェットの説明文です。指定しなければ親クラスのコンストラクタで指定する$nameが適用されます。customize_selective_refreshカスタマイズページでリアルタイムにウィジェット要素のHTMLを更新する機能「セレクティブリフレッシュ」へ対応の有無を設定します。デフォルトはfalseです。操作用の設定値の「width」「height」はウィジェットの設定フォームのサイズに影響が出ます。カスタマイズ)両方で扱われる値です。各々のページで挙動が違います。親要素に横幅が収まりきらないとき、設定フォームを開いた時の横幅に割り当てられる。サイドバーに横幅が収まりきらないとき、設定フォームが右側にフェードイン表示される。ウィジェット)では無視されます。カスタマイズページでwidthの値により「右側にフェードイン表示される」UIに変更された場合にのみ、設定フォームの高さが”min-height”で確保されるようになります。操作用の設定値の参考画像を用意したので、こちらを見ていただければ分かりやすいでしょう。widthの値が収まらないと設定フォームの領域が広がるwidthの値がカスタマイズページのサイドバーに収まらないと右側に設定フォームがフェードイン表示されるheightの値はカスタマイズページ&UI変更時のみ有効。親クラスのコンストラクタに各設定を渡して初期化します。$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()」は実装する機能によってコードが結構変わってしまうので簡単なサンプルコードを記述します。widget()ウィジェットの内容をWebページに出力(HTML表示)する関数です。例としてタイトル、テキストエリアを表示するコード(WordPress標準のテキストウィジェットとほぼ同様)です。register_sidebar()で設定したウィジェットの開始/終了タグ、タイトルの開始/終了タグなどが渡される。管理画面から入力した値が渡される。ウィジェット終了タグ(</div>など)}処理内容はシンプルです。設定フォーム(次で説明する関数)に入力してあるオプション「タイトル」「テキスト」を取得して、それをウィジェット用のHTMLタグで囲って出力しています。(ウィジェット用のHTMLは$argsに、オプションは$instanceに引数で渡ってきます)引数の説明$argsregister_sidebar()で登録した値が渡ってきます。これらで登録したウィジェット用のタグが取得できるので、出力時に使います。(他にもサイドバーのIDや名前も値にあります)$instance管理画面で入力したオプションが渡ってきます。このオプションは次の「form()」関数で用意しましょう。form()widget()でWebページに表示するための、オプションを入力する設定フォーム出力関数です。引数$instanceにはWordPressに保存されているオプション値が渡ってくるので、そのまま扱います。管理画面のウィジェット設定フォームを出力します。現在のオプション値が渡される。<?php}この関数での主な処理は3ステップです。デフォルトのオプション値を定義し(8行目)、WordPressに保存されている現在のオプション値と結合します(14行目)。値が未定義のオプション値を無くすためです。必要であればオプション値の無害化を行います(17行目)。設定フォームを出力します。(20行目以降)3ステップ目の設定フォームの出力コードでは2つのメソッドを使用します。)」この”フィールドネーム”引数にはオプションで使用している文字列を渡しましょう。今回の例だと「title」と「text」になります。(「input」「textarea」タグに”widefat”というクラスが指定されていますが、これは要素を横幅一杯に表示するCSSプロパティが設定されています。WordPressで用意されているクラスです。update()この関数もwidget()やform()同様、ウィジェット機能によってコードが変わってしまいます。内容はウィジェットオプションのデータ検証(バリデーション)/無害化(サニタイズ)を行うための関数です。安全な値を返してWordPressに保存してもらいます。保存処理は自動的に行ってくれます。タイトル、テキストを無害化して返す処理です。$instance;}タイトルは余計なHTMLタグや改行を排除するsanitize_text_field()で無害化し、テキストはHTML操作の権限が低いユーザに対してのみ無害化するwp_kses_post()を使っています。日本語版』を参考にすると良いでしょう。日本語版』にまとめられています。(※WordPressでは「サニタイズ(sanitize)」という言葉が使われておりますが、実際はエスケープ処理が殆どです。誤解を招きやすい言葉で自分もよく混乱してしまうのですが関数名にならってそのまま「サニタイズ」としています)ウィジェットのテンプレートそれでは、上述のコードをすべてまとめたウィジェットのテンプレートです。まとめたコードではwidget()内でタイトルに「widget_title」フィルターを追加してます。これはデフォルトで用意されてるウィジェット全てに適用されているので、テンプレートも対応する形にしました(フィルターの用途はタイトルのテキスト直前にアイコン表示などでしょうか)。こちらをそのままfunctions.phpにコピペすると簡易なウィジェットが実装されます。以上、ご参考になれば。ウィジェットAPIの公式ドキュメント最後にAPIの公式ドキュメントのリンクを貼っておきます。最新のWordPressバージョン(2017年4月7日現在は4.7.3)の各デフォルトウィジェットに新たなコードが追加されていますが、まだ説明文は見当たらなかったのもあってまとめた次第です。MarkRyoichi(しつ)除菌ティッシュを買い込んで使いきれずによく乾かす人。療養目的で退職し、どうやって生きていくか模索中。最近は勉強目的でLaravelやVue.js弄ったり、趣味で音で遊んでます。※2019年10月16日現在ブログリニューアル中です。崩れなどが発生していたらすみません。Log検索:検索カテゴリーCSSHTMLJavaScriptUnityWebサービスWordPressデザイン。