とりさんのソフト屋さん

WordPress 2.8でウィジェット作成(2) – 簡単なウィジェットを完成させる

WordPress 2.8でウィジェット作成(1) – Hello Worldの続きです。

ウィジェット作成に当る上の基礎知識（？）を記述しています。いきなり分け分からん！って人はWordPress 2.8でウィジェット作成(1) – Hello Worldを参考にしてください。

まずはウィジェットのタイトルを表示するまでを簡単に説明します。

管理画面のウィジェットにインプットボックスを設置

フォームメソッドにHTML出力を記述するだけです。。。

	function form($instance) {
		// 管理画面のウィジェットに出力するフォームを記述
		// $instanceには保存したオプションが連想配列で引き渡される。
		echo '<p>';
		echo '<label for="test_title">タイトル</label>';
		echo '<input type="text" name="title" id="test_title" />';
		echo '</p>';
	}

以下のような形になります。この段階では入力できても保存することは出来ません。また複数のウィジェットにも対応していません。つまり入力項目が表示されるだけで全く意味の無いプログラムです（おぃ

ここまでのソース

タイトルだけを表示するウィジェット作成

formメソッドの作成

formメソッドは以下のようになります。

	function form($instance) {
		// 管理画面のウィジェットに出力するフォームを記述
		// $instanceには保存したオプションが連想配列で引き渡される。

		//設定が保存されていない場合、デフォルトを設定
		$instance = wp_parse_args( (array) $instance, array( 'title' => '') );
		//HTMLタグを削除
		$title = strip_tags($instance['title']);

		//出力
		$titlename = $this->get_field_name('title');
		$titleid = $this->get_field_id('title');
		echo '<p>タイトルのid属性は'.$titleid.'です。</p>';
		echo '<p>タイトルのname属性は'.$titlename.'です。</p>';
		echo '<p>';
		echo '<label for="'.$titleid.'">タイトル</label>';
		echo '<input type="text" name="'.$titlename.'" id="'.$titleid.'" value="'.$title.'" />';
		echo '</p>';
	}

$instanceにMySQLに保存されているこのウィジェットの情報が連想配列で引き渡されます。

初めて使用した場合、初期値を設定する必要があります。そのため、$instance = wp_parse_args( (array) $instance, array( ‘title’ => ”) );で初期タイトルは空白に設定しています。

タイトル(title)と本文(text)という項目を使用したい場合は$instance = wp_parse_args( (array) $instance, array( ‘title’ => ‘Hey!’, ‘text’ => ‘入力してちょ’) );のような形になります。初期値は$instance['title']に”Hey!”、$instance['text']に”入力してちょ”となります。

idとname属性の命名について

新しいウィジェットAPIは初めから複数のウィジェット登録が出来るように設計されています。そのためユニークである必要がある入力項目のidとname属性の命名規則が既に決められており、name属性は$this->get_field_name()でid属性は$this->get_field_id()で得ることが出来ます。

get_field_*関数でidやname属性の値を決定することにより、開発の際、楽をすることが出来ます。

コンストラクタで$this->WP_Widgetに渡した第一引数が’TestWidget’で$this->get_field_name()に渡した引数が’title’の場合、帰ってくる値はwidget-testwidget[自動採番]['title']となります。

updateメソッドの作成

管理画面のウィジェットで保存されたオプションのエラーチェックなどを行います。

最後に連想配列でオプションの値を返すと、オプションとして保存されます。

エラーチェック処理(update)と表示(form)が分離されているので、エラーメッセージなどはメンバー変数で引き渡すと良いかも

	function update($new_instance, $old_instance) {
		// 保存したときのウィジェットのオプションを処理
		// $new_instanceには入力データが連想配列で引き渡される
		// $old_instanceにはそれまでの保存されていたオプション値が連想配列で引き渡される。
		// 最後に連想配列でオプション値を返す。

		$instance['title'] = strip_tags($new_instance['title']);

		//エラーチェック
		if (!$instance['title']) {
			//空白の時は、元に戻して、エラー表示
			$instance['title'] = strip_tags($old_instance['title']);
			$this->m_error = '<span style="color:#f00;">タイトルが空白です。元に戻します。</span>';
		}

		return $instance;
	}

メンバー変数m_errorを追加しているので注意

$this->get_field_name(’項目名’)でname属性の名前を付けると、複数ウィジェットでも$new_instance['項目名']で得ることが出来ます。楽ですねぇ。。。

widgetメソッドの作成

実際にWebサイトに訪れた人が見る部分です。

	function widget($args, $instance) {
		// ウィジェットのコンテンツ出力
		$instance = wp_parse_args( (array) $instance, array( 'title' => '') );

		$title = $instance['title'];
		$title = apply_filters('widget_title', $title);

		echo $args['before_widget']."\n";
		echo $args['before_title'].$title.$args['after_title']."\n";
		echo '<p>Hello World Widget</p>'."\n";
		echo $args['after_widget']."\n";
	}

$argにfunction.phpなどで実行されるregister_sidebar関数に与えたパラメータが連想配列で渡ります。

$instanceに管理画面で設定したウィジェットのオプションの値が連想配列で渡ります。

$instance = wp_parse_args( (array) $instance, array( ‘title’ => ”) );でオプション値が保存されていない場合のデフォルトを設定しています。formメソッドでも同じコードを実行しているので共通して使用するメソッドにまとめるとメンテしやすくなります。

$title = apply_filters(’widget_title’, $title);はお約束みたいなもので、通常xss対策などのコードを共通して実行させる意味があるのですが、widget_title関数が存在しない(探し方が悪い？)ので何も実行されていないようです。

実行結果

ここまで作成したウィジェットの動作を見てみると以下のような形になります。

管理画面のウィジェット

複数のウィジェットが登録できています。

サイドバーへの表示結果

出力HTMLは以下です。

</li>
<li id="testwidget-5" class="widget widget_test_widget">
<h2 class="widgettitle">一番目のタイトル</h2>

<p>Hello World Widget</p>
</li>

<li id="testwidget-6" class="widget widget_test_widget">
<h2 class="widgettitle">二番目のタイトル</h2>

<p>Hello World Widget</p>
</li>

<li id="testwidget-7" class="widget widget_test_widget">
<h2 class="widgettitle">ああああ</h2>

<p>Hello World Widget</p>
</li>

HTMLだとイメージが沸きにくいのでキャプチャーも載せます。

参考リンク

Widgets API « WordPress Codex

本家の解説

testwidgets-2.php

今回作ったタイトルだけプラグイン

testwidgets-3.php

タイトルだけプラグインに本文という項目を付け足したもの

default-widgets.php

WordPress2.8の標準のWidgetのソース(カテゴリ、タグ、カレンダウィジェットなどなど)

widgets.php

WordPress2.8のWidgetクラスのソース

最後に

本当は3、4回に分ける予定でしたが、2回で終了です。

ウィジェットのソースが綺麗かつ簡単になりましたねぇ。。。でもまだ公開中のプラグイン変更して無いや。。。（汗

間違いがあればメール、お問い合わせ、コメントなどで受け付けています。

日記(?)

最近、本文の初めに画像を表示するようにしているのですが今回はフリーの看板画像を探していたのだが見つかりませんでした。これに時間を掛けて撮りに行ったり、探し回っているのでは本末転倒なので止めました（汗

画像ファイルなどを公開しているサイトは何故スパムサイトが多いのだろう。。。