全てのウィジェットにプロパティを追加するフック

最近プラグイン「Bogo」に学んで、テーマ「ShapeShifter」でもウィジェットの出力条件を指定するプロパティを全てのウィジェットに設置したのですが、その方法について紹介します。

プロパティがある程度汎用的なことに限られるとは思いますが、非常に便利なフックで、ウィジェットの背景などにも使用できます。ただ、全てのウィジェットに追加する項目ですので、汎用性の高いプロパティを選ぶべきでしょう。

個人的にオススメなのは、「Mobile_Detect」などと組み合わせた出力条件です。

フックは基本的な「レンダー」「保存」「フォーム」の３箇所で呼び出されるものを使用します。

アクションフック「in_widget_form」

ウィジェットの設定フォームの最後に呼び出されるアクションフックです。

INPUTタグ等を出力し、設定項目を追加します。

add_action( 'in_widget_form', 'your_settings_in_widget_form', 10, 3 );
function your_settings_in_widget_form( $widget, $return, $instance ) {

  // フォーム内に出力する

}

ちょっと変数名で注意スべき点があります。

「$widget」がフォームに追加される時のウィジェットのインスタンス（WP_Widget）で、「$instance」が保存された設定を持つ配列となっています。

ちょっと紛らわしいですよね。

フィルターフック「widget_update_callback」

こちらはフィルターフックですので、保存するデータの配列を返す必要があります。

フィルターが使用されるタイミングは設定の保存前ですので、アクションフックで追加した設定項目などを保存するのに使用します。

add_filter( 'widget_update_callback', 'your_widget_update_callback', 10, 4 );
function your_widget_update_callback( $instance, $new_instance, $old_instance, $widget ) {
  
  $instance[ 'settings_name' ] = sanitize_text_field( $new_instance[ 'settings_name' ] );

  return $instance;

}

例ではサニタイズに「sanitize_text_field」を使用していますが、追加する設定項目で保存するデータに合わせてください。

受け取れる変数の注意点は、「$old_instance」は保存前のデータで、「$instance」は現在の設定となります。つまり、「$instance」は各ウィジェットのメソッドにより設定項目が変数に格納された後、そして、データベースに保存される直前ですので、「$old_instance」や「$new_instance」と混同しないようにしましょう。

あとは、保存したい変数を返すだけOKです。

アクションフック「the_widget」

これはウィジェットがレンダーされる前に呼び出されるアクションフックです。

ウィジェットのメソッド「the_widget」が受け取れる変数の他、ウィジェットのインスタンス「$widget」も受け取ることが出来ます。

add_action( 'the_widget', 'your_widgets', 10, 3 );
function your_widgets( $widget, $instance, $args ) {

  // ウィジェットが出力する前の処理

}

ええ、これで出力する前に何かしらの処理を行ったり、出力することができます。

「return」してしまえば、非表示にすることも出来ます。

別に出力条件に限りません。

データの処理をしたりJavaScriptの変数を用意したり出来ます。

フィルターフック「widget_display_callback」

こちらは「return」せず、ウィジェットを非アクティブにするなどできるフィルターフックで、「the_widget」によりウィジェットが出力される前に呼び出され、「$instance」を編集することが出来ます。

テーマ「ShapeShifter」でもこちらのフィルターフックを使用しているのですが、返す値を「$instance」ではなく「false」にしてしまうと、ウィジェットが出力されなくなりますので、それを利用しています。

add_filter( 'widget_display_callback', 'your_widget_display_callback', 10, 3 );
function your_widget_display_callback( $instance, $widget, $args ) {

  if( $some_condition_not_to_display ) { // 非表示条件
    return false;
  }

  return $instance;

}

この他、「$instance」を返しますので、何かしらのデータ編集を行うのもありです。

追加した設定項目に応じて使用してください。