ウィジェットAPI

WordPress 2.8 から、サイドバーに配置するためのウィジェットプラグインを簡単に作れるようになりました。

具体的には WordPress が提供する WP_Widget クラスを継承して、コンストラクタ・各種メソッドに処理を記述するだけで、ウィジェットプラグインが実装できるようになりました。

//クラス名は任意
class My_Widget extends WP_Widget {
	//コンストラクタ クラスと同じ名称
	function My_Widget() {
		// ウィジェットの初期設定
	}

	function widget($args, $instance) {
		// ウィジェットのコンテンツ出力
	}

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

	function form($instance) {
		// 管理画面のウィジェットに出力するフォームを記述
		// $instanceには保存したオプションが連想配列で引き渡される。
	}
}
//MyWidgetInit関数
function MyWidgetInit() {
	//ウィジェットのクラス名を登録
	register_widget('My_Widget');
}
//widgets_initアクション時にMyWidgetInit関数を実行
add_action('widgets_init', 'MyWidgetInit');

コンストラクタでは、基底クラスのコンストラクタを呼び出して初期処理してあげましょう。

    /** constructor */
    function My_Widget() {
        parent::WP_Widget(
		'MyWidget' ,
		'このウィジェットのタイトル' ,
		array(
			'classname' => 'widget_test_widget', 
			'description' => 'このウィジェットの説明'
			)
		);	
    }

第1引数はウィジェットのID
第2引数はウィジェットの表示タイトル
第3引数は、ウィジェットのオプションを連想配列で指定します。
classname は、サイトに表示されるウィジェットのクラス名(CSS)
description は、ダッシュボードに表示されるウィジェットの説明文

widget メソッドには、ウィジェットとしてサイトに出力する内容を記述します。
例えば、以下の用に記述すれば 'Hello World! と表示されるウィジェットが完成します。

    function widget($args, $instance) {
        // ウィジェットのコンテンツ出力
        echo $args['before_widget']."\n";
        echo $args['before_title'].'Hello World!'.$args['after_title']."\n";
        echo '<p>Hello World!</p>'."\n";
        echo $args['after_widget']."\n";
    }

第1引数には、各テーマのregister_sidebar関数で設定されたパラメータが連想配列で
第2引数には、データベースに保存されているウィジェットのオプションが連想配列で引き渡されます。

また、サイトに出力されるコードには parent::WP_Widget() で指定した classname が自動的に付与されます。

ダッシュボードのウィジェットにインプットボックスを設置するには form メソッドに HTML 出力を記述しましょう。

第1引数には、データベースに保存されているウィジェットのオプションが連想配列で引き渡されます。
初めてウィジェットを使用するときは、データベースにオプションが保存されていないため、wp_parse_args() 関数で、デフォルト値を設定すると良いでしょう。

    function form($instance) {
        extract(wp_parse_args(
            (array) $instance ,
            array(
                'title' => '' ,
            )
        ), EXTR_SKIP);

        // title
        echo '<p>';
        echo '<label for="'.$title['name'].'">' . __('Title:');
        echo '<input class="widefat" id="'.$title['id'].'" name="'.$title['id'].'" type="text" value="'.$title['val'].'" />';
        echo '</label>';
        echo '</p>' . "\n";
    }

インプットボックスで入力された値をデータベースに保存するには update メソッドを記述しましょう。
入力されたオプション値のエラーチェック等を行い、最後に保存したいオプション値を連想配列で返してあげてください。

    function update($new_instance, $old_instance) {
        $new_instance = wp_parse_args(
            (array) $new_instance ,
            array(
                'title' => '' ,
            )
        );
        return (
            $new_instance !== $old_instance
            ? $new_instance
            : $old_instance
            );
    }

第1引数には、入力されたオプション値
第2引数には、現在データベースに保存されているオプション値がセットされてきます。

最後に widgets_init アクションフックに register_widget() 関数を呼び出す関数を登録すれば完了です。

//register_widget() 関数を呼び出す関数
function MyWidgetInit() {
    //ウィジェットのクラス名を登録
    register_widget('My_Widget');
}
add_action('widgets_init', 'MyWidgetInit');

register_widget() 関数の第1引数には、WP_Widget クラスを継承して作成した Widget クラスのクラス名を記述してください。

公式プラグインディレクトリでの公開