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

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

「ショートコード API」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(デフォルトのショートコード 追加)
(en:Shortcode API 01:16, 2 October 2015 Miqrogroove 版を反映。)
1行目: 1行目:
__TOC__
+
{{NeedTrans|[[#Limitations|制限事項]]節以降が}}
[[Version 2.5|WordPress 2.5]]で新しく追加された'''ショートコード API'''機能は、コンテンツ記事投稿に用いるマクロコードの作成する機能を備えています。ショートコードの単純な例は次のとおりです。
+
 
 +
'''ショートコード API''' は、投稿や固定ページで使える WordPress の[[ショートコード]]を作るための関数のシンプルなセットです。例えば次のショートコードは(投稿や固定ページの本文に書くと)その投稿や固定ページへ添付されたイメージのギャラリーを追加します:
  
 
  [gallery]
 
  [gallery]
  
ショートコード API は、次の例のような属性をサポートするショートコードを作成することができます。
+
この API を使ってプラグイン開発者は特別な種類のコンテンツ(例えばフォームやコンテンツ生成器)を作成できます。ユーザーはそれに対応するショートコードをページのテキストに追加して、そのコンテンツをページへ追加できます。
 +
 
 +
ショートコード API は次の例のように属性をサポートするショートコードも簡単に作成できます:
  
 
  [gallery id="123" size="medium"]
 
  [gallery id="123" size="medium"]
  
API が手の込んだパージングを処理するので、ショートコードにカスタマイズされた正規表現を書く必要はありません。  デフォルト属性を設定し取り込むヘルパー関数が含まれています。  API は、自己完結型ショートコードと囲み型ショートコードの両方をサポートします。
+
API が手の込んだパーシング(構文解析)を処理するので、いちいちショートコードに独自の正規表現を書く必要はありません。属性にデフォルトを設定し取り込むヘルパー関数が含まれています。API は自己完結型ショートコードと囲み型ショートコードの両方をサポートします。
  
手っ取り早く使い始めたい人のために、属性を持つショートコードを作成するのに最低限必要な PHP コードの例を示します。
+
手っ取り早く使い始めたい人のために、ショートコードを作成するのに最低限必要な PHP コードの例を示します:
  
// [bartag foo="foo-value"]
+
<pre>
function bartag_func($atts) {
+
// [foobar]
extract(shortcode_atts(array(
+
function foobar_func( $atts ){
'foo' => 'no foo',
+
return "foo and bar";
'bar' => 'default bar',
+
}
), $atts));
+
add_shortcode( 'foobar', 'foobar_func' );
+
</pre>
return "foo = {$foo}";
+
 
}
+
これで <code>[foobar]</code> ショートコードが作られて、使用すると次の値を返します: foo and bar
add_shortcode('bartag', 'bartag_func');
+
 
 +
属性を持つショートコードの場合は:
 +
 
 +
<pre>
 +
// [bartag foo="foo-value"]
 +
function bartag_func( $atts ) {
 +
    $a = shortcode_atts( array(
 +
        'foo' => 'something',
 +
        'bar' => 'something else',
 +
    ), $atts );
 +
 
 +
    return "foo = {$a['foo']}";
 +
}
 +
add_shortcode( 'bartag', 'bartag_func' );
 +
</pre>
  
このコードは、<code>[bartag]</code> ショートコードを作成し、2つの属性 <code>[bartag foo="something" bar="something else"]</code> をサポートします。どちらの属性もオプションであり、値が付与されない場合はデフォルト値が使用されます。
+
このコードは、<code>[bartag]</code> ショートコードを作成し、2つの属性 <code>foo</code> と <code>bar</code> をサポートします。どちらの属性もオプションで、省略するとデフォルト値 <code>foo="something"</code> と <code>bar="something else"</code> が入ります。そして <code>foo = {foo 属性の値}</code> を返します。
  
 
<div id="Overview">
 
<div id="Overview">
== 概観 ==
+
== 概要 ==
 
</div>
 
</div>
  
ショートコードを書くには、ハンドラ関数を記述します。  おおまかに言うと、ショートコードハンドラは、WordPress フィルタと類似しています。 フィルタがパラメータを受け入れ、結果を返すように、ハンドラは属性を受け入れ、ショートコードの出力を返します。
+
ショートコードを作るにはハンドラー関数を記述します。おおまかに言うとショートコードハンドラーは WordPress のフィルターと似ています。フィルターがパラメータを受け取って結果を返すように、ハンドラーは属性を受け取ってショートコード出力を返します。
  
ショートコードハンドラを登録するには、[[#add_shortcode()|<code>add_shortcode()</code>]] 関数が用いられます。  この関数には、2つのパラメータ、ショートコード名 (記事で用いられる文字列) とハンドラ関数名、があります。
+
ショートコードの名前は英小文字、数字、下線を使う必要があります。特に[[Shortcode_API#Hyphens|ハイフン]](ダッシュ)には注意して、使わないのが賢明です。
  
ショートコードハンドラ関数には、1つまたは2つの属性、属性の配列 <code>$atts</code> と、(ショートコードが囲み型で使用された場合) タグで囲まれたコンテンツ <code>$content</code>、があります。例を以下に示します。
+
ショートコードハンドラーを登録するには <code>[[関数リファレンス/add_shortcode|add_shortcode]]</code> 関数を使います。この関数には2つのパラメータ、ショートコード名(投稿の本文で使う文字列)とコールバック関数の名前を渡します。
  
function my_shortcode_handler($atts, $content=null) {
+
ショートコードのコールバック関数には3つのパラメータが渡されます。いくつ使うか、どれも使わないかはあなたの自由です。
}
+
  
ショートコードハンドラを登録する API コールは、以下のようになります。
+
* '''$atts''' - 属性の連想配列、または空文字列(属性が省略された場合)
 +
* '''$content''' - 囲まれたコンテンツ(囲み型ショートコードとして使われた場合)
 +
* '''$tag''' - ショートコードのタグ。共有コールバック関数の場合に便利です
  
add_shortcode('my-shortcode', 'my_shortcode_handler');
+
ショートコードハンドラーを登録する API 呼び出しは例えば次のようになります;
  
<code>the_content</code> が表示されるとき、ショートコード API は <code>[my-shortcode]</code> のような登録されたショートコードをパースし、属性と (存在するならば) コンテンツをパースして分離し、対応するショートコードハンドラ関数に渡します。  ショートコードハンドラによって返される文字列は、ショートコードの代わりに記事本体に挿入されます。
+
add_shortcode( 'myshortcode', 'my_shortcode_handler' );
  
以下のようなショートコードの属性は、
+
[[テンプレートタグ/the content|the_content]] が表示されるとき、ショートコード API は <code>[myshortcode]</code> のような登録済みショートコードをパースして、属性と (存在するならば) コンテンツを分離してパースし、対応するショートコードハンドラー関数へ渡します。ショートコードハンドラが''返した''(表示されたのではなく)文字列はショートコードの代わりにページの本文へ挿入されます。
  
[my-shortcode foo="bar" baz="bing"]
+
次のようにショートコードの属性が入力されたとしましょう:
  
以下に示す連想配列に変換され、<code>$atts</code> パラメータとしてハンドラ関数に渡されます。
+
[myshortcode foo="bar" bar="bing"]
  
array( 'foo' => 'bar', 'baz' => 'bing')
+
属性は次のような連想配列に変換され、<code>$atts</code> パラメータとしてハンドラー関数へ渡されます:
  
配列のキーは属性名で、値は対応する属性値です。
+
array( 'foo' => 'bar', 'bar' => 'bing' )
  
<div id="Attributes">
+
配列のキーは属性名で、値は対応する属性値です。<!-- 以降は未確認なのでコメントアウトします 10-Oct-2015 gblsm
== 属性 ==
+
In addition, the zeroeth entry ('''$atts[0]''') will hold the string that matched the shortcode regex, but ONLY IF that is different from the callback name. See the discussion of attributes, below.
 +
コメントアウトここまで -->
 +
 
 +
<div id="Handling_Attributes">
 +
== 属性の処理 ==
 
</div>
 
</div>
  
生の <code>$atts</code> 配列には、ユーザーが指定した任意の属性が含まれている可能性があります。 欠けている属性にデフォルト値を付与し、ショートコードで認識されない属性をすべて取り除くために、API には [[#shortcode_atts|<code>shortcode_atts()</code>]] 関数が用意されています。
+
生の <code>$atts</code> 配列にはユーザーが指定した任意の属性が含まれている可能性があります。<!-- 以降は未確認なのでコメントアウトします 10-Oct-2015 gblsm
 +
  (In addition, the zeroeth entry of the array may contain the string that was recognized by the regex; see the note below.)
 +
コメントアウトここまで -->
  
<code>shortcode_atts()</code> は、<code>wp_parse_args()</code> 関数に似ていますが、重要な違いがあります。そのパラメータは、以下のとおりです。
+
省略された属性にデフォルト値を付与し、ショートコードが認識しない属性をすべて取り除くために、API には shortcode_atts() 関数が用意されています。
 +
 
 +
<code>[[関数リファレンス/shortcode_atts|shortcode_atts()]]</code> <code>[[関数リファレンス/wp_parse_args|wp_parse_args]]</code> 関数に似ていますが、いくつか重要な違いがあります。パラメータは以下のとおりです:
  
 
  shortcode_atts( $defaults_array, $atts );
 
  shortcode_atts( $defaults_array, $atts );
  
両方のパラメータが必須です。 <code>$defaults_array</code> は、認識される属性名とそのデフォルト値を指定する連想配列です。<code>$atts</code> は、ショートコードハンドラに渡される生の属性配列です。<code>shortcode_atts()</code> は、<code>$defaults_array</code> のキーを全て含み、<code>$atts</code> 配列からの値が存在すればその値を付与された正規化された配列を返します。例を以下に示します。
+
両方のパラメータが必須です。<code>$defaults_array</code> は認識される属性名とそのデフォルト値を指定する連想配列です。<code>$atts</code> はショートコードハンドラーに渡された生の属性配列です。<code>shortcode_atts()</code> は、<code>$defaults_array</code> のキーを全て含み、<code>$atts</code> 配列に値が存在すればその値を上書きした、正規化された配列を返します。例を以下に示します:
  
$a = shortcode_atts( array(
+
<pre>
     'title' => 'My Title'
+
$a = shortcode_atts( array(
 +
     'title' => 'My Title',
 
     'foo' => 123,
 
     'foo' => 123,
 +
), $atts );
 +
</pre>
 +
 +
もし <code>$atts</code> の内容が <code>array( 'foo' => 456, 'bar' => 'something' )</code> なら、結果の <code>$a</code> は <code>array( 'title' => 'My Title', 'foo' => 456 )</code> になります。<code>$atts['foo']</code> の値はデフォルト値 <var>123</var> を上書きします。<code>$atts['title']</code> は設定されていないので、デフォルト値 'My Title' が使用されます。デフォルト配列には 'bar' 要素がないので、結果に含まれません。
 +
 +
属性の名前はハンドラー関数へ渡される前にいつも小文字へ変換されます。値はそのままです。<code>[myshortcode FOO="BAR"]</code> は <code>$atts = array( 'foo' => 'BAR' )</code> になります。
 +
 +
ショートコードハンドラーでデフォルトを宣言して属性をパースする推奨のコード形式は以下のとおりです:
 +
 +
<pre>
 +
function my_shortcode_handler( $atts, $content = null ) {
 +
    $a = shortcode_atts( array(
 +
        'attr_1' => 'attribute 1 default',
 +
        'attr_2' => 'attribute 2 default',
 +
        // ...etc
 
     ), $atts );
 
     ), $atts );
 +
}
 +
</pre>
  
<code>$atts</code> <code>array( 'foo' => 456, 'bar' => 'something' )</code> を含むならば、出力 <code>$a</code> <code>array( 'title' => 'My Title', 'foo' => 456 )</code> になります。<code>$atts['foo']</code> の値は、デフォルト値 <var>123</var> を上書きします。<code>$atts['title']</code> は設定されていないので、デフォルト値 'My Title' が使用されます。デフォルト配列には 'bar' 要素は含まれていないので、出力に含まれません。
+
これは属性をパースし、デフォルトを設定し、サポートされない属性を除去し、結果をローカルの配列変数 <code>$a</code> へ入れます。その配列は属性がキーになります(<code>$a['attr_1']</code><code>$a['attr_2']</code> など)。見方を変えると、デフォルトの配列はローカル変数の宣言のリストみたいなものです。<!-- 前の版にあった説明を残しておきます 10-Oct-2015 gblsm
 +
(<code>shortcode_atts()</code> はデフォルト配列に含まれないキーをすべて取り除くため、ここでは衝突をハンドルする特別なフラグが無くても、<code>extract()</code> を安全に使用できます。)
 +
-->
  
ショートコードハンドラでデフォルト値を宣言し、属性をパースする推奨コードイディオムは、以下のとおりです。
+
----
 +
; 重要なヒント - <tt>$atts</tt> の属性名に[[Wikipedia:ja:キャメルケース|キャメルケース]]や大文字を使わない : <tt>$atts</tt> の値は <code>shortcode_atts( array( 'attr_1' => 'attr_1 default', // ...etc ), $atts )</code> の処理前に'''''小文字'''''にされているので、''小文字だけを使う''ようにしましょう。
 +
----
  
function my_shortcode_handler( $atts, $content = null ) {
+
<!-- 以降は未確認なのでコメントアウトします 10-Oct-2015 gblsm
    extract( shortcode_atts( array(
+
----
      'attr_1' => 'attribute 1 default',
+
; NOTE on confusing regex/callback name reference: The zeroeth entry of the attributes array ('''$atts[0]''') will contain the string that matched the shortcode regex, but ONLY if that differs from the callback name, which otherwise appears as the third argument to the callback function.
      'attr_2' => 'attribute 2 default',
+
; (Appears to always appear as third argument as of 2.9.2.)
      // ...etc
+
 
      ), $atts ) );
+
  add_shortcode('foo','foo'); // two shortcodes referencing the same callback
}
+
  add_shortcode('bar','foo');
 +
    produces this behavior:
 +
  [foo a='b'] ==> callback to: foo(array('a'=>'b'),NULL,"foo");
 +
  [bar a='c'] ==> callback to: foo(array(0 => 'bar', 'a'=>'c'),NULL,"");
  
この関数は、属性をパースし、デフォルト値を設定し、サポートされない属性を除去し、(<code>extract()</code> を用いて) <code>$attr_1</code>, <code>$attr_2</code> などの属性キーの名前のローカル変数に蓄積します。つまり、デフォルトの配列は、ローカル変数宣言のリストに類似しています。  (<code>shortcode_atts()</code> はデフォルト配列に含まれないキーをすべて取り除くため、ここでは衝突をハンドルする特別なフラグが無くても、<code>extract()</code> を安全に使用できます。)
+
This is confusing and perhaps reflects an underlying bug, but an overloaded callback routine can correctly determine what shortcode was used to call it, by checking BOTH the third argument to the callback and the zeroeth attribute. (It is NOT an error to have two shortcodes reference the same callback routine, which allows for common code.)
 +
コメントアウトここまで -->
  
 
<div id="Output">
 
<div id="Output">
89行目: 141行目:
 
</div>
 
</div>
  
ショートコードハンドラ関数の返り値は、ショートコードマクロの代わりに投稿コンテンツの出力に挿入されます。 <code>echo</code> ではなくて <code>return</code> を使用するようにしてください。<code>echo</code> されたものは全てブラウザに出力されますが、ページの適切な箇所に表示されません。
+
ショートコードハンドラー関数の返り値はショートコードマクロの代わりに投稿コンテンツの出力へ挿入されます。 <code>echo</code> ではなく <code>return</code> を使うようにしてください。<code>echo</code> されたものはすべてブラウザへ出力されますが、ページの適切な箇所に表示されません。
  
ショートコードは、[[関数リファレンス/wpautop|<code>wpautop</code>]]/[[:en:Function Reference/wpautop|en]] および [[関数リファレンス/wptexturize|<code>wptexturize</code>]]/[[:en:Function Reference/wptexturize|en]]による投稿の整形適用後にパースされます。 ([[Version 2.5|2.5.0]] と [[Version 2.5.1|2.5.1]] の違いについては、下記注を参照してください。).  つまり、ショートコードの出力 HTML は、カーリークォートが適用されず、<code>p</code> タグや <code>br</code> タグも付与されません。  ショートコードの出力を整形したい場合は、ショートコードハンドラが出力を返したときに、<code>wpautop()</code> や <code>wptexturize()</code> を直接呼び出す必要があります。
+
ショートコードは [[関数リファレンス/wpautop|<code>wpautop</code>]] および [[関数リファレンス/wptexturize|<code>wptexturize</code>]] による投稿の整形適用後にパースされます([[Version 2.5|2.5.0]] と [[Version 2.5.1|2.5.1]] の違いについては後の注記を参照してください)。つまりショートコードが出力した HTML には、例えば曲線形のクォートが適用されず、<code>p</code> タグや <code>br</code> タグが追加されません。ショートコードの出力を整形したい場合は、ショートコードハンドラーから出力を返すときに <code>wpautop()</code> や <code>wptexturize()</code> を直接呼び出す必要があります。
  
<code>wpautop</code> はショートコードの構文を認識し、独立した行のショートコードを <code>p</code> あるいは <code>br</code> タグで括らないようにします。  この方法で使用されるショートコードは、出力が <code><nowiki><p></nowiki></code>や <code><nowiki><div></nowiki></code>. などの適切なブロックタグで括られるようにする必要があります。
+
<code>wpautop</code> はショートコードの構文を認識し、ショートコードだけが書かれた行を <code>p</code> あるいは <code>br</code> タグで括らないようにします。この方法で使用されることを前提とするショートコードは、出力を <code><nowiki><p></nowiki></code> や <code><nowiki><div></nowiki></code> などの適切なブロックタグで括る必要があります。
 +
 
 +
参考:[[Version 2.5|WordPress 2.5.0]]では、ショートコードは投稿の整形を行う前にパースされるので、ショートコードが出力した HTML が <code>p</code> タグや <code>br</code> タグで括られることがありました。これは正しくない動作だったので [[Version 2.5.1|2.5.1]] で修正されました。
 +
 
 +
ショートコードが大量の HTML を生成する場合、次のように <code>ob_start</code> を使って出力を取り込んでから文字列へ変換することができます:
 +
 
 +
<pre>
 +
function my_shortcode() {
 +
ob_start();
 +
?> <HTML> <here> ... <?php
 +
return ob_get_clean();
 +
}
 +
</pre>
  
注: [[Version 2.5|WordPress 2.5.0]]では、ショートコードは投稿記事の整形を行う前にパースされるので、ショートコードの出力 HTML が <code>p</code> タグや <code>br</code> タグで括られることがありました。  これは正しくない動作だったので、[[Version 2.5.1|2.5.1]] で修正されました。
 
  
 
<div id="Enclosing_vs_self-closing_shortcodes">
 
<div id="Enclosing_vs_self-closing_shortcodes">
101行目: 164行目:
 
</div>
 
</div>
  
上で示した例は、<code>[my-shortcode]</code> のような、自己完結型ショートコードマクロでした。ショートコード API は、<code>[my-shortcode]content[/my-shortcode]</code> のような囲み型ショートコードもサポートしています。
+
上で示した例は <code>[myshortcode]</code> のような自己完結型ショートコードマクロでした。ショートコード API <code>[myshortcode]コンテンツ[/myshortcode]</code> のような囲み型ショートコードもサポートしています。
  
ショートコードマクロがコンテンツを囲むように使用された場合は、ハンドラ関数はそのコンテンツを含む第二パラメータを受け取ります。  ユーザーは、ショートコードをどちらの形式で記述しても構いません。そのため、ハンドラ関数に第二パラメータのデフォルト値を適用することで、どちらのケースにも対応する必要があります。
+
ショートコードマクロがコンテンツを囲むように使用された場合、ハンドラー関数はそのコンテンツを第2パラメータとして受け取ります。ユーザーはショートコードをどちらの形式で記述しても構いません。そのためハンドラー関数の第2パラメータにデフォルト値を与えておくことによりどちらのケースにも対応する必要があります。
  
 
  function my_shortcode_handler( $atts, $content = null )
 
  function my_shortcode_handler( $atts, $content = null )
  
<code>is_null($content)</code> を使用して囲み型と自己完結型を区別することができます。
+
こうすれば <code>is_null( $content )</code> を使用して囲み型と自己完結型を区別することができます。
  
コンテンツがタグで囲まれている場合は、そのコンテンツを含むショートコードマクロ全体が、関数の出力に置き換えられます。  生のコンテンツ文字列に必要なエスケープやエンコードを適用し、出力に含めることが、ハンドラ関数に要求されています。
+
コンテンツがタグで囲まれている場合は、そのコンテンツを含むショートコードマクロ全体が関数の出力で置き換えられます。生のコンテンツ文字列に必要なエスケープやエンコードを適用し、出力に含める処理は、ハンドラー関数が行う必要があります。
  
囲み型ショートコードの例を以下に示します。
+
囲み型ショートコードの例を以下に示します:
  
 
<pre>
 
<pre>
119行目: 182行目:
 
</pre>
 
</pre>
  
add_shortcode('caption', 'caption_shortcode');
+
これを次のように使用すると:
 
+
このように使用したとき、
+
  
 
  [caption]My Caption[/caption]
 
  [caption]My Caption[/caption]
  
出力は以下の通りです。
+
出力は以下のようになります:
  
 
<pre class="screen"><span class="caption">My Caption</span></pre>
 
<pre class="screen"><span class="caption">My Caption</span></pre>
  
<code>$content</code> は、エスケープやエンコードされずに返り値に含まれているので、ユーザーが生 HTML を含めることができます。
+
<code>$content</code> はエスケープやエンコードされずに返り値へ含められるので、ユーザーが生の HTML を含めることができます:
  
 
<pre>[caption]<a href="<nowiki>http://example.com/</nowiki>">My Caption</a>[/caption]</pre>
 
<pre>[caption]<a href="<nowiki>http://example.com/</nowiki>">My Caption</a>[/caption]</pre>
  
出力は以下の通りです。
+
これは次のような結果を生成します:
  
 
<pre class="screen"><span class="caption"><a href="<nowiki>http://example.com/</nowiki>">My Caption</a></span></pre>
 
<pre class="screen"><span class="caption"><a href="<nowiki>http://example.com/</nowiki>">My Caption</a></span></pre>
  
これは、意図された動作のことも、意図されない動作のこともあるでしょう。ショートコードが生 HTML の出力を許可しないようにするには、エスケープまたはフィルタ関数を使用してから結果を返すようにしてください。
+
これは意図したとおり、またはそうではない動作かもしれません。ショートコードが生の HTML の出力を許可しないようにするには、エスケープまたはフィルター関数を使用してから結果を返すようにしてください。
  
ショートコードパーザーは、投稿記事コンテンツにシングルパスを使用します。つまり、ショートコードハンドラの <code>$content</code> パラメータが別のショートコードを含む場合、それはパースされません。
+
ショートコードのパーサーは投稿コンテンツを一度だけパースします。つまりショートコードハンドラーの <code>$content</code> パラメータが別のショートコードを含む場合、それはパースされません。次の場合:
  
  [caption]Caption: [my-shortcode][/caption]
+
  [caption]Caption: [myshortcode][/caption]
  
出力は以下の通りです。
+
出力はこうなるでしょう:
  
<pre class="screen"><span class="caption">Caption: [my-shortcode]</span></pre>
+
<pre class="screen"><span class="caption">Caption: [myshortcode]</span></pre>
  
囲み型ショートコードが、出力に他のショートコードを許可している場合、ハンドラ関数は、[[#do_shortcode|<code>do_shortcode()</code>]] 関数を再帰的に呼び出します。
+
囲み型ショートコードが出力に他のショートコードを許可する場合、ハンドラー関数が [[関数リファレンス/do_shortcode|do_shortcode()]] を再帰的に呼び出すことができます。
  
 
<pre>
 
<pre>
155行目: 216行目:
 
</pre>
 
</pre>
  
この例では、タグで囲まれたコンテンツ内の <code>[my-shortcode]</code> マクロがパースされることが保証され、出力は caption span で囲まれます。
+
この例では、タグで囲まれたコンテンツ内の <code>[myshortcode]</code> マクロがパースされることが保証され、出力は caption クラスの span タグで囲まれます。
  
<pre class="screen"><span class="caption">Caption: The result of my-shortcode's handler function</span></pre>
+
<pre class="screen"><span class="caption">Caption: myshortcode のハンドラー関数の結果</span></pre>
  
囲み型ショートコードは、自己完結型ショートコードと同様に、属性をサポートします。<code>class</code> 属性をサポートするように改良された<code>caption_shortcode()</code> の例を以下に示します。
+
パーサーは同じショートコードの囲み型と自己完結型のミックスを、そうして欲しいようには処理しません。例えば次のように書いたとします:
 +
 
 +
[myshortcode example='non-enclosing' /] non-enclosed content [myshortcode] enclosed content [/myshortcode]
 +
 
 +
これを「 non-enclosed content 」というテキストで区切られた2つのショートコードとして処理するのではなく、パーサーは「 non-enclosed content [myshortcode] enclosed content 」を囲むひとつのショートコードとして処理します。
 +
 
 +
囲み型ショートコードは自己完結型ショートコードと同様に属性をサポートします。<code>class</code> 属性をサポートするように改良された <code>caption_shortcode()</code> の例を以下に示します:
  
 
<pre>
 
<pre>
170行目: 237行目:
 
}
 
}
 
</pre>
 
</pre>
 +
 +
これで次のようなコンテンツを処理させると:
  
 
  [caption class="headline"]My Caption[/caption]
 
  [caption class="headline"]My Caption[/caption]
 +
 +
次のように出力されます:
  
 
<pre class="screen"><span class="headline">My Caption</span></pre>
 
<pre class="screen"><span class="headline">My Caption</span></pre>
  
 
<div id="Other_features_in_brief">
 
<div id="Other_features_in_brief">
 
+
== その他の機能 ==
== その他の特徴 ==
+
 
</div>
 
</div>
  
* パーザーは、<code>[my-shortcode /]</code> のような xhtml スタイルのショートコードをサポートしています。これはオプションです。
+
* パーサーは <code>[myshortcode /]</code> のような xhtml スタイルのショートコードをサポートしていますが、これはオプションです。
 
+
* 属性名は、必ず小文字に変換されてからハンドラ関数に渡されます。  値は変更されません。<code>[my-shortcode FOO="BAR"]</code>は、<code><nowiki>$atts = array( 'foo' => 'BAR' )</nowiki></code> を生成します。
+
  
* ショートコードマクロは、シングルクォーテーションまたはダブルクォーテーションが利用できます。属性の値が空白を含まない場合は、クォーテーションの省略も可能です。<code>[my-shortcode foo='123' bar=456]</code> は、<code>[my-shortcode foo="123" bar="456"]</code> と同等です。
+
* ショートコードマクロの属性の値にはシングルクォートとダブルクォートのどちらも使えます。属性の値が空白を含まない場合はクォートを省略できます。<code>[myshortcode foo='123' bar=456]</code> <code>[myshortcode foo="123" bar="456"]</code> と同等です。参考:最後尾の属性の値はスラッシュ「/」で終わることができません。ひとつ前に説明した機能がそのスラッシュを消してしまうためです。
  
* 古い、アドホックなショートコードとの後方互換性のため、属性名を省略することができます。属性名がない場合は、<code>$atts</code> 配列の順序キーが付与されます。たとえば、<code>[my-shortcode 123]</code> は <code>$atts = array( 0 => 123 )</code> を生成します。順序で規定される属性と、属性名のある属性を混合することができます。また値が空白やその他の重要な文字を含む場合は引用符を使用することができます。
+
* 古くてアドホックなショートコードとの後方互換性のため、属性名を省略することができます。属性名がない場合は位置を表す数値キーをつけて <code>$atts</code> 配列へ入れられます。例えば、<code>[myshortcode 123]</code> は <code>$atts = array( 0 => 123 )</code> を生成します。属性名を省略した属性と属性名のある属性を混ぜて使うことができます。そして値が空白や他の特殊文字を含む場合はクォートを使用することができます。
  
* ショートコード API にはテストケースがあります。http://svn.automattic.com/wordpress-tests/wp-testcase/test_shortcode.php でエラーケースや異常な構文の例を含むテストが公開されています。
+
* ショートコード API にはテストケースがあります。エラーケースや異常な構文の例を含むテストが http://svn.automattic.com/wordpress-tests/wp-testcase/test_shortcode.php で公開されています。
  
 
<div id="Function_reference">
 
<div id="Function_reference">
198行目: 266行目:
 
=== add_shortcode() ===
 
=== add_shortcode() ===
  
  function add_shortcode($tag, $func)
+
  function add_shortcode( $tag, $func )
  
新しいショートコードハンドラ関数を登録します。<code>$tag</code> は、<code>my-shortcode</code> のような、ユーザーによって記述されるショートコード文字列 (角括弧(<code>[]</code>)を除いたもの) です。<code>$func</code> は、ハンドラ関数名です。
+
新しいショートコードハンドラー関数を登録します。<code>$tag</code> <code>myshortcode</code> のようなユーザーによって記述されるショートコード文字列(角括弧 <code>[</code> と <code>]</code> を除いたもの)です。<code>$func</code> はハンドラー関数名です。
  
ショートコードには、1つのハンドラ関数のみが存在できます。同じ <code>$tag</code> 名に対して再び <code>add_shortcode()</code> を呼び出した場合は、以前のハンドラに上書きします。
+
ひとつのショートコードには1つのハンドラー関数のみが存在できます。同じ <code>$tag</code> 名に対して再び <code>add_shortcode()</code> を呼び出すと以前のハンドラーが上書きされます。
  
 
=== remove_shortcode() ===
 
=== remove_shortcode() ===
  
  function remove_shortcode($tag)
+
  function remove_shortcode( $tag )
  
既存のショートコードを抹消します。<code>$tag</code> は、<code>add_shortcode()</code> で使用されるショートコード名です。
+
既存のショートコードを抹消します。<code>$tag</code> <code>add_shortcode()</code> で使用されるショートコード名です。
  
 
=== remove_all_shortcodes() ===
 
=== remove_all_shortcodes() ===
218行目: 286行目:
 
=== shortcode_atts() ===
 
=== shortcode_atts() ===
  
  function shortcode_atts($pairs, $atts)
+
  function shortcode_atts( $pairs, $atts )
  
<code>$pairs</code>で指定されているデフォルト値に対して、属性の生配列 <code>$atts</code> を処理し、配列を返します。結果は、<code>$pairs</code> のすべてのキーを含み、<code>$atts</code> の値をマージしたものになります。<code>$atts</code> に存在しても <code>$pairs</code> に存在しないキーは無視されます。
+
<code>$pairs</code> で指定されているデフォルト値に対して、生の属性の配列 <code>$atts</code> を処理します。配列を返します。結果は <code>$pairs</code> のすべてのキーを含み、<code>$atts</code> の値をマージしたものになります。<code>$atts</code> に存在しても <code>$pairs</code> に存在しないキーは無視されます。
  
 
=== do_shortcode() ===
 
=== do_shortcode() ===
  
  function do_shortcode($content)
+
  function do_shortcode( $content )
  
<code>$content</code> 文字列の既知のショートコードをパースします。  元のコンテンツのショートコードマクロが、ハンドラ関数の出力で置き換えられた文字列を返します。
+
<code>$content</code> 文字列に含まれる既知のショートコードをパースします。元のコンテンツに含まれたショートコードマクロがハンドラー関数の出力で置き換えられた文字列を返します。
 +
 
 +
[[関数リファレンス/do_shortcode|<code>do_shortcode()</code>]] は <code>'the_content'</code> フックのデフォルトフィルターとして優先度11で登録されます。
  
<code>do_shortcode()</code> は、<code>'the_content'</code> のデフォルトフィルターとして、プライオリティ11で登録されます。
 
  
 
<div id="Limitations">
 
<div id="Limitations">
234行目: 303行目:
 
</div>
 
</div>
  
ショートコードパーザーは、ハンドラ関数が再帰的に <code>do_shortcode()</code> を呼び出すことをサポートしていれば、ネストされたショートコードマクロを処理することができます。
+
<div id="Nested_Shortcodes">
 +
=== 入れ子のショートコード ===
 +
</div>
 +
 
 +
ショートコードパーサーは、再帰的に <code>do_shortcode()</code> を呼び出すことでハンドラー関数がサポートしていれば、入れ子になったショートコードマクロを正しく処理することができます:
  
 
  [tag-a]
 
  [tag-a]
     [tab-b]
+
     [tag-b]
 
       [tag-c]
 
       [tag-c]
 
     [/tag-b]
 
     [/tag-b]
 
  [/tag-a]
 
  [/tag-a]
  
しかし、ショートコードマクロが、同じ名前の別のマクロを囲むように使用すると、パースに失敗します。
+
しかしショートコードマクロが同じ名前のマクロをもうひとつ囲むように使用するとパースに失敗します:
  
 
  [tag-a]
 
  [tag-a]
249行目: 322行目:
 
  [/tag-a]
 
  [/tag-a]
  
これは、<code>do_shortcode()</code> で使われる文脈自由正規パーザーの制限です。非常に高速ですが、ネストの階層を数えることができません。そのため、この場合には各開始タグを正しい終了タグとマッチさせることができません。
+
これは [[関数リファレンス/do_shortcode|<code>do_shortcode()</code>]] で使われる文脈自由正規表現パーサーの制限によるものです。このパーサーはとても高速ですが入れ子のレベルを数えることができません。そのためこの場合にはそれぞれの開始タグを正しい終了タグとマッチさせることができません。
  
 +
In future versions of WordPress, it may be necessary for plugins having a nested shortcode syntax to ensure that the wptexturize() processor does not interfere with the inner codes.  It is recommended that for such complex syntax, the [[プラグイン API/フィルターフック一覧/no_texturize_shortcodes|no_texturize_shortcodes]] /[[:en:Plugin_API/Filter_Reference/no_texturize_shortcodes|en]] filter should be used on the outer tags.  In the examples used here, tag-a should be added to the list of shortcodes to not texturize.  If the contents of tag-a or tag-b still need to be texturized, then you can call [[関数リファレンス/wptexturize|wptexturize()]] before calling [[関数リファレンス/do_shortcode|do_shortcode()]] as described above.
  
== デフォルトのショートコード ==
+
=== Unregistered Names ===
  
* <code>[[Audio Shortcode|[audio]]] /[[:en:Audio Shortcode|en]]</code>
+
Some plugin authors have chosen a strategy of not registering shortcode names, for example to disable a nested shortcode until the parent shortcode's handler function is called.  This may have unintended consequences, such as failure to parse shortcode attribute values.  For example:
* <code>[[Caption Shortcode|[wp_caption]]] /[[:en:Caption Shortcode|en]] </code>
+
* <code>[[Caption Shortcode|[caption]]] /[[:en:Caption Shortcode|en]]</code>
+
* <code>[[Embed Shortcode|[embed]]] /[[:en:Embed Shortcode|en]]</code>
+
* <code>[[Gallery Shortcode|[gallery]]] /[[:en:Gallery Shortcode|en]]</code>
+
* <code>[[Video Shortcode|[video]]] /[[:en:Video Shortcode|en]]</code>
+
* <code>[[Playlist Shortcode|[playlist]]] /[[:en:Playlist Shortcode|en]]</code>
+
  
 +
[tag-a unit="north"]
 +
    [tag-b size="24"]
 +
      [tag-c color="red"]
 +
    [/tag-b]
 +
[/tag-a]
 +
 +
Starting with version 4.0.1, if a plugin fails to register tag-b and tag-c as valid shortcodes, the wptexturize() processor will output the following text prior to any shortcode being parsed:
 +
 +
[tag-a unit="north"]
 +
    [tag-b size=&amp;#8221;24&amp;#8221;]
 +
      [tag-c color=&amp;#8221;red&amp;#8221;]
 +
    [/tag-b]
 +
[/tag-a]
 +
 +
Unregistered shortcodes should be considered normal plain text that have no special meaning, and the practice of using unregistered shortcodes is discouraged.  If you must enclose raw code between shortcode tags, at least consider using the [[プラグイン API/フィルターフック一覧/no_texturize_shortcodes|no_texturize_shortcodes]] /[[:en:Plugin_API/Filter_Reference/no_texturize_shortcodes|en]] filter to prevent texturization of the contents of tag-a:
 +
 +
add_shortcode( 'tag-a', 'my_tag_a_handler' );
 +
add_filter( 'no_texturize_shortcodes', 'ignore_tag_a' );
 +
 +
function ignore_tag_a( $list ) {
 +
  $list[] = 'tag-a';
 +
  return $list;
 +
}
 +
 +
=== Unclosed Shortcodes ===
 +
 +
In certain cases the shortcode parser cannot correctly deal with the use of both closed and unclosed shortcodes. For instance in this case the parser will only correctly identify the second instance of the shortcode:
 +
 +
[tag]
 +
[tag]
 +
    CONTENT
 +
[/tag]
 +
 +
However in this case the parser will identify both:
 +
 +
[tag]
 +
    CONTENT
 +
[/tag]
 +
[tag]
 +
 +
=== Hyphens ===
 +
 +
'''Note:''' The behavior described below involving shortcodes with hyphens ('-') still applies in WordPress 3+. This could be due to a bug in do_shortcode() or get_shortcode_regex().
 +
 +
Take caution when using hyphens in the name of your shortcodes. In the following instance WordPress may see the second opening shortcode as equivalent to the first (basically WordPress sees the first part before the hyphen):
 +
 +
[tag]
 +
[tag-a]
 +
 +
It all depends on which shortcode is defined first. If you are going to use hyphens then define the shortest shortcode first.
 +
 +
To avoid this, use an underscore or simply no separator:
 +
 +
[tag]
 +
[tag_a]
 +
 +
[tag]
 +
[taga]
 +
 +
If the first part of the shortcode is different from one another, you can get away with using hyphens:
 +
 +
[tag]
 +
[tagfoo-a]
 +
 +
'''Important:''' Using hyphens can have implications that you may not be aware of; such as if other installed shortcodes also are use hyphens, the use of generic words with hyphens may cause collisions (if shortcodes are used together within the same request):
 +
 +
// plugin-A
 +
[is-logged-in]
 +
 +
// plugin-B
 +
[is-admin]
 +
 +
=== Square Brackets ===
 +
 +
The shortcode parser does not accept square brackets within attributes. Thus the following will fail:
 +
 +
[tag attribute="[Some value]"]
 +
 +
Tags surrounded by cosmetic brackets are not yet fully supported by wptexturize() or its filters.  These codes may give unexpected results:
 +
 +
[I put random text near my captions. [caption]]
 +
 +
'''Note:''' these limitations may change in future versions of WordPress, you should test to be absolutely sure.
 +
 +
=== HTML ===
 +
 +
Starting with version 3.9.3, use of HTML is limited inside shortcode attributes.  For example, this shortcode will not work correctly because it contains a '&gt;' character:
 +
 +
[tag value1="35" value2="25" compare="&gt;"]
 +
 +
Version 4.0 is designed to allow validated HTML, so this will work:
 +
 +
[tag description="&lt;b&gt;Greetings&lt;/b&gt;"]
 +
 +
The suggested workaround for HTML limitations is to use HTML encoding for all user input, and then add HTML decoding in the custom shortcode handler.  Extra API functions are planned.
 +
 +
Full usage of HTML in shortcode attributes was never officially supported, and this will not be expanded in future versions.
 +
 +
Starting with version 4.2.3, similar limitations were placed on use of shortcodes inside HTML.  For example, this shortcode will not work correctly because it is nested inside a scripting attribute:
 +
 +
&lt;a onclick="[tag]"&gt;
 +
 +
The suggested workaround for dynamic attributes is to design a shortcode that outputs all needed HTML rather than just a single value.  This will work better:
 +
 +
[link onclick="tag"]
 +
 +
Also notice the following shortcode is no longer allowed because of incorrect attribute quoting:
 +
 +
&lt;a title="[tag attr="id"]"&gt;
 +
 +
The only way to parse this as valid HTML is to use single quotes and double quotes in a nested manner:
 +
 +
&lt;a title="[tag attr='id']"&gt;
 +
 +
=== Registration Count ===
 +
 +
The API is known to become unstable when registering hundreds of shortcodes.  Plugin authors should create solutions that rely on only a small number of shortcodes names.  This limitation might change in future versions.
 +
 +
 +
<div id="Formal_Syntax">
 +
== Formal Syntax ==
 +
</div>
 +
 +
WordPress shortcodes do not use special characters in the same way as HTML.  The square braces may seem magical at first glance, but they are not truly part of any language.  For example:
 +
 +
[gallery]
 +
 +
The gallery shortcode is parsed by the API as a special symbol because it is a registered shortcode.  On the other hand, square braces are simply ignored when a shortcode is not registered:
 +
 +
[randomthing]
 +
 +
The randomthing symbol and its square braces are ignored because they are not part of any registered shortcode.
 +
 +
In a perfect world, any [*] symbol could be handled by the API, but we have to consider the following challenges:  Square braces are allowed in HTML and are not always shortcodes, angle braces are allowed inside of shortcodes only in limited situations, and all of this code must run through multiple layers of customizeable filters and parsers before output.  Because of these language compatibility issues, square braces can't be magical.
 +
 +
The shortcode syntax uses these general parts:
 +
 +
[name attributes close]
 +
 +
[name attributes]Any HTML or shortcode may go here.[/name]
 +
 +
Escaped shortcodes are identical but have exactly two extra braces:
 +
 +
&#91;&#91;name attributes close]]
 +
 +
&#91;&#91;name attributes]Any HTML or shortcode may go here.[/name]]
 +
 +
Again, the shortcode name must be registered, otherwise all four examples would be ignored.
 +
 +
=== Names ===
 +
 +
Shortcode names must never contain the following characters:
 +
 +
* Square braces: [ ]
 +
* Angle braces: &lt; &gt;
 +
* Ampersand: &amp;
 +
* Forward slash: /
 +
* Whitespace: space linefeed tab
 +
* Non-printing characters: \x00 - \x20
 +
 +
It is recommended to also avoid quotes in the names of shortcodes:
 +
 +
* Quotes: ' "
 +
 +
=== Attributes ===
 +
 +
Attributes are optional.  A space is required between the shortcode name and the shortcode attributes.  When more than one attribute is used, each attribute must be separated by at least one space.
 +
 +
Each attribute should conform to one of these formats:
 +
 +
attribute_name = 'value'
 +
 +
attribute_name = "value"
 +
 +
attribute_name = value
 +
 +
"value"
 +
 +
value
 +
 +
Attribute names are optional and should contain only the following characters for compatibility across all platforms:
 +
 +
* Upper-case and lower-case letters: A-Z a-z
 +
* Digits: 0-9
 +
* Underscore: _
 +
* Hyphen: - (Not allowed before version 4.3.0)
 +
 +
Spaces are not allowed in attribute names.  Optional spaces may be used between the name and the = sign.  Optional spaces may also be used between the = sign and the value.
 +
 +
Attribute values must never contain the following characters:
 +
 +
* Square braces: [ ]
 +
* Quotes: " '
 +
 +
Unquoted values also must never contain spaces.
 +
 +
HTML characters &lt; and &gt; have only limited support in attributes.
 +
 +
The recommended method of escaping special characters in shortcode attributes is HTML encoding.  Most importantly, any user input appearing in a shortcode attribute must be escaped or stripped of special characters.
 +
 +
Note that double quotes are allowed inside of single-quoted values and vice versa, however this is not recommended when dealing with user input.
 +
 +
The following characters, if they are not escaped within an attribute value, will be automatically stripped and converted to spaces:
 +
 +
* No-break space: \xC2\xA0
 +
* Zero-width space: \xE2\x80\x8B
 +
 +
=== Self-Closing ===
 +
 +
The self-closing marker, a single forward slash, is optional.  Space before the marker is optional.  Spaces are not allowed after the marker.
 +
 +
[example /]
 +
 +
The self-closing marker is purely cosmetic and has no effect except that it will force the shortcode parser to ignore any closing tag that follows it.
 +
 +
The enclosing type shortcodes may not use a self-closing marker.
 +
 +
=== Escaping ===
 +
 +
WordPress attempts to insert curly quotes between the [name] and [/name] tags.  It will process that content just like any other.  As of 4.0.1, unregistered shortcodes are also "texturized" and this may give unexpected curly quotes:
 +
 +
[randomthing param="test"]
 +
 +
A better example would be:
 +
 +
&lt;code&gt;[randomthing param="test"]&lt;/code&gt;
 +
 +
The &lt;code&gt; element is always avoided for the sake of curly quotes.
 +
 +
Registered shortcodes are still processed inside of &lt;code&gt; elements.  To escape a registered shortcode for display on your website, the syntax becomes:
 +
 +
&#91;&#91;caption param="test"]]
 +
 +
... which will output ...
 +
 +
[caption param="test"]
 +
 +
The &lt;code&gt; element is optional in that situation.
 +
 +
 +
== History ==
 +
 +
The Shortcode API was introduced in WordPress 2.5.
  
 
<div id=External_Resources"">
 
<div id=External_Resources"">
267行目: 578行目:
 
</div>
 
</div>
  
* [http://xavisys.com/wordpress-25-shortcodes/ Shortcode summary by  Aaron D. Campbell] に、ショートコードの説明およびサンプルが掲載されています。javascriptを使用して、ショートコードをメタボックスに組み込んで編集者へと送信するサンプルも含まれています。
+
* [http://generatewp.com/shortcodes/ WordPress Shortcodes Generator]
 +
* [http://solislab.com/how-to-make-shortcodes-user-friendly/ Make Shortcodes User-Friendly] - Explains how to add buttons to the rich-text editor so that users don't have to memorize shortcodes and insert them manually.
 +
* [http://bluedogwebservices.com/wordpress-25-shortcodes/ Shortcode summary by  Aaron D. Campbell] に、ショートコードの説明およびサンプルが掲載されています。JavaScript を使用してショートコードをメタボックスに組み込み、エディターへ送信するサンプルも含まれています。
 +
* [http://wordpress.org/extend/plugins/iblocks/ Innovative WordPress Shortcodes In Action] - a WordPress plugin that shows you how to effectively use shortcodes to change your post content designs.
 
* [http://planetozh.com/blog/2008/03/wordpress-25-shortcodes-api-overview/ WordPress Shortcode API Overview] - explanations on usage and example of plugin using shortcodes.
 
* [http://planetozh.com/blog/2008/03/wordpress-25-shortcodes-api-overview/ WordPress Shortcode API Overview] - explanations on usage and example of plugin using shortcodes.
* [http://wordpress.org/extend/plugins/bbcode/ Simple shortcode-powered BBCode plugin] に、ショートコードを用いて、BBコードをサポートするプラグインが紹介されています。ショートコードの動作を見るのに良いでしょう。
+
* [http://wordpress.org/extend/plugins/bbcode/ Simple shortcode-powered BBCode plugin] - a simple plugin that adds support for BBCode via shortcode. A good way to see shortcodes in action.
 +
* [http://wordpress.org/extend/plugins/bbcode/ Simple shortcode-powered BBCode plugin] に、ショートコードを用いて BBCode をサポートするプラグインが紹介されています。ショートコードの動作を見るのに良いでしょう。
 +
* [http://themocracy.com/2010/03/a-flickr-badge-using-wordpress-shortcodes/ A Flickr Badge using WordPress Shortcodes] - a demonstration of how to pass variables to shortcode handler functions.
 +
* [http://aaron.jorb.in/2010/wordpress-shortcodes-a-how-to-by-example/ Three Simple Sample Shortcodes] - Three Sample Shortcodes and an explanation for how they work by Aaron Jorbin.
 +
* [http://wptricks.net/added-permalinks-shortcode-on-wordpress/ Added Permalinks Shortcode] Simple Tutorial how to added Permalinks Shortcode on WordPress
 +
 
 +
<div id="Default Shortcodes">
 +
== デフォルトで使えるショートコード ==
 +
</div>
 +
 
 +
* <code>[[Audio Shortcode|[audio]]] /[[:en:Audio Shortcode|en]]</code>
 +
* <code>[[Caption Shortcode|[wp_caption]]] /[[:en:Caption Shortcode|en]] </code>
 +
* <code>[[Caption Shortcode|[caption]]] /[[:en:Caption Shortcode|en]]</code>
 +
* <code>[[Embed Shortcode|[embed]]] /[[:en:Embed Shortcode|en]]</code>
 +
* <code>[[Gallery Shortcode|[gallery]]] /[[:en:Gallery Shortcode|en]]</code>
 +
* <code>[[Video Shortcode|[video]]] /[[:en:Video Shortcode|en]]</code>
 +
* <code>[[Playlist Shortcode|[playlist]]] /[[:en:Playlist Shortcode|en]]</code>
  
 
== 活用事例 ==
 
== 活用事例 ==
277行目: 607行目:
  
 
== 変更履歴 ==
 
== 変更履歴 ==
 +
 
* [[Version 2.5.1|2.5.1]] :  
 
* [[Version 2.5.1|2.5.1]] :  
 
** [[#do_shortcode()|<code>do_shortcode()</code>]] の <code>the_content</code> でのプライオリティが 11 になりました。
 
** [[#do_shortcode()|<code>do_shortcode()</code>]] の <code>the_content</code> でのプライオリティが 11 になりました。
282行目: 613行目:
 
* [[Version 2.5|2.5]] : 新規機能
 
* [[Version 2.5|2.5]] : 新規機能
  
 
+
<div id="Related">
== 関連 ==
+
== 関連項目 ==
 +
</div>
  
 
{{Shortcode Tags}}
 
{{Shortcode Tags}}
  
{{原文|Shortcode API|65562}}<!-- 22:52, December 29, 2008 Ozh 版 -->
+
{{原文|Shortcode API|154257}} <!-- 01:16, 2 October 2015 Miqrogroove 版 -->
  
 
{{DEFAULTSORT:しよおとこおとAPI}}
 
{{DEFAULTSORT:しよおとこおとAPI}}
297行目: 629行目:
  
 
[[en:Shortcode API]]
 
[[en:Shortcode API]]
 +
[[it:Le API degli Shortcode]]
 +
[[pt-br:Shortcode API]]
 +
[[ru:Shortcode API]]

2015年10月10日 (土) 20:53時点における版

このページ「ショートコード API」は制限事項節以降が未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

ショートコード API は、投稿や固定ページで使える WordPress のショートコードを作るための関数のシンプルなセットです。例えば次のショートコードは(投稿や固定ページの本文に書くと)その投稿や固定ページへ添付されたイメージのギャラリーを追加します:

[gallery]

この API を使ってプラグイン開発者は特別な種類のコンテンツ(例えばフォームやコンテンツ生成器)を作成できます。ユーザーはそれに対応するショートコードをページのテキストに追加して、そのコンテンツをページへ追加できます。

ショートコード API は次の例のように属性をサポートするショートコードも簡単に作成できます:

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

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

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

// [foobar]
function foobar_func( $atts ){
	return "foo and bar";
}
add_shortcode( 'foobar', 'foobar_func' );

これで [foobar] ショートコードが作られて、使用すると次の値を返します: foo and bar

属性を持つショートコードの場合は:

// [bartag foo="foo-value"]
function bartag_func( $atts ) {
    $a = shortcode_atts( array(
        'foo' => 'something',
        'bar' => 'something else',
    ), $atts );

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

このコードは、[bartag] ショートコードを作成し、2つの属性 foobar をサポートします。どちらの属性もオプションで、省略するとデフォルト値 foo="something"bar="something else" が入ります。そして foo = {foo 属性の値} を返します。

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

ショートコードの名前は英小文字、数字、下線を使う必要があります。特にハイフン(ダッシュ)には注意して、使わないのが賢明です。

ショートコードハンドラーを登録するには add_shortcode 関数を使います。この関数には2つのパラメータ、ショートコード名(投稿の本文で使う文字列)とコールバック関数の名前を渡します。

ショートコードのコールバック関数には3つのパラメータが渡されます。いくつ使うか、どれも使わないかはあなたの自由です。

  • $atts - 属性の連想配列、または空文字列(属性が省略された場合)
  • $content - 囲まれたコンテンツ(囲み型ショートコードとして使われた場合)
  • $tag - ショートコードのタグ。共有コールバック関数の場合に便利です

ショートコードハンドラーを登録する API 呼び出しは例えば次のようになります;

add_shortcode( 'myshortcode', 'my_shortcode_handler' );

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

次のようにショートコードの属性が入力されたとしましょう:

[myshortcode foo="bar" bar="bing"]

属性は次のような連想配列に変換され、$atts パラメータとしてハンドラー関数へ渡されます:

array( 'foo' => 'bar', 'bar' => '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' ) なら、結果の $aarray( 'title' => 'My Title', 'foo' => 456 ) になります。$atts['foo'] の値はデフォルト値 123 を上書きします。$atts['title'] は設定されていないので、デフォルト値 'My Title' が使用されます。デフォルト配列には 'bar' 要素がないので、結果に含まれません。

属性の名前はハンドラー関数へ渡される前にいつも小文字へ変換されます。値はそのままです。[myshortcode FOO="BAR"]$atts = array( 'foo' => 'BAR' ) になります。

ショートコードハンドラーでデフォルトを宣言して属性をパースする推奨のコード形式は以下のとおりです:

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

これは属性をパースし、デフォルトを設定し、サポートされない属性を除去し、結果をローカルの配列変数 $a へ入れます。その配列は属性がキーになります($a['attr_1']$a['attr_2'] など)。見方を変えると、デフォルトの配列はローカル変数の宣言のリストみたいなものです。


重要なヒント - $atts の属性名にキャメルケースや大文字を使わない 
$atts の値は shortcode_atts( array( 'attr_1' => 'attr_1 default', // ...etc ), $atts ) の処理前に小文字にされているので、小文字だけを使うようにしましょう。


出力

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

ショートコードは wpautop および wptexturize による投稿の整形適用後にパースされます(2.5.02.5.1 の違いについては後の注記を参照してください)。つまりショートコードが出力した HTML には、例えば曲線形のクォートが適用されず、p タグや br タグが追加されません。ショートコードの出力を整形したい場合は、ショートコードハンドラーから出力を返すときに wpautop()wptexturize() を直接呼び出す必要があります。

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

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

ショートコードが大量の HTML を生成する場合、次のように ob_start を使って出力を取り込んでから文字列へ変換することができます:

function my_shortcode() {
	ob_start();
	?> <HTML> <here> ... <?php
	return ob_get_clean();
}


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

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

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

function my_shortcode_handler( $atts, $content = null )

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

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

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

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

これを次のように使用すると:

[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: [myshortcode][/caption]

出力はこうなるでしょう:

<span class="caption">Caption: [myshortcode]</span>

囲み型ショートコードが出力に他のショートコードを許可する場合、ハンドラー関数が do_shortcode() を再帰的に呼び出すことができます。

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

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

<span class="caption">Caption: myshortcode のハンドラー関数の結果</span>

パーサーは同じショートコードの囲み型と自己完結型のミックスを、そうして欲しいようには処理しません。例えば次のように書いたとします:

[myshortcode example='non-enclosing' /] non-enclosed content [myshortcode] enclosed content [/myshortcode]

これを「 non-enclosed content 」というテキストで区切られた2つのショートコードとして処理するのではなく、パーサーは「 non-enclosed content [myshortcode] enclosed content 」を囲むひとつのショートコードとして処理します。

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

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

これで次のようなコンテンツを処理させると:

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

次のように出力されます:

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

その他の機能

  • パーサーは [myshortcode /] のような xhtml スタイルのショートコードをサポートしていますが、これはオプションです。
  • ショートコードマクロの属性の値にはシングルクォートとダブルクォートのどちらも使えます。属性の値が空白を含まない場合はクォートを省略できます。[myshortcode foo='123' bar=456][myshortcode foo="123" bar="456"] と同等です。参考:最後尾の属性の値はスラッシュ「/」で終わることができません。ひとつ前に説明した機能がそのスラッシュを消してしまうためです。
  • 古くてアドホックなショートコードとの後方互換性のため、属性名を省略することができます。属性名がない場合は位置を表す数値キーをつけて $atts 配列へ入れられます。例えば、[myshortcode 123]$atts = array( 0 => 123 ) を生成します。属性名を省略した属性と属性名のある属性を混ぜて使うことができます。そして値が空白や他の特殊文字を含む場合はクォートを使用することができます。

関数リファレンス

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

add_shortcode()

function add_shortcode( $tag, $func )

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

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

remove_shortcode()

function remove_shortcode( $tag )

既存のショートコードを抹消します。$tagadd_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]
   [tag-b]
      [tag-c]
   [/tag-b]
[/tag-a]

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

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

これは do_shortcode() で使われる文脈自由正規表現パーサーの制限によるものです。このパーサーはとても高速ですが入れ子のレベルを数えることができません。そのためこの場合にはそれぞれの開始タグを正しい終了タグとマッチさせることができません。

In future versions of WordPress, it may be necessary for plugins having a nested shortcode syntax to ensure that the wptexturize() processor does not interfere with the inner codes. It is recommended that for such complex syntax, the no_texturize_shortcodes /en filter should be used on the outer tags. In the examples used here, tag-a should be added to the list of shortcodes to not texturize. If the contents of tag-a or tag-b still need to be texturized, then you can call wptexturize() before calling do_shortcode() as described above.

Unregistered Names

Some plugin authors have chosen a strategy of not registering shortcode names, for example to disable a nested shortcode until the parent shortcode's handler function is called. This may have unintended consequences, such as failure to parse shortcode attribute values. For example:

[tag-a unit="north"]
   [tag-b size="24"]
      [tag-c color="red"]
   [/tag-b]
[/tag-a]

Starting with version 4.0.1, if a plugin fails to register tag-b and tag-c as valid shortcodes, the wptexturize() processor will output the following text prior to any shortcode being parsed:

[tag-a unit="north"]
   [tag-b size=&#8221;24&#8221;]
      [tag-c color=&#8221;red&#8221;]
   [/tag-b]
[/tag-a]

Unregistered shortcodes should be considered normal plain text that have no special meaning, and the practice of using unregistered shortcodes is discouraged. If you must enclose raw code between shortcode tags, at least consider using the no_texturize_shortcodes /en filter to prevent texturization of the contents of tag-a:

add_shortcode( 'tag-a', 'my_tag_a_handler' );
add_filter( 'no_texturize_shortcodes', 'ignore_tag_a' );

function ignore_tag_a( $list ) {
  $list[] = 'tag-a';
  return $list;
}

Unclosed Shortcodes

In certain cases the shortcode parser cannot correctly deal with the use of both closed and unclosed shortcodes. For instance in this case the parser will only correctly identify the second instance of the shortcode:

[tag]
[tag]
   CONTENT
[/tag]

However in this case the parser will identify both:

[tag]
   CONTENT
[/tag]
[tag]

Hyphens

Note: The behavior described below involving shortcodes with hyphens ('-') still applies in WordPress 3+. This could be due to a bug in do_shortcode() or get_shortcode_regex().

Take caution when using hyphens in the name of your shortcodes. In the following instance WordPress may see the second opening shortcode as equivalent to the first (basically WordPress sees the first part before the hyphen):

[tag]
[tag-a]

It all depends on which shortcode is defined first. If you are going to use hyphens then define the shortest shortcode first.

To avoid this, use an underscore or simply no separator:

[tag]
[tag_a]

[tag]
[taga]

If the first part of the shortcode is different from one another, you can get away with using hyphens:

[tag]
[tagfoo-a]

Important: Using hyphens can have implications that you may not be aware of; such as if other installed shortcodes also are use hyphens, the use of generic words with hyphens may cause collisions (if shortcodes are used together within the same request):

// plugin-A
[is-logged-in]

// plugin-B
[is-admin]

Square Brackets

The shortcode parser does not accept square brackets within attributes. Thus the following will fail:

[tag attribute="[Some value]"]

Tags surrounded by cosmetic brackets are not yet fully supported by wptexturize() or its filters. These codes may give unexpected results:

[I put random text near my captions. [caption]]

Note: these limitations may change in future versions of WordPress, you should test to be absolutely sure.

HTML

Starting with version 3.9.3, use of HTML is limited inside shortcode attributes. For example, this shortcode will not work correctly because it contains a '>' character:

[tag value1="35" value2="25" compare=">"]

Version 4.0 is designed to allow validated HTML, so this will work:

[tag description="<b>Greetings</b>"]

The suggested workaround for HTML limitations is to use HTML encoding for all user input, and then add HTML decoding in the custom shortcode handler. Extra API functions are planned.

Full usage of HTML in shortcode attributes was never officially supported, and this will not be expanded in future versions.

Starting with version 4.2.3, similar limitations were placed on use of shortcodes inside HTML. For example, this shortcode will not work correctly because it is nested inside a scripting attribute:

<a onclick="[tag]">

The suggested workaround for dynamic attributes is to design a shortcode that outputs all needed HTML rather than just a single value. This will work better:

[link onclick="tag"]

Also notice the following shortcode is no longer allowed because of incorrect attribute quoting:

<a title="[tag attr="id"]">

The only way to parse this as valid HTML is to use single quotes and double quotes in a nested manner:

<a title="[tag attr='id']">

Registration Count

The API is known to become unstable when registering hundreds of shortcodes. Plugin authors should create solutions that rely on only a small number of shortcodes names. This limitation might change in future versions.


Formal Syntax

WordPress shortcodes do not use special characters in the same way as HTML. The square braces may seem magical at first glance, but they are not truly part of any language. For example:

[gallery]

The gallery shortcode is parsed by the API as a special symbol because it is a registered shortcode. On the other hand, square braces are simply ignored when a shortcode is not registered:

[randomthing]

The randomthing symbol and its square braces are ignored because they are not part of any registered shortcode.

In a perfect world, any [*] symbol could be handled by the API, but we have to consider the following challenges: Square braces are allowed in HTML and are not always shortcodes, angle braces are allowed inside of shortcodes only in limited situations, and all of this code must run through multiple layers of customizeable filters and parsers before output. Because of these language compatibility issues, square braces can't be magical.

The shortcode syntax uses these general parts:

[name attributes close]
[name attributes]Any HTML or shortcode may go here.[/name]

Escaped shortcodes are identical but have exactly two extra braces:

[[name attributes close]]
[[name attributes]Any HTML or shortcode may go here.[/name]]

Again, the shortcode name must be registered, otherwise all four examples would be ignored.

Names

Shortcode names must never contain the following characters:

  • Square braces: [ ]
  • Angle braces: < >
  • Ampersand: &
  • Forward slash: /
  • Whitespace: space linefeed tab
  • Non-printing characters: \x00 - \x20

It is recommended to also avoid quotes in the names of shortcodes:

  • Quotes: ' "

Attributes

Attributes are optional. A space is required between the shortcode name and the shortcode attributes. When more than one attribute is used, each attribute must be separated by at least one space.

Each attribute should conform to one of these formats:

attribute_name = 'value'
attribute_name = "value"
attribute_name = value
"value"
value

Attribute names are optional and should contain only the following characters for compatibility across all platforms:

  • Upper-case and lower-case letters: A-Z a-z
  • Digits: 0-9
  • Underscore: _
  • Hyphen: - (Not allowed before version 4.3.0)

Spaces are not allowed in attribute names. Optional spaces may be used between the name and the = sign. Optional spaces may also be used between the = sign and the value.

Attribute values must never contain the following characters:

  • Square braces: [ ]
  • Quotes: " '

Unquoted values also must never contain spaces.

HTML characters < and > have only limited support in attributes.

The recommended method of escaping special characters in shortcode attributes is HTML encoding. Most importantly, any user input appearing in a shortcode attribute must be escaped or stripped of special characters.

Note that double quotes are allowed inside of single-quoted values and vice versa, however this is not recommended when dealing with user input.

The following characters, if they are not escaped within an attribute value, will be automatically stripped and converted to spaces:

  • No-break space: \xC2\xA0
  • Zero-width space: \xE2\x80\x8B

Self-Closing

The self-closing marker, a single forward slash, is optional. Space before the marker is optional. Spaces are not allowed after the marker.

[example /]

The self-closing marker is purely cosmetic and has no effect except that it will force the shortcode parser to ignore any closing tag that follows it.

The enclosing type shortcodes may not use a self-closing marker.

Escaping

WordPress attempts to insert curly quotes between the [name] and [/name] tags. It will process that content just like any other. As of 4.0.1, unregistered shortcodes are also "texturized" and this may give unexpected curly quotes:

[randomthing param="test"]

A better example would be:

<code>[randomthing param="test"]</code>

The <code> element is always avoided for the sake of curly quotes.

Registered shortcodes are still processed inside of <code> elements. To escape a registered shortcode for display on your website, the syntax becomes:

[[caption param="test"]]

... which will output ...

[caption param="test"]

The <code> element is optional in that situation.


History

The Shortcode API was introduced in WordPress 2.5.

外部リソース

デフォルトで使えるショートコード

活用事例

変更履歴

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


ショートコード: do_shortcode(), add_shortcode(), remove_shortcode(), remove_all_shortcodes(), shortcode_atts(), strip_shortcodes(), shortcode_exists(), has_shortcode(), get_shortcode_regex(), wp_audio_shortcode(), wp_video_shortcode(), フィルター no_texturize_shortcodes /en


最新英語版: WordPress Codex » Shortcode API最新版との差分