万が一、当サイトで重大な問題を発見した際などは、フォーラムや WordSlack #docs チャンネルでお知らせください。</p>
WordPress ウィジェット API
目次
ウィジェット API
このページは開発者向けの WordPress ウィジェット API 技術文書です。一般のユーザー向けには「 ウィジェット」ページを参照してください。
技術的に言えば、WordPress ウィジェットは widget() メソッドが呼ばれると文字列データを STDOUT に出力する PHP オブジェクトです。ソースコードは wp-includes/widgets.php にあります。
関数リファレンス
|
|
ウィジェットの開発
ウィジェットの開発は標準の WP_Widget クラスといくつかの関数を拡張するだけで済みます。
基底クラスには、ウィジェットとして動作するには拡張する必要のある関数の情報が含まれています。
WP_Widget クラスは wp-includes/widgets.php にあります。
標準的な使い方
class My_Widget extends WP_Widget {
/**
* ウィジェット名などを設定
*/
public function __construct() {
// widget actual processes
}
/**
* ウィジェットの内容を出力
*
* @param array $args
* @param array $instance
*/
public function widget( $args, $instance ) {
// outputs the content of the widget
}
/**
* 管理用のオプションのフォームを出力
*
* @param array $instance ウィジェットオプション
*/
public function form( $instance ) {
// 管理用のオプションのフォームを出力
}
/**
* ウィジェットオプションの保存処理
*
* @param array $new_instance 新しいオプション
* @param array $old_instance 以前のオプション
*/
public function update( $new_instance, $old_instance ) {
// ウィジェットオプションの保存処理
}
}
ウィジェットは、'widgets_init' フックを使用してで登録できます。
PHP 5.3+ 以上:
add_action( 'widgets_init', function(){
register_widget( 'My_Widget' );
});
PHP 5.2+:
add_action('widgets_init',
create_function('', 'return register_widget("My_Widget");')
);
ウィジェットの例
サンプルコードは、表示タイトルを変更する設定フォームを持つ Foo_Widget という名前のウィジェットを作成します。
/**
* Adds Foo_Widget widget.
*/
class Foo_Widget extends WP_Widget {
/**
* WordPress でウィジェットを登録
*/
function __construct() {
parent::__construct(
'foo_widget', // Base ID
__( 'ウィジェットのタイトル', 'text_domain' ), // Name
array( 'description' => __( 'サンプルのウィジェット「Foo Widget」です。', 'text_domain' ), ) // Args
);
}
/**
* ウィジェットのフロントエンド表示
*
* @see WP_Widget::widget()
*
* @param array $args ウィジェットの引数
* @param array $instance データベースの保存値
*/
public function widget( $args, $instance ) {
echo $args['before_widget'];
if ( ! empty( $instance['title'] ) ) {
echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ). $args['after_title'];
}
echo __( '世界のみなさん、こんにちは', 'text_domain' );
echo $args['after_widget'];
}
/**
* バックエンドのウィジェットフォーム
*
* @see WP_Widget::form()
*
* @param array $instance データベースからの前回保存された値
*/
public function form( $instance ) {
$title = ! empty( $instance['title'] ) ? $instance['title'] : __( '新しいタイトル', 'text_domain' );
?>
<p>
<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'タイトル:' ); ?></label>
<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>">
</p>
<?php
}
/**
* ウィジェットフォームの値を保存用にサニタイズ
*
* @see WP_Widget::update()
*
* @param array $new_instance 保存用に送信された値
* @param array $old_instance データベースからの以前保存された値
*
* @return array 保存される更新された安全な値
*/
public function update( $new_instance, $old_instance ) {
$instance = array();
$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
return $instance;
}
} // class Foo_Widget
このサンプルウィジェットは、'widgets_init' フックで登録することができます。
// Foo_Widget ウィジェットを登録
function register_foo_widget() {
register_widget( 'Foo_Widget' );
}
add_action( 'widgets_init', 'register_foo_widget' );
注意 : フォーム要素の名前と ID を生成するには get_field_name() および get_field_id() 関数を使用する必要があります。
名前空間を使用する例
PHP 5.3 の名前空間を使用する場合、コンストラクタは直接、以下の例のように呼び出してください。
namespace a\b\c;
class My_Widget_Class extends \WP_Widget {
function __construct() {
parent::__construct( 'baseID', 'name' );
}
// ... 残りのコード
}
そして register_widget() を呼び出します。
add_action( 'widgets_init', function(){
register_widget( 'a\b\c\My_Widget_Class' );
});
(参照: http://stackoverflow.com/questions/5247302/php-namespace-5-3-and-wordpress-widget/5247436#5247436)
これで終わりです。複数のウィジェットも自動生成されます。複数のウィジェットのための調整は不要です。
詳細は「Version 2.8 の新しいウィジェット API」を参照してください。
ウィジェットとウィジェットエリアの表示
ウィジェットの表示には少なくとも 3つの方法があります。
ウィジェットエリア
最初の、もっとも一般的な方法は希望の ウィジェット を ウィジェットエリア に追加する方法です。管理画面の Appearance -> Widgets から実行できます。
WordPress にはそれぞれ一意の識別子をもつ事前に定義されたウィジェットエリアがあります。識別子を知るには ウィジェットを表示するページのソースを参照してください。ウィジェトエリアを表示するにはこの識別子が必要です。事前に定義されたウィジェットエリアでは十分でない場合、 カスタムウィジェットエリア を 登録 できます。
希望の場所にウィジェットエリアを表示するには、該当するテーマファイルに次のコードを挿入します。
<?php if ( dynamic_sidebar('example_widget_area_name') ) : else : endif; ?>
ウィジェットエリアに追加されたすべてのウィジェットを表示します。
アクテイブ時にウィジェットエリアを表示する
次のコードは Twenty Fourteen テーマの sidebar.php ファイルのコードです。
<?php if ( is_active_sidebar( 'sidebar-1' ) ) : ?> <div id="primary-sidebar" class="primary-sidebar widget-area" role="complementary"> <?php dynamic_sidebar( 'sidebar-1' ); ?> </div><!-- #primary-sidebar --> <?php endif; ?>
新しいウィジェットエリアがあるかどうかを確認し、なければ実行されません。
独立したウィジェット
2番目の、より技術的なウィジェットの表示方法は the_widget メソッドを使用する方法です。
Tags: ウィジェットの表示方法、ウィジェットエリアの表示方法
外部資料
- Deprecating PHP4 style constructors in WordPress 4.3. WordPress 4.3 では PHP4 スタイルのコンストラクタが非推奨
- Notice: The called constructor method for WP_Widget is deprecated since version 4.3.0! Use __construct() 古い WP_Widget 呼び出しが非推奨となったことを伝える記事。代わりに __construct() を使用する。
- WordPress Sidebar Generator
関連
ウィジェット API: is_active_widget(), the_widget(), register_widget(), unregister_widget() / en, wp_register_widget_control() / en, wp_unregister_widget_control() / en, wp_convert_widget_settings() / en, wp_get_widget_defaults() / en, wp_widget_description() / en
最新英語版： WordPress Codex » Widgets API （最新版との差分）
