WordPressでウィジェットを自作する方法

この記事では、DIYユーザーおよび開発者向けにWordPressでウィジェットを自作する方法を解説します。

WordPressでウィジェットを自作する手順

WordPressでウィジェットを自作する流れは、次のようになります。

1. WP_Widgetクラスを拡張したクラスを作成する
2. 1で作成したクラスをregister_widget関数で登録する

詳しく解説していきます。

WordPressでウィジェットを自作する基本的な方法

WordPressでウィジェットを自作するために最低限必要な方法を解説していきます。

まずは手順で示したように、WP_Widgetクラスを拡張したクラスを作成し、register_widget関数で作成したクラスを登録します。

WP_Widgetクラスを拡張したクラスでは、次の4つのメソッドの定義を行います。

• __construct()：ウィジェットIDの登録や説明を記載する
• widget：フロントエンドの表示用
• form：バックエンド（管理画面）用
• update：バックエンド（管理画面）で変更を行った際の更新処理

クラス作成とメソッドの定義のみを行うと、次のコードになります。

// ウィジェットの作成 
class foxwp_widget extends WP_Widget {
 
    // コンストラクタの実装部分
    function __construct() {
         
    }
  
    // フロントエンドの実装部分
    public function widget( $args, $instance ) {
        
    }
          
    // バックエンド（管理画面）の実装部分 
    public function form( $instance ) {
         
    }
      
    // 更新処理の実装部分（バックエンド（管理画面）でウィジェットの設定変更が行われた際）
    public function update( $new_instance, $old_instance ) {
     
    }
 
}

register_widget関数で、上記で作成したウィジェットの登録を行います。

function register_foxwp_widget() {
    register_widget( 'foxwp_widget' );
}
add_action( 'widgets_init', 'register_foxwpy_widget' );

以上がウィジェットを自作する基本となります。

ここからは各処理に分けて、詳しく見ていきます。

コンストラクタの実装

コンストラクタでは、「ウィジェットのベースID」「管理画面のウィジェットの表示名」「管理画面で表示されるウィジェットの説明」を実装します。

WP_Widgetクラスのコンストラクタは次のように定義されています。

__construct( mixed|string $id_base, string $name, array $widget_options = array(), array $control_options = array() )

• $id_base・・・ウィジェットのベースID
• $name・・・管理画面のウィジェットの表示名
• $widget_options配列のdescription・・・「管理画面で表示されるウィジェットの説明」

これらの値を入れていきます。

function __construct() {
    parent::__construct(
  
        // ウィジェットのベースID
        'foxwp_widget', 
  
        // ウィジェットの表示名
        'FOXWP Widget', 
  
        // ウィジェットの説明
        array( 'description' => '自作ウィジェットのサンプル', ) 
    );
}

多言語化したい場合、表示名やウィジェットの説明には、ローカライズを行うための__関数が使用されます。

function __construct() {
    parent::__construct(
  
        // ウィジェットのベースID
        'foxwp_widget', 
  
        // ウィジェットの表示名
        __('FOXWP Widget', 'foxwp_widget'),
  
        // ウィジェットの説明
        array( 'description' => __('自作ウィジェットのサンプル', 'foxwp_widget'), ) 
    );
}

以上が__constructの実装の基本となります。

フロントエンドの実装

フロントエンドの実装では、サイトを訪れたユーザーが目にする部分を実装します。

widget関数は次のように定義されています。

widget( array $args, array $instance)

まずwidget関数で使用される引数について、解説します。

$argsには、次の4つの値が含まれています。

• before_title・・・ウィジェットのタイトルの前に表示するコード
• after_title・・・ウィジェットのタイトルの後に表示するコード
• before_widget・・・ウィジェットの前に表示するコード
• after_widget・・・ウィジェットの後に表示するコード

$argsに含まれる値は、テーマによって異なります。

これらの値は基本的に、次のように使うことになります。

echo $args['before_widget'];
echo $args['before_title'] . 'タイトル' . $args['after_title'];
echo '表示したい内容';
echo $args['after_widget'];

そして、$instanceには、ウィジェットの設定内容の値が含まれています。

実装は次のようになります。

任意のタイトル及び固定の文章を表示する場合は、次のような実装となります。

public function widget( $args, $instance ) {
    $title = apply_filters( 'widget_title', $instance['title'] );
  
    echo $args['before_widget'];
    if ( ! empty( $title ) ) echo $args['before_title'] . $title . $args['after_title'];
    echo 'ウィジェットサンプル';
    echo $args['after_widget'];
}

バックエンドの実装

バックエンドの実装では、管理画面のウィジェットメニューでどのような項目を変更可能か指定できるように実装を行います。

form関数の定義は次のようになっています。

form( array $instance )

引数$instanceには、設定内容の値が含まれています。

バックエンドの設定値は、labelとinputなどのユーザーからデータを受け取るためのHTML要素を組み合わせて行います。

form要素は自動的に生成されるので、form関数での実装は不要です。

public function form( $instance ) {
    $title = isset( $instance[ 'title' ] ) ? $instance['title'] : '';

    ?>
    <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
}

_e関数は__関数と同じようにローカライズで使用される関数です。_e関数は、値を保持せずにすぐに出力したい場合に使用します。

更新処理の実装

update関数では、古い設定値を新しい設定値に更新する処理を行います。

また入力項目のバリデーションや無害化を行います。

public function update( $new_instance, $old_instance ) {
   $instance = $old_instance;
   $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? sanitize_text_field( $new_instance['title'] ) : '';
   return $instance;
}

ウィジェットの登録

function.phpなどに作成したウィジェットクラス及びregsster_widget関数での登録を記載します。

class foxwp_widget extends WP_Widget {

    function __construct() {
        parent::__construct(
            
            // ウィジェットのベースID
            'foxwp_widget', 
           
            // ウィジェットの表示名
            __('FOXWP Widget', 'foxwp_widget'),
           
            // ウィジェットの説明
            array( 'description' => __('自作ウィジェットのサンプル', 'foxwp_widget'), ) 
        );
    }

    public function widget( $args, $instance ) {
        $title = apply_filters( 'widget_title', $instance['title'] );
       
        echo $args['before_widget'];
        if ( ! empty( $title ) ) echo $args['before_title'] . $title . $args['after_title'];
        echo 'ウィジェットサンプル';
        echo $args['after_widget'];
    }

    public function form( $instance ) {
        $title = isset( $instance[ 'title' ] ) ? $instance['title'] : '';
     
        ?>
        <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
    }

    public function update( $new_instance, $old_instance ) {
       $instance = $old_instance;
       $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? sanitize_text_field( $new_instance['title'] ) : '';
       return $instance;
    }

}

function register_foxwp_widget() {
    register_widget( 'foxwp_widget' );
}
add_action( 'widgets_init', 'register_foxwpy_widget' );

参考：
https://developer.wordpress.org/reference/classes/wp_widget/
http://wpdocs.osdn.jp/WordPress_ウィジェット_API