WordPressのショートコードAPI

WordPressのショートコードAPIWordPressは、ショートコードを登録、処理するためのAPIを備えており、このショートコードAPIを使えば、簡単にショートコードを登録することが出来る。

今回は、このショートコードAPIの説明を行う。

ショートコードの登録には、add_shortcode()関数を使用する。

add_shortcode('ショートコードタグ', 'ハンドラー');

ショートコードは、

[ショートコードタグ]

と言った[]で文字列を囲んだ書式であるが、[]を除いたものを「ショートコードタグ」として記述し、「ハンドラー」には、ショートコードと置き換える文字列を戻り値として返す関数の名称を記述する。

例えば、「こんにちは」と表示されるショートコード [hi]を登録する場合は、

add_shortcode('hi', 'my_shortcode_handler');

function my_shortcode_handler() {
	return 'こんにちは';
}

と記述すれば良い。

非常に簡単にショートコードを登録できるようになっているが、内部的には、 do_shortcode()というフィルター関数が、add_shortcode()関数で登録された全てのショートコードハンドラーを使って文字列に変換する処理を行なっており、デフォルトでは、do_shortcode()関数は、the_contentフィルターフックにプライオリティ11で適用されている。

このフィルターによって、投稿や固定ページが表示される際に、ショートコードが決められた文字列に変換され、表示に反映される。

デフォルトでは、ショートコードが使えるのは投稿と固定ページの中だけであるが、他の場所でも使用したいなら、このdo_shortcode()関数を使えば良い。

例えば、コメントでショートコードを使いたいなら、

add_filter('comment_text', 'do_shortcode', 11);

とすれば良い。(プライオリティは11ある必要はない。)

以上がショートコードの登録の基本であるが、ショートコードAPIは、単純なショートコードだけなく、属性値を持つショートコードや囲み型のショートコードもサポートしている。

[ショートコードタグ attr1="値1" attr2="値2" ・・・]任意の文字列[/ショートコードタグ]

次の例は、属性値を持つ、囲み型のショートコードであり、[div id="id1" class="class1"]任意の文字列[/div]と言う書式のショートコードを<div id=”id1″ class=”class1″>任意の文字列<div>に変換してくれる。

add_shortcode('div', 'my_shortcode_handler');

function my_shortcode_handler($atts, $content = null) {
	extract(shortcode_atts(array(
		'id' => 'block',
		'class' => 'block',
		), $atts));

	return '<div id="'.esc_attr($id).'" class="'.esc_attr($class).'">'.do_shortcode($content).'</div>';
}

ハンドラーは、引数としてショートコードで囲まれた部分の文字列を受け取ることが出来る。

加えて、属性名をキー、属性値を値とする配列の形で、ショートコードの記述された全ての属性と属性値を引数として受け取ることが出来る。

しかし、ユーザーが入力する属性、属性値に関しては、何が含まれているか分からない。

そこで、無効な属性が含まれている場合は、これを取り除き、欠けている場合は、デフォルト値を与えて補う必要があるが、これを簡単に行うことができるのが、shortcode_atts()関数である。

上の例では、id、classのデフォルト属性値は「block」となっており、ショートコードで、idまたはclassが省略された場合は、この「block」が値として自動的に割り当てられる。

そして最終的には、extract()を使って属性名を名前とする変数に格納している。

これらの値を用いて、置き換えの文字列を定義し、これを戻り値として返しているが、受け取った属性値は、セキュリティ上も信頼できないので、そのまま出力することは避けたい。

そこで、戻り値として返す前にesc_attr()関数でエスケープしている。

また、$contentに対してdo_shortcode()を適用して、ショートコードに囲まれたショートコード、つまりネストされたショートコードも、ショートコードとして正しく処理されるようにしている。

前にも書いたがdo_shortcode()が、ショートコードを処理するフィルターそのものであるので、do_shortcode()を文字列に適用すれば、文字列内のショートコードが正しく処理される。上記の場合は、$contentに対して、これを行なっている。



PHP, WordPress, ネット・PC, , Permalink