テンプレートタグ/wp dropdown categories

説明

送信ボタンのないセレクトボックス（ドロップダウンメニューなど）を使ったカテゴリーリストを表示します。

使い方

<?php wp_dropdown_categories( $args ); ?>

デフォルトの使い方

<?php $args = array(
	'show_option_all'    => '',
	'show_option_none'   => '',
	'option_none_value'  => '-1',
	'orderby'            => 'ID', 
	'order'              => 'ASC',
	'show_count'         => 0,
	'hide_empty'         => 1, 
	'child_of'           => 0,
	'exclude'            => '',
	'echo'               => 1,
	'selected'           => 0,
	'hierarchical'       => 0, 
	'name'               => 'cat',
	'id'                 => '',
	'class'              => 'postform',
	'depth'              => 0,
	'tab_index'          => 0,
	'taxonomy'           => 'category',
	'hide_if_empty'      => false,
	'value_field'	     => 'term_id',	
); ?>

デフォルトでは次のように表示します：

カテゴリー ID の昇順にソート
最終更新日は非表示
各カテゴリーの投稿数は非表示
空の（投稿のない）カテゴリーは非表示
除外カテゴリーなし
カテゴリーを表示（表示するか値として返すか選べるので）
フォームの 'selected'（初期選択値）とするカテゴリーなし
カテゴリーを階層型構造で表示しない
フォーム名を 'cat' とする
フォーム内のカテゴリーの ID 属性を指定しないため（デフォルトの）カテゴリー名が入る
フォームのクラスを 'postform' とする
階層の深さ制限なし
フォームの tabindex を 0 にする
タクソノミーを 'category' にする
カテゴリー（タクソノミー 'category' のターム）が一つもなければフォーム自体を非表示
ドロップダウンオプションを選択するとターム ID を出力

パラメータ

$args

（文字列|配列）（オプション）デフォルトの引数を上書きします。下記の引数を参照してください。

初期値：

戻り値

(文字列): 'echo' 引数が 0 の場合のみ HTML コンテンツを返します。

引数

show_option_all

（文字列）（オプション）クリックすると 'すべてのカテゴリー' を選択できるテキスト。デフォルトでは、'すべてのカテゴリー' を選択できるテキストを表示しない。

初期値： ''

show_option_none

（文字列）（オプション）クリックすると 'カテゴリーなし' を指定できるテキスト。デフォルトでは、'カテゴリーなし' を指定できるテキストを表示しない。

初期値： ''

option_none_value

（文字列）（オプション）「カテゴリーなし」option 要素の値。

初期値： -1

orderby

（文字列）（オプション）カテゴリーをソートするためのキー項目。有効な値は：

'ID'
'NAME'（名前）
'SLUG'（スラッグ）

初期値： 'ID'

order

（文字列）（オプション）カテゴリーをソートする方向。有効な値は：

'ASC'（昇順）
'DESC'（降順）

初期値： 'ASC'

show_count

（真偽値）（オプション）各カテゴリーに属する投稿数を表示する (1/True) または、しない (0/False)

初期値： 0/False

hide_empty

（真偽値）（オプション）投稿のないカテゴリーを表示する (0/False) または、しない (1/True)

初期値： 1/True

child_of

（整数）（オプション）カテゴリーを ID で指定して、その子孫のすべてのカテゴリー（子、孫、ひ孫・・・）を表示する。get_categories() を参照。

初期値： 0

exclude

（文字列）（オプション）除外したいカテゴリー ID をコンマ区切りで指定。

初期値： ''

参考：例えば 'exclude=4,12' とすれば、ID が 4 と 12 のカテゴリーを表示しない、または値として返さない。get_categories() を参照。

include

（文字列/配列）（オプション）含めたいカテゴリー ID を指定。get_categories() を参照。

初期値： ''

exclude_tree

（文字列）（オプション）コンマ区切りのリストで、除外したい親カテゴリーの ID を定義する。ある親カテゴリーとその子カテゴリーすべてを除外したい時に使う。hierarchical 引数が true の場合は、exclude 引数の値を使って exclude_tree と同じ処理が実行される。

初期値： ''

参考：例えば 'exclude_tree=5' を指定すると、ID が 5 のカテゴリーとその子（すべての子孫）カテゴリーが除外される。

echo

（真偽値）（オプション）カテゴリーリストを表示する (1/True) または、PHP で使うために値を返す (0/False)

初期値： 1/True

depth

（整数）（オプション）カテゴリー階層のどのレベルまでを出力するかを指定。hierarchical 引数が true でなければ、これは無視される。

初期値： 0

参考：depth

0 - 全ての階層のカテゴリーを出力
-1 - 全てのカテゴリーをフラット（インデントなし）形式で出力（hierarchical 引数よりも優先）
1 - 最上位カテゴリーのみ出力
2以上 - 指定した階層までを出力。例えば 2 を指定すると、最上位と直下の子カテゴリまでを出力。

tab_index

（整数）（オプション）ドロップダウンメニューの select 要素に付ける 'tabindex' 属性の値。

初期値： 0

name

（文字列）（オプション）ドロップダウンメニューのフォーム名（select 要素の 'name' 属性）。

初期値： 'cat'

id

（文字列）（オプション）ドロップダウンメニューの ID（select 要素の 'id' 属性）。

初期値： 'name'

class

（文字列）（オプション）ドロップダウンメニューのクラス（select 要素の 'class' 属性）。

初期値： 'postform'

selected

（整数）（オプション）表示ボックスで 'selected' としたいカテゴリーの ID（これを付けるとドロップダウンメニューなどの選択値の初期値となる）。

初期値： 0（どれにも付けない）

hierarchical

（真偽値）（オプション）カテゴリーをフラットに表示する (0/False) または、階層形式（子孫カテゴリーをインデント）で表示する (1/True)

初期値： 0/False

参考：階層形式 (hierarchical=true) にすると 'depth' 引数で指定する階層までを表示する。

pad_counts

（真偽値）（オプション）リンク数または投稿数を計算するとき、子孫カテゴリーからの数値を含める。'show_counts' と 'hierarchical' が両方とも true の場合、この引数は自動的に true に設定される。

初期値： 0/False

taxonomy

（文字列）（オプション）指定したタクソノミーを返す。有効な値は：

'category'（カテゴリー）
'post_tag'（タグ）
登録済みのカスタム分類（タクソノミー）

初期値： category

hide_if_empty

（真偽値）（オプション）ターム（例：カテゴリー、投稿タグ、カスタム分類の項目）が一つも無いときにフォーム自体を非表示にする (1/True) または、表示する (0/False)

初期値： 0/False

value_field

（文字列）（オプション）フォームの option 要素の 'value' 属性へ入れるタームのフィールド。タームの任意の有効なフィールド: 'term_id', 'name', 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description', 'parent', 'count'。

初期値： 'term_id'

用例

送信ボタン付きドロップダウンメニュー

WordPress サイドバーの箇条書きリスト内に、送信ボタン付きの HTML フォームとして、階層型カテゴリーのドロップダウンリストを表示します。各カテゴリーの投稿数も表示します。

<li id="categories">
	<h2><?php _e( 'Categories:' ); ?></h2>
	<form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">
		<?php wp_dropdown_categories( 'show_count=1&hierarchical=1' ); ?>
		<input type="submit" name="submit" value="view" />
	</form>
</li>

JavaScript を用いた送信ボタンなしドロップダウンメニュー

これは show_option_none パラメータを使った例です。 Moshu さんのフォーラムの投稿から転載しました。

<li id="categories"><h2><?php _e( 'Posts by Category' ); ?></h2>
	<?php wp_dropdown_categories( 'show_option_none=Select category' ); ?>
	<script type="text/javascript">
		<!--
		var dropdown = document.getElementById("cat");
		function onCatChange() {
			if ( dropdown.options[dropdown.selectedIndex].value > 0 ) {
				location.href = "<?php echo esc_url( home_url( '/' ) ); ?>?cat="+dropdown.options[dropdown.selectedIndex].value;
			}
		}
		dropdown.onchange = onCatChange;
		-->
	</script>
</li>

JavaScript を用いた送信ボタンなしドロップダウンメニュー (2)

この例は echo パラメータ (echo=0) を使っています。簡単な preg_replace を使って JavaScript のコードを追加しています。 JavaScript が使えない環境でも動作します（送信ボタンを noscript タグ内に埋め込んであるから）。

<li id="categories">
	<h2><?php _e( 'Posts by Category' ); ?></h2>
	<form id="category-select" class="category-select" action="<?php echo esc_url( home_url( '/' ) ); ?>" method="get">

		<?php
		$args = array(
			'show_option_none' => __( 'Select category' ),
			'show_count'       => 1,
			'orderby'          => 'name',
			'echo'             => 0,
		);
		?>

		<?php $select  = wp_dropdown_categories( $args ); ?>
		<?php $replace = "<select$1 onchange='return this.form.submit()'>"; ?>
		<?php $select  = preg_replace( '#<select([^>]*)>#', $replace, $select ); ?>

		<?php echo $select; ?>

		<noscript>
			<input type="submit" value="View" />
		</noscript>

	</form>
</li>

トラブルシューティング

空のドロップダウン

デフォルトでは、wp_dropdown_categories は、少なくともひとつの投稿に付けられているカテゴリーだけを返します。この機能を変更したい場合は、'hide_empty' 引数を false（"0"）に設定する必要があります。

例:

<?php wp_dropdown_categories( 'hide_empty=0' ); ?>

選択したすべての値を持つドロップダウン

'selected' 引数のデフォルト値は 0 ですが、これはドロップダウンのすべてのタームが選択されたとしてマークされてしまう可能性があります。この問題を解決するには、'selected' 引数を 0 ではなく false に設定します。

例:

<?php wp_dropdown_categories( 'selected=false' ); ?>

参考

　一度に複数の値を選べるようにするには、wp_category_checklist() /en を使ってください。
　結果の文字列を echo または返す前に wp_dropdown_cats /en フィルターが適用されます。

変更履歴

2.9 : パラメータに pad_counts を追加
2.7.1 : パラメータに exclude_tree を追加
2.5 : パラメータに depth を追加
2.1 : 新規テンプレートタグ

ソースファイル

wp_dropdown_categories() は wp-includes/category-template.php にあります。

カテゴリータグ： the_category(), the_category_rss(), single_cat_title(), category_description(), wp_dropdown_categories(), wp_list_categories(), get_the_category(), get_the_category_by_ID(), get_category_by_slug(), get_the_category_list(), get_category_parents(), get_category_link(), is_category(), in_category()

リスト・ドロップダウン関数： wp_list_authors(), wp_list_categories(), wp_list_pages(), wp_list_bookmarks(), wp_list_comments(), wp_get_archives(), wp_page_menu(), wp_dropdown_pages(), wp_dropdown_categories(), wp_dropdown_users()

関数リファレンス、テンプレートタグ目次もご覧ください。

テンプレートタグ/wp dropdown categories

目次

説明

使い方

デフォルトの使い方

パラメータ

戻り値

引数

用例

送信ボタン付きドロップダウンメニュー

JavaScript を用いた送信ボタンなしドロップダウンメニュー

JavaScript を用いた送信ボタンなしドロップダウンメニュー (2)

トラブルシューティング

空のドロップダウン

選択したすべての値を持つドロップダウン

参考

変更履歴

ソースファイル

案内メニュー

個人用ツール

名前空間

変種

表示

その他

検索

このサイトについて

リファレンス

サーバー別情報

ドキュメント整備

協力・貢献

WordPress関連リンク

ツール

他言語版

テンプレートタグ/wp dropdown categories

目次

説明

使い方

デフォルトの使い方

パラメータ

戻り値

引数

用例

送信ボタン付きドロップダウンメニュー

JavaScript を用いた送信ボタンなしドロップダウンメニュー

JavaScript を用いた送信ボタンなしドロップダウンメニュー (2)

トラブルシューティング

空のドロップダウン

選択したすべての値を持つドロップダウン

参考

変更履歴

ソースファイル

関連項目

案内メニュー

検索