• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(言語間リンク・原文リンク挿入、リンク調整等、未翻訳)
(翻訳完了)
1行目: 1行目:
{{NeedTrans}}
+
{{CheckTrans}}
==Widgets API==
+
==ウィジェット API==
This page contains the technical documentation of the WordPress Widgets API (Application Programming Interface). The intended audience for this information includes WordPress theme authors, plug-in authors and anyone who would like to write a stand-alone widget. This document assumes a basic understanding of PHP scripting.
+
このページは、WordPress ウィジェット API (アプリケーションプログラミングインターフェース) についての技術文書です。この文書の想定する読者は、WordPress テーマ作成者、プラグイン作成者、およびスタンドアロンのウィジェットを作りたい方全てです。この文書では、PHP スクリプトの基礎知識を前提としています。
  
A widget is a [http://www.php.net/manual/ja/language.functions.php PHP function] that echoes string data to STDOUT when called. To turn such a PHP function into a Wordpress Widget it must be registered as such. This is done using a [http://www.php.net/manual/ja/language.pseudo-types.php PHP callback] (a ''Pseudo-Type'' in PHP documentation) that is registered by a wordpress widget API function.
+
ウィジェットは、呼び出されたときに文字列データを STDOUT に出力する [http://www.php.net/manual/en/language.functions.php PHP 関数] です。PHP 関数を WordPress ウィジェットにするには、以下のようにして登録します。WordPress ウィジェット API 関数が登録する [http://www.php.net/manual/en/language.pseudo-types.php PHP コールバック] (PHP ドキュメントの 擬似タイプ) を用います。
  
 
register_sidebar_widget($callback);
 
register_sidebar_widget($callback);
  
The Wordpress widget API is located in ''wp-includes/widgets.php''. It is advised to '''not''' use the functions starting with ''wp_'' as these could change in subsequent releases. This is why we use register_sidebar_widget() instead of wp_register_sidebar_widget().
+
Wordpress ウィジェット API は、''wp-includes/widgets.php'' ファイルにあります。今後変更される可能性があるので、''wp_'' で始まる関数は、使うべきでありません。このため、wp_register_sidebar_widget() ではなく、register_sidebar_widget() を使用します。
  
 
<div id="Function_Reference">
 
<div id="Function_Reference">
== Function Reference ==
+
== 関数リファレンス ==
 
</div>
 
</div>
  
45行目: 45行目:
  
 
|}
 
|}
== Developing New Widgets (2.8 and up) ==
+
== ウィジェットの新規作成 (2.8 以降) ==
 +
[[Version 2.8|version 2.8]] から、ウィジェットの作成が簡単になりました。ウィジェットを作るには、標準ウィジェットクラスとこのクラスのいくつかのメソッドを継承すれば良いのです。
  
Widget development has become easier since [[Version 2.8|version 2.8]]. To create a widget, you only need to extend the standard widget class and some of it's functions.
+
基底クラスでは、動作するウィジェットで継承すべきメソッドについての情報も記述されています。
  
That base class also contains information about the function that must be extended to get a working widget.
+
サンプルコードは、表示タイトルを変更する設定フォームを持つ ''FooWidget'' という名前のウィジェットを作成します。
 
+
This sample code creates a Widget named ''FooWidget'' that has a settings form to change the display title.
+
  
 
<pre>
 
<pre>
92行目: 91行目:
 
</pre>
 
</pre>
  
This sample widget can then be registered in the ''widgets_init'' hook:
+
このサンプルウィジェットは、''widgets_init'' フックで登録することができます。
  
 
<pre>
 
<pre>
99行目: 98行目:
 
</pre>
 
</pre>
  
That's all. You will automatically get a multi-widget. No special tweaks needed any longer for that.
+
これで終わりです。複数のウィジェットも自動生成されます。複数のウィジェットのための調整は不要です。
  
More information is available in the [[Version 2.8#New_Widgets_API|version information]].
+
詳細は [[Version 2.8#New_Widgets_API|新ウィジェット API]] を参照してください。
  
 
<div id="Developing_New_Widgets">
 
<div id="Developing_New_Widgets">
== Developing New Widgets ==
+
== ウィジェットの新規作成 ==
 
</div>
 
</div>
  
The Google Search widget which was included in the deprecated (i.e. not needed since WordPress 2.2) [http://downloads.wordpress.org/plugin/widgets.zip original widget plugin] is commented within inches of its life, so consider that your tutorial. Additionally, there are a few guidelines to follow:
+
古い (WordPress 2.2 以降では不要の) [http://downloads.wordpress.org/plugin/widgets.zip オリジナルウィジェットプラグイン] に含まれている Google 検索ウィジェットは、コメントがつけられています。チュートリアルを参考にしてください。ガイドラインをいくつか示します。
  
* Don’t execute any code while the plugin is being loaded. Use the plugins_loaded hook or you risk fatal errors due to undefined functions, or missing the boat completely because your plugin loaded before the one it depends on.
+
* プラグインがロードされている間は、コードを実行しない。plugins_loaded フックを使用してください。さもないと、未定義関数による致命的エラー、あるいは依存関係のあるプラグインが未ロードなために失敗するでしょう。
* Use register_sidebar_widget($name, $callback) to add your widget to the admin interface.
+
* register_sidebar_widget($name, $callback) を使用して、管理画面インターフェースにウィジェットを追加する。
* Follow this template:
+
* 下記テンプレートに従う。
  
 
<pre>
 
<pre>
129行目: 128行目:
 
</pre>
 
</pre>
  
'''Important''': To use the above in a plugin, wrap it with:
+
'''重要''':上記テンプレートをプラグインとして使用するには、以下で囲んでください。
  
 
  function widget_myuniquewidget_register() {
 
  function widget_myuniquewidget_register() {
136行目: 135行目:
 
  add_action('init', widget_myuniquewidget_register);
 
  add_action('init', widget_myuniquewidget_register);
  
* Don’t leave out $before_widget, $after_widget, $before_title, or $after_title by accident. They are required for compatibility with various themes.
+
* $before_widget, $after_widget, $before_title, $after_title を消さない。これらは、様々なテーマとの整合性のために必要です。
* Name your widget and its functions carefully. Those strings will be used as HTML attributes and you don’t want to cause identical id’s in a single HTML document.
+
* ウィジェットおよびその関数には慎重に命名する。これらは HTML 属性として使用します。同じ HTML 文書に同一の id は好ましくありません。
* Localization is done internally to preserve the HTML id attribute. If you want your widget name localized with a textdomain, pass array($name, $textdomain) instead of $name.
+
* HTML id 属性を保持するために、ローカライゼーションは内部で行う。テキストドメインでウィジェット名をローカライズしたい場合、$name ではなく array($name, $textdomain) を渡します。
* To accommodate multi-widgets (e.g. Text and RSS) you can also pass a replacement value with the name: array($name_as_sprintf_pattern, $textdomain, $replacement). See the source.
+
* 複数利用できるウィジェット (テキストや RSS ) には、名前と置き換え値を渡す。array($name_as_sprintf_pattern, $textdomain, $replacement).ソースを参照してください。
* You may use the variables mentioned above in different ways, or neglect them in some circumstances. Some widgets may not need a title, for example. Some widgets will use the $before_widget and $after_widget several times, or as arguments to tell another template tag how to format its output.
+
* 変数を上で述べたのと異なる方法で使用することができる。状況によっては無視することができる。例えば、ウィジェットによっては、タイトルを必要としない等です。ウィジェットによっては、$before_widget $after_widget を複数回使うでしょう。あるいは他のテンプレートタグに出力を整形する方法を教える引数として使うでしょう。
* Optionally, use the following syntax to add a configuration page to the admin. Your callback will be used within the main form, so you must not include any <form> tags or a form submit button.
+
* 以下の構文に従うと、管理画面の設定ページを追加することができる。コールバック関数は主フォームで使用されるため、<form> タグや送信ボタンを含めてはいけません。
  
 
<pre>
 
<pre>
147行目: 146行目:
 
</pre>
 
</pre>
  
* Namespace your form elements so they don’t conflict with other widgets.
+
* 他のウィジェットと衝突しないように、フォーム要素に名前をつける。
* Each widget must have a unique name. You can replace an already-registered widget by registering another one with the same name, supplying your own callback.
+
* 各ウィジェットが一意の名前を持つようにする。同名のウィジェットを登録すると、登録済みのウィジェットを置き換えます。
* Any extra arguments to register_sidebar_widget() or register_widget_control() will be passed to your callback. See the Text and RSS widgets for examples.
+
* register_sidebar_widget() register_widget_control() の余分な引数は、コールバック関数に渡される。テキストウィジェット、RSS ウィジェットの例を参照してください。
* Any widget or control can be “unregistered” by passing an empty string to the registration function.
+
* 登録関数に空文字列を渡すことで、widget と control を抹消できる。
* There are probably some undocumented functions. You are encouraged to read the source code and see how we’ve created the standard widgets using these functions.
+
* ドキュメント化されていない関数があるかもしれない。ソースコードを読み、標準ウィジェットがどのように作られているかを見ることをお勧めします。
* Please test your widgets with several themes other than Classic and Default (they both use the ul/li/h2 markup).
+
* Classic Default (どちらも ul/li/h2 マークアップを採用) 以外のいくつかのテーマでウィジェットを試してみる。
* Please audit the security of your widgets before distributing them.
+
* ウィジェットのセキュリティをチェックしてから配布する。
* If you would like your widget to be considered for use on WordPress.com, send a link (no attachments please) to widgets@wordpress.com and we’ll have a look.
+
* WordPress.com で使用することを検討してほしい場合は、widgets@wordpress.com までリンクを送信する (ファイル添付ではない)。
  
==What else can I do with Widgets?==
+
==他にウィジェットでできる事は?==
  
You have no idea how glad we are that you asked that. Here are a few ideas:
+
このような質問は非常に嬉しいです。いくつかのアイデアを紹介します。
  
* Write a theme that includes a special widget to set it apart from the others.
+
* 他と差別化するために、特別なウィジェットを含むテーマを作成する。
* How about this for a special widget: a WordPress loop to show asides.
+
* 以下のような特別なウィジェットはどうでしょう。サイドバーでの WordPress ループ。
* Register a replacement widget that buffers the original widget and transforms it somehow.
+
* オリジナルウィジェットを記憶し、何らかの方法で変更する置き換えウィジェットを登録する。
* Remember that a “sidebar” is really just a name for a list. It can be displayed vertically or horizontally.
+
* サイドバーはリストの名前に過ぎないことを理解する。サイドバーは縦でも横でも表示できます。
* Remember that a “widget” is really just a name for a configurable code snippet. It can be invisible or it can be absolutely positioned.
+
* ウィジェットは、コードスニペットの名前に過ぎないことを理解する。ウィジェットを不可視にしたり、絶対配置したりすることもできます。
* Use the id and class attributes of any or all widgets in scripts to animate your sidebar.
+
* サイドバーを活性化するために、任意/全てのウィジェットで id class 属性を使用する。
* Heck, use script.aculo.us or dbx (included with WordPress) to make your widgets draggable or even collapsible. Ain’t scripting sweet?
+
* script.aculo.us dbx (WordPress に含まれる) を使用して、ウィジェットをドラッグしたり、折りたたんだりできるようにする。すごいでしょう?
* Remember that the widget control API is just for convenience. You can always set up your own admin page instead.
+
* ウィジェットコントロール API は便宜的なものであることを理解する。独自の管理ページを設定することができます。
* Support your users and get feedback so you can improve your widget. Put a link to your email or your site at the bottom of your widget control.
+
* 利用者をサポートし、ウィジェットをよりよくするためのフィードバックを得る。ウィジェットコントロールの末尾にメールアドレスまたはサイトへのリンクを配置しましょう。
* Send a link to your widgets to widgets@wordpress.com for review. We might put them up for everyone to use on WordPress.com. You could be internet famous!
+
* ウィジェットへのリンクを widgets@wordpress.com に送信して、評価してもらう。WordPress.com で使用できるようにするかもしれません。ネット上で有名人になれるかもしれませんよ。
  
 
<div id="Widgets_-_One_or_many">
 
<div id="Widgets_-_One_or_many">
== Widgets - One or many ==
+
== ウィジェット - 1 つか複数か ==
 
</div>
 
</div>
Widgets can be coded so that they can exist one time or they can exist multiple times. Wordpress is doing the work for you to instantiate your Widget multiple times if you follow some rules.
+
ウィジェットは、1 度に 1 つだけ、あるいは1 度に複数可能にコーディングすることができます。いくつかのルールに従うと、ウィジェットを複数回使用するための作業を WordPress が行ってくれます。
  
You can find a tutorial [http://brainfart.com.ua/post/lesson-wordpress-multi-widgets/ here].
+
詳しくは [http://brainfart.com.ua/post/lesson-wordpress-multi-widgets/ ここ] を参照してください。
  
 
{{原文|Plugins/WordPress Widgets Api|72702}}<!-- 11:04, May 26, 2009 Sipsniffa 版 -->
 
{{原文|Plugins/WordPress Widgets Api|72702}}<!-- 11:04, May 26, 2009 Sipsniffa 版 -->

2009年5月30日 (土) 16:35時点における版

この項目「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最新版との差分