get_search_form()を使った検索フォームの設置やカスタマイズの方法

投稿日 :

2024年5月4日

2024年5月10日

カテゴリー : WordPress

タグ : General Template Tag, WordPress functions

WordPress では簡単にサイト内検索フォームを設置することができます。それを実現してくれるのが get_search_form() 関数です。ポンと設置すればフォームを出力してくれる便利な関数なのですが、ちょっとコードを書くだけでカスタマイズも簡単にできるようになっています。

この記事では、その get_search_form() 関数について紹介していきます。

get_search_form() 関数とは

検索フォームを出力する関数です。

動作としては、まずテーマの中に searchform.php ファイルがあるか探して読み込もうとします。ない場合には WordPress 側が用意しているデフォルトの検索フォームが表示されます。

検索フォームを編集したり置き換えたりするためのフック get_search_form も用意されています。こちらを含むフックについては後述します。

この関数は主に、検索フォームをサイドバーにハードコーディングしたい場合や、WordPress の検索ウィジェットで使用されます。

この関数が実行されるたびに pre_get_search_form というフックが呼び出されます。これは検索が依存する JavaScript や、検索の最初に適応されるさまざまなフォーマットを出力するのに便利です。

パラメーター

$args

表示のために引数が配列で入ります。

`echo`	表示するかどうか `true` or `false` デフォルトは `true`
`aria_label`	検索フォームの `aria-label` を指定できる。検索フォームによって変えることでページ内に複数フォームがある場合に、アクセシビリティを向上させることが期待できる。

使い方

基本的な使い方

基本的な使い方としては、テンプレートにそのまま記述する方法です。

get_search_form();

これだけで検索フォームが表示されます。

しかし、add_theme_support() にて HTML5 フォーマットの指定をしている場合とそうでない場合では出力される検索フォームのソースコードに違いが見られます。

wp-includes/general-template.php 291行あたりで current_theme_support() にて search-form に html5 を指定しているかどうかを確認しています。その後、その値を格納した $format を使って 324行あたりで出力するフォームのソースコードを分岐していることが確認できます。

通常のフォームのソースコードは、このようなコードになります。（WordPress 6.5.2 の場合）

<form role="search" method="get" id="searchform" class="searchform" action="http://wordpress-dev.wp/">
	<div>
		<label class="screen-reader-text" for="s">検索:</label>
		<input type="text" value="" name="s" id="s">
		<input type="submit" id="searchsubmit" value="検索">
	</div>
</form>

そして、HTML5 フォーマットを指定している場合には、以下のようなコードになります。（WordPress 6.5.2 の場合）

<form role="search" method="get" class="search-form" action="http://wordpress-dev.wp/">
	<label>
		<span class="screen-reader-text">検索:</span>
		<input type="search" class="search-field" placeholder="検索…" value="" name="s">
	</label>
	<input type="submit" class="search-submit" value="検索">
</form>

searchform.php を用意して出力ソースコードを意図したものにする

テーマ内に searchform.php というファイルを用意することで、get_search_form() を設置した際に出力する検索フォームのソースコードを意図したものにすることができます。

この searchform.php ファイルを用意する場合、前述している add_theme_support() での HTML5 フォーマットの指定は利用できません。

例えば、WordPress 標準テーマ Twenty Twenty-One では searchform.php ファイルが用意されており、以下のようなソースコードになっています。

$twentytwentyone_unique_id = wp_unique_id( 'search-form-' );

$twentytwentyone_aria_label = ! empty( $args['aria_label'] ) ? 'aria-label="' . esc_attr( $args['aria_label'] ) . '"' : '';
?>
<form role="search" <?php echo $twentytwentyone_aria_label; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Escaped above. ?> method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
	<label for="<?php echo esc_attr( $twentytwentyone_unique_id ); ?>"><?php _e( 'Search…', 'twentytwentyone' ); // phpcs:ignore: WordPress.Security.EscapeOutput.UnsafePrintingFunction -- core trusts translations ?></label>
	<input type="search" id="<?php echo esc_attr( $twentytwentyone_unique_id ); ?>" class="search-field" value="<?php echo get_search_query(); ?>" name="s" />
	<input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button', 'twentytwentyone' ); ?>" />
</form>

ちなみに、その１つ前の標準テーマ Twenty Twenty では以下のようになっています。

$unique_id = twentytwenty_unique_id( 'search-form-' );

$aria_label = ! empty( $args['label'] ) ? 'aria-label="' . esc_attr( $args['label'] ) . '"' : '';
?>
<form role="search" <?php echo $aria_label; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Escaped above. ?> method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
	<label for="<?php echo esc_attr( $unique_id ); ?>">
		<span class="screen-reader-text"><?php _e( 'Search for:', 'twentytwenty' ); // phpcs:ignore: WordPress.Security.EscapeOutput.UnsafePrintingFunction -- core trusts translations ?></span>
		<input type="search" id="<?php echo esc_attr( $unique_id ); ?>" class="search-field" placeholder="<?php echo esc_attr_x( 'Search …', 'placeholder', 'twentytwenty' ); ?>" value="<?php echo get_search_query(); ?>" name="s" />
	</label>
	<input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button', 'twentytwenty' ); ?>" />
</form>

<label> の使い方が若干違うのがぱっと見でわかりますね。

このように searchform.php ファイルを用意することで簡単に WordPress が提供する検索フォームのソースコードを上書きすることができてしまいます。

しかし、乱暴な言い方をすると改悪できてしまうとも言えます。WordPress が出力するソースコードはアクセシビリティなども確保されたものになっていることが多く、ソースコードがそのようになっているのには理由があります。

そこを上書きして独自のものを導入するのであれば、それ以上の理由や利用しやすさ、そして当然ですが最低限のアクセシビリティも確保したものにするべきでしょう。

フック

get_search_form

apply_filters( ‘get_search_form’, string $form, array $args )

検索フォームの HTML アウトプットをフィルターします。

以下のようなソースコードで実験することができます。

add_filter(
	'get_search_form',
	function( $form, $args ) {
		echo '<hr>' . basename(__FILE__) . ' :: ' . __LINE__;
		echo( '<pre>' );
		var_dump( $form );
		echo( '</pre>' );
		echo '<hr>';
	},
	10,
	2
);

pre_get_search_form

do_action( ‘pre_get_search_form’, array $args )

検索フォームが始まる前に発火するアクションフックです。

以下のようなソースコードで実験することができます。

add_action(
	'pre_get_search_form',
	function() {
		echo "<p>検索フォームの前に出力されます</p>";
	}
);

search_form_args

apply_filters( ‘search_form_args’, array $args )

検索フォームを生成する際に使用する引数の配列にフィルターします。

以下のようなコードで実験することができます。

add_filter(
	'search_form_args',
	function ( $args ) {
		echo '<hr>' . basename(__FILE__) . ' :: ' . __LINE__;
		echo( '<pre>' );
		var_dump( $args );
		echo( '</pre>' );
		echo '<hr>';
	},
	10,
	1
);

出力結果としては、

array(2) {
  ["echo"]=>
  bool(true)
  ["aria_label"]=>
  string(0) ""
}

のようになります。

search_form_format

apply_filters( ‘search_form_format’, string $format, array $args )

検索フォームの HTML 形式をフィルターします。

以下のようなソースコードで実験できます。

add_filter(
	'search_form_format',
	function ( $format, $args ) {
		echo '<hr>' . basename(__FILE__) . ' :: ' . __LINE__;
		echo( '<pre>' );
		var_dump( $format );
		echo( '</pre>' );
		echo '<hr>';
	},
	10,
	2
);

このソースコードの実行例としては以下のようになります。