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

WordPress ウィジェット API

提供: WordPress Codex 日本語版
2009年5月30日 (土) 16:35時点におけるMizuno (トーク | 投稿記録)による版 (翻訳完了)

移動先: 案内検索

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

ウィジェット API

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

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

register_sidebar_widget($callback);

Wordpress ウィジェット API は、wp-includes/widgets.php ファイルにあります。今後変更される可能性があるので、wp_ で始まる関数は、使うべきでありません。このため、wp_register_sidebar_widget() ではなく、register_sidebar_widget() を使用します。

関数リファレンス

Sidebar Functions
Widget Functions

ウィジェットの新規作成 (2.8 以降)

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

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

サンプルコードは、表示タイトルを変更する設定フォームを持つ 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最新版との差分