• サイトデザイン工事中です。ご意見をお寄せください。
  • 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。（詳細）

【このWikiはいつでも誰でも編集できます】

WordPress ウィジェット API

提供：WordPress Codex 日本語版
移動： 案内, 検索

目次

ウィジェット API

このページは、WordPress ウィジェット API （アプリケーションプログラミングインターフェース） についての技術文書です。この文書の想定する読者は、WordPress テーマ作成者、プラグイン作成者、およびスタンドアロンのウィジェットを作りたい方全てです。この文書では、PHP スクリプトの基礎知識を前提としています。

ウィジェットは、呼び出されたときに文字列データを STDOUT に出力する PHP 関数 です。PHP 関数を WordPress ウィジェットにするには、以下のようにして登録します。WordPress ウィジェット API 関数が登録する PHP コールバック (PHP ドキュメントの 擬似タイプ) を用います。

Wordpress ウィジェット API は、wp-includes/widgets.php ファイルにあります。

関数リファレンス

'サイドバー関数
ウィジェット関数

注意: 今後変更される可能性があるので、wp_ で始まる関数は、使うべきでありません。このため、wp_register_sidebar_widget()/en ではなく、register_sidebar_widget()/en を使用します。

サイドバーの定義

これらの関数は、サイドバーのあるテーマ作成に使用します。

複数のサイドバーの登録 

register_sidebars( $count, $args );

利用中のテーマで使用する 1 つ以上のサイドバーを登録します。ほとんどのテーマはサイドバーが 1 つあります。このため、サイドバー数パラメータはオプションで、デフォルト値は 1 です。

$args パラメータは、register_sidebar() に渡され、そのフォーマットに準じます。ただし名前は、サイドバーが複数の場合、sprintf() で処理して一意の番号を挿入または付加します。

例えば、次の行は、"Foobar 1" と "Foobar 2" というサイドバーを作成します。 

register_sidebars(2, array('name'=>'Foobar %d'));

1 つのサイドバー登録 

register_sidebar( $args );

オプション $args パラメータは連想配列で、アクティブなウィジェットコールバック関数に第一引数として渡されます。(配列の代わりに文字列が渡されると、parse_str() によって連想配列を作成します。) 本引数の基本的な使い方は、ウィジェットおよびウィジェットのタイトルを囲む、テーマに特有の HTML タグを渡すことです。デフォルトは以下のとおりです。 

 'before_widget' => '<li id="%1$s" class="widget %2$s">',
 'after_widget' => "</li>n",
 'before_title' => '<h2 class="widgettitle">',
 'after_title' => "</h2>n"

register_sidebars の代わりにこの関数を呼び出す必要があるのは、"Right Sidebar" や "Left Sidebar" 等のようにサイドバーに個別に命名する場合、異なる方法でマークアップする場合、ぐらいでしょう。名前が表示されるのは管理画面のみですが、サイドバー編集を保存するインデックスとしても使用されます。したがって、他のテーマが同じ名前のサイドバーを使用していると、サイドバーの編集結果が再利用されたり、更新されたりします。

デフォルト before/after 値は、サイドバーがリストを生成し、タイトルを "h2" でマークアップすることを想定しています。全てのテーマが、この規約に従うことを推奨します。すると、この規約に従ったテーマでは、タグを気にせずに、簡単にサイドバーを登録することができます。 やむを得ない理由で、このようにマークアップできない場合、サイドバーを登録するときに指定することができます。 id 属性と class 属性を丸ごとコピーし、内部 sprintf が動作し、個々のウィジェットに CSS スタイルが適用されるようにしましょう。

サイドバーをテーマに表示 

dynamic_sidebar( $sidebar );

この関数はアクティブなウィジェットコールバック関数を順に呼び出し、サイドバーに表示します。複数のサイドバーがある場合、表示するサイドバーの番号または名前を知らせる必要があります。この関数が正しく実行されると true を返し、失敗すると false を返します。

静的なサイドバーを表示するかどうかを決定するのに、返り値を使用すべきです。こうすることで、ウィジェットプラグインがアクティブでない場合にも、テーマがきちんと表示されるようにできます。致命的なエラーを防ぐために、以下のように使用することをお勧めします。 

    <ul id="sidebar">
        <?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>
            <li>{static sidebar item 1}</li>
            <li>{static sidebar item 2}</li>
        <?php endif; ?>
    </ul>

サイドバーを番号で登録している場合、番号で呼び出します。名前で登録している場合は、名前で呼び出します。

ウィジェットの開発

2.8以降のウィジェット開発

version 2.8 から、ウィジェットの作成が簡単になりました。ウィジェットを作るには、標準ウィジェットクラスとこのクラスのいくつかのメソッドを継承すれば良いのです。

基底クラスでは、動作するウィジェットで継承すべきメソッドについての情報も記述されています。

標準的な使い方 

class My_Widget extends WP_Widget {
	function My_Widget() {
		// widget actual processes
	}

	function form($instance) {
		// outputs the options form on admin
	}

	function update($new_instance, $old_instance) {
		// processes widget options to be saved
	}

	function widget($args, $instance) {
		// outputs the content of the widget
	}

}
register_widget('My_Widget');

ウィジェットの例

サンプルコードは、表示タイトルを変更する設定フォームを持つ FooWidget という名前のウィジェットを作成します。 

/**
 * FooWidget Class
 */
class FooWidget extends WP_Widget {
    /** constructor */
    function FooWidget() {
        parent::WP_Widget(false, $name = 'FooWidget');	
    }

    /** @see WP_Widget::widget */
    function widget($args, $instance) {		
        extract( $args );
        $title = apply_filters('widget_title', $instance['title']);
        ?>
              <?php echo $before_widget; ?>
                  <?php if ( $title )
                        echo $before_title . $title . $after_title; ?>
                  Hello, World!
              <?php echo $after_widget; ?>
        <?php
    }

    /** @see WP_Widget::update */
    function update($new_instance, $old_instance) {				
        return $new_instance;
    }

    /** @see WP_Widget::form */
    function form($instance) {				
        $title = esc_attr($instance['title']);
        ?>
            <p><label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?> <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" /></label></p>
        <?php 
    }

} // class FooWidget

このサンプルウィジェットは、widgets_init フックで登録することができます。 

// register FooWidget widget
add_action('widgets_init', create_function('', 'return register_widget("FooWidget");'));

これで終わりです。複数のウィジェットも自動生成されます。複数のウィジェットのための調整は不要です。

詳細は 新ウィジェット API を参照してください。

ウィジェットの新規作成

古い (WordPress 2.2 以降では不要の) オリジナルウィジェットプラグイン に含まれている Google 検索ウィジェットは、コメントがつけられています。チュートリアルを参考にしてください。ガイドラインをいくつか示します。 

      function widget_myuniquewidget($args) {
          extract($args);
      ?>
              <?php echo $before_widget; ?>
                  <?php echo $before_title
                      . 'My Unique Widget'
                      . $after_title; ?>
                  Hello, World!
              <?php echo $after_widget; ?>
      <?php
      }
      register_sidebar_widget('My Unique Widget',
          'widget_myuniquewidget');

重要:上記テンプレートをプラグインとして使用するには、以下で囲んでください。 

function widget_myuniquewidget_register() {
  --the above goes here--
  register_sidebar_widget('My Unique Widget','widget_myuniquewidget');}
add_action('init', widget_myuniquewidget_register);

      register_widget_control($name, $callback [, $width [, $height ]] );

他にウィジェットでできる事は？

このような質問は非常に嬉しいです。いくつかのアイデアを紹介します。

ウィジェット - １ つか複数か

ウィジェットは、１ 度に １ つだけ、あるいは１ 度に複数可能にコーディングすることができます。いくつかのルールに従うと、ウィジェットを複数回使用するための作業を WordPress が行ってくれます。

外部資料

最新英語版： WordPress Codex » Plugins/WordPress Widgets Api （最新版との差分）

「http://wpdocs.sourceforge.jp/WordPress_%E3%82%A6%E3%82%A3%E3%82%B8%E3%82%A7%E3%83%83%E3%83%88_API」より作成
個人用ツール
名前空間
変種
操作
このサイトについて
特集
サーバ別情報
リファレンス
ドキュメント整備
ツールボックス
他の言語