[WP]ショートコードAPI仕様メモ

wordpress2.5から実装されたショートコードについて。
ショートコードというのは、タグの簡易版みたいなものです。プラグインではよくお目にかかります。
2.5から本文中に［gallery］と入力すると、その記事でアップロードされた画像がサムネイルで一覧表示される機能がありますが、こういうのを自作できるわけです。

胡散臭いまとめは信用ならねぇ、という方は公式サイトの説明を見てください。
※この記事は本家解説の完全翻訳はしてません

手っ取り早く作ってみる

下のソースをアクティブになってるテーマのfunction.phpにコピペする。

function bartag_func($atts) {
	extract(shortcode_atts(array(
		'foo' => 'no foo',
		'baz' => 'default baz',
	), $atts));

	return "foo = {$foo}";
}
add_shortcode('bartag', 'bartag_func');

▼投稿画面で次のタグを記入すると、それぞれ違う出力結果になります。

[ bartag ]と本文に投稿→foo = no foo
[ bartag foo=”bar” ]と本文に投稿→foo = bar

概要

ショートコードを定義する関数（ショートコードハンドラ）は２つ引数を持ってます。

function my_shortcode_handler($atts, $content=null) {}

• $atts・・・属性の配列
• $content・・・ショートコードをタグっぽく使ったときの中身

これをショートコードとして登録するにはadd_shortcode（）を使う。

add_shortcode('my-shortcode', 'my_shortcode_handler');

サイドバーウィジェットとほぼ同じです。

本文中に投稿されたショートコードの属性は

[ my-shortcode foo="bar" baz="bing" ]

$attsパラメータに受け渡されると変換されて次のような連想配列になります

array( 'foo' => 'bar', 'baz' => 'bing')

配列のkeyは属性の名前、valueは属性の値です。

属性とか

生の$atts配列は指定された属性をただ並べてるだけなので、値が無かったり想定外の属性が渡されることも考えられます。
それによってショートコードが機能を失わないために、shortcode_atts()で属性にあらかじめデフォルトの値を設定することができます。

shortcode_atts( $defaults_array, $atts );

どちらのパラメータも必須。

• $defaults_array・・・デフォルトの値を連想配列で設定する。
• $atts・・・生の属性を連想配列としてショートコードハンドラに渡す

shortcode_atts()は、値があればその値をそのままパス。なければデフォルトで設定された値を返します。

たとえばこんな感じで設定したとする

$a = shortcode_atts( array(
   'title' => 'My Title'
   'foo' => 123,
   ), $atts );

$attsにarray( 'foo' => 456, 'bar' => 'something' )が渡された場合、
$aの値はarray( 'title' => 'My Title', 'foo' => 456 )になります。

$atts['foo']はデフォルトの123を上書きし、$atts['title']はデフォルトで設定されてる’My Title’が使用されました。’bar’はデフォルトの配列内に含まれていない属性なので、結果に含まれません。

Enclosing vs self-closing shortcodes

［gallary］のように単体で使うほかに、[my-shortcode]content[/my-shortcode]のようにショートコードでコンテンツを囲んでタグっぽく使うことも出来ます。

[ caption]My Caption[/caption ]

この場合のショートコードハンドラは次のように書きます。

function caption_shortcode( $atts, $content = null ) {
   return '<span class="caption">' . $content . '</span>';
}
add_shortcode('caption', 'caption_shortcode');

ショートコードに囲まれた内容は、ショートコードハンドラの第二引数$contentsへ受け渡されます。

その結果、このように出力されます。

<span class="caption">My Caption</span>

$contentsにタグが含まれる場合もあるかと思いますが

[ caption]<a href="http://example.com/">My Caption</a>[/caption ]

▼ショートコードに囲まれたHTMLはそのままパスされます

<span class="caption"><a href="http://example.com/">My Caption</a></span>

しかし、HTMLタグではなく別のショートコードが入ってる場合

[ caption]Caption: [my-shortcode][/caption ]

▼このように、ネストされたショートコードはそのままでは機能しませんが

<span class="caption">Caption: [my-shortcode]</span>

次のようにショートコードハンドラ内でdo_shortcode()を使うと

function caption_shortcode( $atts, $content = null ) {
   return '<span class="caption">' . do_shortcode($content) . '</span>';
}

ネストされたショートコードも機能するようになります。

<span class="caption">Caption: The result of my-shortcode's handler function</span>

また、ショートコードは自身を閉じるのと同じように、属性を追加することもできます。
たとえば、上にあるサンプルのcaption_shortcode()でclassをつける場合のソースは次のようになります。

function caption_shortcode( $atts, $content = null ) {
   extract( shortcode_atts( array(
      'class' => 'caption',
      ), $atts ) );
 
   return '<span class="' . attribtue_escape($caption) . '">' . $content . '</span>';
}

[ caption class="headline"]My Caption[/caption ]

▼

<span class="headline">My Caption</span>