当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「WordPress ウィジェット API」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(サイドバーの定義: セクションを追加)
(1 つのサイドバー登録)
87行目: 87行目:
 
</pre>
 
</pre>
  
The only times you might need to call this function instead of register_sidebars の代わりにこの関数を呼び出す必要があるのは、"Right Sidebar" や "Left Sidebar" 等のようにサイドバーに個別に命名する場合、異なる方法でマークアップする場合、ぐらいでしょう。名前が表示されるのは管理画面のみですが、サイドバー編集を保存するインデックスとしても使用されます。したがって、他のテーマが同じ名前のサイドバーを使用していると、サイドバーの編集結果が再利用されたり、更新されたりします。
+
register_sidebars の代わりにこの関数を呼び出す必要があるのは、"Right Sidebar" や "Left Sidebar" 等のようにサイドバーに個別に命名する場合、異なる方法でマークアップする場合、ぐらいでしょう。名前が表示されるのは管理画面のみですが、サイドバー編集を保存するインデックスとしても使用されます。したがって、他のテーマが同じ名前のサイドバーを使用していると、サイドバーの編集結果が再利用されたり、更新されたりします。
  
 
デフォルト before/after 値は、サイドバーがリストを生成し、タイトルを "h2" でマークアップすることを想定しています。全てのテーマが、この規約に従うことを推奨します。すると、この規約に従ったテーマでは、タグを気にせずに、簡単にサイドバーを登録することができます。 やむを得ない理由で、このようにマークアップできない場合、サイドバーを登録するときに指定することができます。 id 属性と class 属性を丸ごとコピーし、内部 sprintf が動作し、個々のウィジェットに CSS スタイルが適用されるようにしましょう。
 
デフォルト before/after 値は、サイドバーがリストを生成し、タイトルを "h2" でマークアップすることを想定しています。全てのテーマが、この規約に従うことを推奨します。すると、この規約に従ったテーマでは、タグを気にせずに、簡単にサイドバーを登録することができます。 やむを得ない理由で、このようにマークアップできない場合、サイドバーを登録するときに指定することができます。 id 属性と class 属性を丸ごとコピーし、内部 sprintf が動作し、個々のウィジェットに CSS スタイルが適用されるようにしましょう。

2009年6月24日 (水) 06:31時点における版

この項目「WordPress ウィジェット API」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

ウィジェット API

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

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

Wordpress ウィジェット API は、wp-includes/widgets.php ファイルにあります。(訳注:trac へのリンク --Mizuno 2009年6月17日 (水) 10:45 (UTC))

関数リファレンス

Sidebar Functions
Widget Functions

注意: 今後変更される可能性があるので、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 widget($args, $instance) {
		// outputs the content of the widget
	}

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

	function form($instance) {
		// outputs the options form on admin
	}
}
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 );
        ?>
              <?php echo $before_widget; ?>
                  <?php echo $before_title
                      . $instance['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 検索ウィジェットは、コメントがつけられています。チュートリアルを参考にしてください。ガイドラインをいくつか示します。

  • プラグインがロードされている間は、コードを実行しない。plugins_loaded フックを使用してください。さもないと、未定義関数による致命的エラー、あるいは依存関係のあるプラグインが未ロードなために失敗するでしょう。
  • register_sidebar_widget($name, $callback) を使用して、管理画面インターフェースにウィジェットを追加する。
  • 下記テンプレートに従う。
      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);
  • $before_widget, $after_widget, $before_title, $after_title を消さない。これらは、様々なテーマとの整合性のために必要です。
  • ウィジェットおよびその関数には慎重に命名する。これらは HTML 属性として使用します。同じ HTML 文書に同一の id は好ましくありません。
  • HTML id 属性を保持するために、ローカライゼーションは内部で行う。テキストドメインでウィジェット名をローカライズしたい場合、$name ではなく array($name, $textdomain) を渡します。
  • 複数利用できるウィジェット (テキストや RSS 等) には、名前と置き換え値を渡す。array($name_as_sprintf_pattern, $textdomain, $replacement).ソースを参照してください。
  • 変数を上で述べたのと異なる方法で使用することができる。状況によっては無視することができる。例えば、ウィジェットによっては、タイトルを必要としない等です。ウィジェットによっては、$before_widget と $after_widget を複数回使うでしょう。あるいは他のテンプレートタグに出力を整形する方法を教える引数として使うでしょう。
  • 以下の構文に従うと、管理画面の設定ページを追加することができる。コールバック関数は主フォームで使用されるため、<form> タグや送信ボタンを含めてはいけません。
      register_widget_control($name, $callback [, $width [, $height ]] );
  • 他のウィジェットと衝突しないように、フォーム要素に名前をつける。
  • 各ウィジェットが一意の名前を持つようにする。同名のウィジェットを登録すると、登録済みのウィジェットを置き換えます。
  • register_sidebar_widget() や register_widget_control() の余分な引数は、コールバック関数に渡される。テキストウィジェット、RSS ウィジェットの例を参照してください。
  • 登録関数に空文字列を渡すことで、widget と control を抹消できる。
  • ドキュメント化されていない関数があるかもしれない。ソースコードを読み、標準ウィジェットがどのように作られているかを見ることをお勧めします。
  • Classic と Default (どちらも ul/li/h2 マークアップを採用) 以外のいくつかのテーマでウィジェットを試してみる。
  • ウィジェットのセキュリティをチェックしてから配布する。
  • WordPress.com で使用することを検討してほしい場合は、widgets@wordpress.com までリンクを送信する (ファイル添付ではない)。

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

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

  • 他と差別化するために、特別なウィジェットを含むテーマを作成する。
  • 以下のような特別なウィジェットはどうでしょう。サイドバーでの WordPress ループ。
  • オリジナルウィジェットを記憶し、何らかの方法で変更する置き換えウィジェットを登録する。
  • サイドバーはリストの名前に過ぎないことを理解する。サイドバーは縦でも横でも表示できます。
  • ウィジェットは、コードスニペットの名前に過ぎないことを理解する。ウィジェットを不可視にしたり、絶対配置したりすることもできます。
  • サイドバーを活性化するために、任意/全てのウィジェットで id と class 属性を使用する。
  • script.aculo.us や dbx (WordPress に含まれる) を使用して、ウィジェットをドラッグしたり、折りたたんだりできるようにする。
  • ウィジェットコントロール API は便宜的なものであることを理解する。独自の管理ページを設定することができます。
  • 利用者をサポートし、ウィジェットをよりよくするためのフィードバックを得る。ウィジェットコントロールの末尾にメールアドレスまたはサイトへのリンクを配置しましょう。
  • ウィジェットへのリンクを widgets@wordpress.com に送信して、評価してもらう。WordPress.com で使用できるようにするかもしれません。

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

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

外部資料

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