ショートコード API

出典: WordPress Codex 日本語版

目次

WordPress 2.5で新しく追加されたショートコード API機能は、コンテンツ記事投稿に用いるマクロコードの作成する機能を備えています。ショートコードの単純な例は次のとおりです。 

[gallery]

ショートコード API は、次の例のような属性をサポートするショートコードを作成することができます。 

[gallery id="123" size="medium"]

API が手の込んだパージングを処理するので、ショートコードにカスタマイズされた正規表現を書く必要はありません。 デフォルト属性を設定し取り込むヘルパー関数が含まれています。 API は、自己完結型ショートコードと囲み型ショートコードの両方をサポートします。

手っ取り早く使い始めたい人のために、属性を持つショートコードを作成するのに最低限必要な PHP コードの例を示します。 

// [bartag foo="foo-value"]
function bartag_func($atts) {
	extract(shortcode_atts(array(
		'foo' => 'no foo',
		'bar' => 'default bar',
	), $atts));

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

このコードは、[bartag] ショートコードを作成し、２つの属性 [bartag foo="something" bar="something else"] をサポートします。どちらの属性もオプションであり、値が付与されない場合はデフォルト値が使用されます。

概観

ショートコードを書くには、ハンドラ関数を記述します。 おおまかに言うと、ショートコードハンドラは、WordPress フィルタと類似しています。 フィルタがパラメータを受け入れ、結果を返すように、ハンドラは属性を受け入れ、ショートコードの出力を返します。

ショートコードハンドラを登録するには、add_shortcode() 関数が用いられます。 この関数には、２つのパラメータ、ショートコード名 (記事で用いられる文字列) とハンドラ関数名、があります。

ショートコードハンドラ関数には、１つまたは２つの属性、属性の配列 $atts と、(ショートコードが囲み型で使用された場合) タグで囲まれたコンテンツ $content、があります。例を以下に示します。 

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

ショートコードハンドラを登録する API コールは、以下のようになります。 

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

the_content が表示されるとき、ショートコード API は [my-shortcode] のような登録されたショートコードをパースし、属性と (存在するならば) コンテンツをパースして分離し、対応するショートコードハンドラ関数に渡します。 ショートコードハンドラによって返される文字列は、ショートコードの代わりに記事本体に挿入されます。

以下のようなショートコードの属性は、 

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

以下に示す連想配列に変換され、$atts パラメータとしてハンドラ関数に渡されます。 

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

配列のキーは属性名で、値は対応する属性値です。

属性

生の $atts 配列には、ユーザーが指定した任意の属性が含まれている可能性があります。 欠けている属性にデフォルト値を付与し、ショートコードで認識されない属性をすべて取り除くために、API には shortcode_atts() 関数が用意されています。

shortcode_atts() は、wp_parse_args() 関数に似ていますが、重要な違いがあります。そのパラメータは、以下のとおりです。 

shortcode_atts( $defaults_array, $atts );

両方のパラメータが必須です。 $defaults_array は、認識される属性名とそのデフォルト値を指定する連想配列です。$atts は、ショートコードハンドラに渡される生の属性配列です。shortcode_atts() は、$defaults_array のキーを全て含み、$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' 要素は含まれていないので、出力に含まれません。

ショートコードハンドラでデフォルト値を宣言し、属性をパースする推奨コードイディオムは、以下のとおりです。 

function my_shortcode_handler( $atts, $content = null ) {
   extract( shortcode_atts( array(
      'attr_1' => 'attribute 1 default',
      'attr_2' => 'attribute 2 default',
      // ...etc
      ), $atts ) );
}

この関数は、属性をパースし、デフォルト値を設定し、サポートされない属性を除去し、(extract() を用いて) $attr_1, $attr_2 などの属性キーの名前のローカル変数に蓄積します。つまり、デフォルトの配列は、ローカル変数宣言のリストに類似しています。 (shortcode_atts() はデフォルト配列に含まれないキーをすべて取り除くため、ここでは衝突をハンドルする特別なフラグが無くても、extract() を安全に使用できます。)

出力

ショートコードハンドラ関数の返り値は、ショートコードマクロの代わりに投稿コンテンツの出力に挿入されます。 echo ではなくて return を使用するようにしてください。echo されたものは全てブラウザに出力されますが、ページの適切な箇所に表示されません。

ショートコードは、wpautop/en および wptexturize/enによる投稿の整形適用後にパースされます。 (2.5.0 と 2.5.1 の違いについては、下記注を参照してください。). つまり、ショートコードの出力 HTML は、カーリークォートが適用されず、p タグや br タグも付与されません。 ショートコードの出力を整形したい場合は、ショートコードハンドラが出力を返したときに、wpautop() や wptexturize() を直接呼び出す必要があります。

wpautop はショートコードの構文を認識し、独立した行のショートコードを p あるいは br タグで括らないようにします。 この方法で使用されるショートコードは、出力が <p>や <div>. などの適切なブロックタグで括られるようにする必要があります。

注： WordPress 2.5.0では、ショートコードは投稿記事の整形を行う前にパースされるので、ショートコードの出力 HTML が p タグや br タグで括られることがありました。 これは正しくない動作だったので、2.5.1 で修正されました。

囲み型ショートコードと自己完結型ショートコード

上で示した例は、[my-shortcode] のような、自己完結型ショートコードマクロでした。ショートコード API は、[my-shortcode]content[/my-shortcode] のような囲み型ショートコードもサポートしています。

ショートコードマクロがコンテンツを囲むように使用された場合は、ハンドラ関数はそのコンテンツを含む第二パラメータを受け取ります。 ユーザーは、ショートコードをどちらの形式で記述しても構いません。そのため、ハンドラ関数に第二パラメータのデフォルト値を適用することで、どちらのケースにも対応する必要があります。 

function my_shortcode_handler( $atts, $content = null )

is_null($content) を使用して囲み型と自己完結型を区別することができます。

コンテンツがタグで囲まれている場合は、そのコンテンツを含むショートコードマクロ全体が、関数の出力に置き換えられます。 生のコンテンツ文字列に必要なエスケープやエンコードを適用し、出力に含めることが、ハンドラ関数に要求されています。

囲み型ショートコードの例を以下に示します。 

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

add_shortcode('caption', 'caption_shortcode');

このように使用したとき、 

[caption]My Caption[/caption]

出力は以下の通りです。 

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

$content は、エスケープやエンコードされずに返り値に含まれているので、ユーザーが生 HTML を含めることができます。 

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

出力は以下の通りです。 

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

これは、意図された動作のことも、意図されない動作のこともあるでしょう。ショートコードが生 HTML の出力を許可しないようにするには、エスケープまたはフィルタ関数を使用してから結果を返すようにしてください。

ショートコードパーザーは、投稿記事コンテンツにシングルパスを使用します。つまり、ショートコードハンドラの $content パラメータが別のショートコードを含む場合、それはパースされません。 

[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>';
}

この例では、タグで囲まれたコンテンツ内の [my-shortcode] マクロがパースされることが保証され、出力は caption span で囲まれます。 

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

囲み型ショートコードは、自己完結型ショートコードと同様に、属性をサポートします。class 属性をサポートするように改良されたcaption_shortcode() の例を以下に示します。 

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>

その他の特徴

  • パーザーは、[my-shortcode /] のような xhtml スタイルのショートコードをサポートしています。これはオプションです。
  • 属性名は、必ず小文字に変換されてからハンドラ関数に渡されます。 値は変更されません。[my-shortcode FOO="BAR"]は、$atts = array( 'foo' => 'BAR' ) を生成します。
  • ショートコードマクロは、シングルクォーテーションまたはダブルクォーテーションが利用できます。属性の値が空白を含まない場合は、クォーテーションの省略も可能です。[my-shortcode foo='123' bar=456] は、[my-shortcode foo="123" bar="456"] と同等です。
  • 古い、アドホックなショートコードとの後方互換性のため、属性名を省略することができます。属性名がない場合は、$atts 配列の順序キーが付与されます。たとえば、[my-shortcode 123] は $atts = array( 0 => 123 ) を生成します。順序で規定される属性と、属性名のある属性を混合することができます。また値が空白やその他の重要な文字を含む場合は引用符を使用することができます。

関数リファレンス

利用可能なショートコード API 関数を、以下に示します。

add_shortcode() 

function add_shortcode($tag, $func)

新しいショートコードハンドラ関数を登録します。$tag は、my-shortcode のような、ユーザーによって記述されるショートコード文字列 (角括弧（[]）を除いたもの) です。$func は、ハンドラ関数名です。

ショートコードには、１つのハンドラ関数のみが存在できます。同じ $tag 名に対して再び add_shortcode() を呼び出した場合は、以前のハンドラに上書きします。

remove_shortcode() 

function remove_shortcode($tag)

既存のショートコードを抹消します。$tag は、add_shortcode() で使用されるショートコード名です。

remove_all_shortcodes() 

function remove_all_shortcodes()

すべてのショートコードを抹消します。

shortcode_atts() 

function shortcode_atts($pairs, $atts)

$pairsで指定されているデフォルト値に対して、属性の生配列 $atts を処理し、配列を返します。結果は、$pairs のすべてのキーを含み、$atts の値をマージしたものになります。$atts に存在しても $pairs に存在しないキーは無視されます。

do_shortcode() 

function do_shortcode($content)

$content 文字列の既知のショートコードをパースします。 元のコンテンツのショートコードマクロが、ハンドラ関数の出力で置き換えられた文字列を返します。

do_shortcode() は、'the_content' のデフォルトフィルターとして、プライオリティ11で登録されます。

制限事項

ショートコードパーザーは、ハンドラ関数が再帰的に do_shortcode() を呼び出すことをサポートしていれば、ネストされたショートコードマクロを処理することができます。 

[tag-a]
   [tab-b]
      [tag-c]
   [/tag-b]
[/tag-a]

しかし、ショートコードマクロが、同じ名前の別のマクロを囲むように使用すると、パースに失敗します。 

[tag-a]
   [tag-a]
   [/tag-a]
[/tag-a]

これは、do_shortcode() で使われる文脈自由正規パーザーの制限です。非常に高速ですが、ネストの階層を数えることができません。そのため、この場合には各開始タグを正しい終了タグとマッチさせることができません。

外部リソース

  • Shortcode summary by Aaron D. Campbell に、ショートコードの説明およびサンプルが掲載されています。javascriptを使用して、ショートコードをメタボックスに組み込んで編集者へと送信するサンプルも含まれています。
  • WordPress Shortcode API Overview - explanations on usage and example of plugin using shortcodes.
  • Simple shortcode-powered BBCode plugin に、ショートコードを用いて、BBコードをサポートするプラグインが紹介されています。ショートコードの動作を見るのに良いでしょう。

活用事例

変更履歴

  • 2.5.1 :
    • do_shortcode() の the_content でのプライオリティが 11 になりました。
  • 2.5 : 新規機能

原文・最新版： WordPress Codex » Shortcode API （最新版との差分）

"http://wpdocs.sourceforge.jp/%E3%82%B7%E3%83%A7%E3%83%BC%E3%83%88%E3%82%B3%E3%83%BC%E3%83%89_API" より作成
他の言語