• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

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

提供: WordPress Codex 日本語版
< テンプレートタグ
2015年5月27日 (水) 07:47時点におけるMiccweb (トーク | 投稿記録)による版 (参考: link)

移動先: 案内検索

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

使い方

<?php wp_dropdown_categories( $args ); ?>

デフォルトの使い方

<?php $args = array(
	'show_option_all'    => '',
	'show_option_none'   => '',
	'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,
); ?>

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

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

パラメータ

$args
文字列|配列) (オプション) デフォルトの引数を上書きします。下記の引数を参照してください。
初期値:

戻り値

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

引数

show_option_all
文字列) (オプション) クリックすると 'すべてのカテゴリー' を選択できるテキスト。デフォルトでは、'すべてのカテゴリー' を選択できるテキストを表示しない。
初期値: ''
show_option_none
文字列) (オプション) クリックすると 'カテゴリーなし' を指定できるテキスト。デフォルトでは、'カテゴリーなし' を指定できるテキストを表示しない。
初期値: ''
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() を参照。

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

用例

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

<li id="categories">
	<h2><?php _e('Categories:'); ?></h2>
	<form action="<?php bloginfo('url'); ?>" method="get">
	<div>
	<?php wp_dropdown_categories('show_count=1&hierarchical=1'); ?>
	<input type="submit" name="submit" value="view" />
	</div>
	</form>
</li>

これは 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 get_option('home');
?>/?cat="+dropdown.options[dropdown.selectedIndex].value;
		}
    }
    dropdown.onchange = onCatChange;
--></script>
</li>

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

<li id="categories">
	<h2><?php _e('Posts by Category'); ?></h2>
	<form action="<?php bloginfo('url'); ?>/" method="get">
	<div>
<?php
$select = wp_dropdown_categories('show_option_none=Select category&show_count=1&orderby=name&echo=0');
$select = preg_replace("#<select([^>]*)>#", "<select$1 onchange='return this.form.submit()'>", $select);
echo $select;
?>
	<noscript><div><input type="submit" value="View" /></div></noscript>
	</div></form>
</li>

参考

  •  一度に複数の値を選べるようにするには、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()


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


最新英語版: WordPress Codex » Function Reference/wp_dropdown_categories最新版との差分