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

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(en:Shortcode API 01:16, 2 October 2015 Miqrogroove 版を反映。)
(en:Shortcode API 12:33, 8 April 2018 Feindbild 版をマージ、翻訳。)
 
(2人の利用者による、間の6版が非表示)
1行目: 1行目:
{{NeedTrans|[[#Limitations|制限事項]]節以降が}}
+
'''ショートコード API''' は、投稿や固定ページで使える WordPress の[[ショートコード]]を作るための関数のシンプルなセットです。例えば次のショートコードは(投稿や固定ページの本文に書くと)その投稿や固定ページへ添付されたイメージのギャラリーを追加します:
 
+
'''ショートコード API''' は、投稿や固定ページで使える WordPress の[[ショートコード]]を作るための関数のシンプルなセットです。例えば次のショートコードは(投稿や固定ページの本文に書くと)その投稿や固定ページへ添付されたイメージのギャラリーを追加します:
+
  
 
  [gallery]
 
  [gallery]
7行目: 5行目:
 
この API を使ってプラグイン開発者は特別な種類のコンテンツ(例えばフォームやコンテンツ生成器)を作成できます。ユーザーはそれに対応するショートコードをページのテキストに追加して、そのコンテンツをページへ追加できます。
 
この API を使ってプラグイン開発者は特別な種類のコンテンツ(例えばフォームやコンテンツ生成器)を作成できます。ユーザーはそれに対応するショートコードをページのテキストに追加して、そのコンテンツをページへ追加できます。
  
ショートコード API は次の例のように属性をサポートするショートコードも簡単に作成できます:
+
ショートコード API は次の例のように属性をサポートするショートコードも簡単に作成できます:
  
 
  [gallery id="123" size="medium"]
 
  [gallery id="123" size="medium"]
13行目: 11行目:
 
API が手の込んだパーシング(構文解析)を処理するので、いちいちショートコードに独自の正規表現を書く必要はありません。属性にデフォルトを設定し取り込むヘルパー関数が含まれています。API は自己完結型ショートコードと囲み型ショートコードの両方をサポートします。
 
API が手の込んだパーシング(構文解析)を処理するので、いちいちショートコードに独自の正規表現を書く必要はありません。属性にデフォルトを設定し取り込むヘルパー関数が含まれています。API は自己完結型ショートコードと囲み型ショートコードの両方をサポートします。
  
手っ取り早く使い始めたい人のために、ショートコードを作成するのに最低限必要な PHP コードの例を示します:
+
手っ取り早く使い始めたい人のために、ショートコードを作成するのに最低限必要な PHP コードの例を示します:
  
 
<pre>
 
<pre>
23行目: 21行目:
 
</pre>
 
</pre>
  
これで <code>[foobar]</code> ショートコードが作られて、使用すると次の値を返します: foo and bar
+
これで <code>[foobar]</code> ショートコードが作られて、使用すると次の値を返します: foo and bar
  
属性を持つショートコードの場合は:
+
属性を持つショートコードの場合は:
  
 
<pre>
 
<pre>
64行目: 62行目:
 
[[テンプレートタグ/the content|the_content]] が表示されるとき、ショートコード API は <code>[myshortcode]</code> のような登録済みショートコードをパースして、属性と (存在するならば) コンテンツを分離してパースし、対応するショートコードハンドラー関数へ渡します。ショートコードハンドラが''返した''(表示されたのではなく)文字列はショートコードの代わりにページの本文へ挿入されます。
 
[[テンプレートタグ/the content|the_content]] が表示されるとき、ショートコード API は <code>[myshortcode]</code> のような登録済みショートコードをパースして、属性と (存在するならば) コンテンツを分離してパースし、対応するショートコードハンドラー関数へ渡します。ショートコードハンドラが''返した''(表示されたのではなく)文字列はショートコードの代わりにページの本文へ挿入されます。
  
次のようにショートコードの属性が入力されたとしましょう:
+
次のようにショートコードの属性が入力されたとしましょう:
  
 
  [myshortcode foo="bar" bar="bing"]
 
  [myshortcode foo="bar" bar="bing"]
  
属性は次のような連想配列に変換され、<code>$atts</code> パラメータとしてハンドラー関数へ渡されます:
+
属性は次のような連想配列に変換され、<code>$atts</code> パラメータとしてハンドラー関数へ渡されます:
  
 
  array( 'foo' => 'bar', 'bar' => 'bing' )
 
  array( 'foo' => 'bar', 'bar' => 'bing' )
86行目: 84行目:
 
省略された属性にデフォルト値を付与し、ショートコードが認識しない属性をすべて取り除くために、API には shortcode_atts() 関数が用意されています。
 
省略された属性にデフォルト値を付与し、ショートコードが認識しない属性をすべて取り除くために、API には shortcode_atts() 関数が用意されています。
  
<code>[[関数リファレンス/shortcode_atts|shortcode_atts()]]</code> は <code>[[関数リファレンス/wp_parse_args|wp_parse_args]]</code> 関数に似ていますが、いくつか重要な違いがあります。パラメータは以下のとおりです:
+
<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> 配列に値が存在すればその値を上書きした、正規化された配列を返します。例を以下に示します:
  
 
<pre>
 
<pre>
103行目: 101行目:
 
属性の名前はハンドラー関数へ渡される前にいつも小文字へ変換されます。値はそのままです。<code>[myshortcode FOO="BAR"]</code> は <code>$atts = array( 'foo' => 'BAR' )</code> になります。
 
属性の名前はハンドラー関数へ渡される前にいつも小文字へ変換されます。値はそのままです。<code>[myshortcode FOO="BAR"]</code> は <code>$atts = array( 'foo' => 'BAR' )</code> になります。
  
ショートコードハンドラーでデフォルトを宣言して属性をパースする推奨のコード形式は以下のとおりです:
+
ショートコードハンドラーでデフォルトを宣言して属性をパースする推奨のコード形式は以下のとおりです:
  
 
<pre>
 
<pre>
147行目: 145行目:
 
<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]] で修正されました。
+
参考: [[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> を使って出力を取り込んでから文字列へ変換することができます:
+
ショートコードが大量の HTML を生成する場合、次のように <code>ob_start</code> を使って出力を取り込んでから文字列へ変換することができます:
  
 
<pre>
 
<pre>
170行目: 168行目:
 
  function my_shortcode_handler( $atts, $content = null )
 
  function my_shortcode_handler( $atts, $content = null )
  
こうすれば <code>is_null( $content )</code> を使用して囲み型と自己完結型を区別することができます。
+
こうすれば <code>empty( $content )</code> を使用して囲み型と自己完結型を区別することができます。
  
 
コンテンツがタグで囲まれている場合は、そのコンテンツを含むショートコードマクロ全体が関数の出力で置き換えられます。生のコンテンツ文字列に必要なエスケープやエンコードを適用し、出力に含める処理は、ハンドラー関数が行う必要があります。
 
コンテンツがタグで囲まれている場合は、そのコンテンツを含むショートコードマクロ全体が関数の出力で置き換えられます。生のコンテンツ文字列に必要なエスケープやエンコードを適用し、出力に含める処理は、ハンドラー関数が行う必要があります。
  
囲み型ショートコードの例を以下に示します:
+
囲み型ショートコードの例を以下に示します:
  
 
<pre>
 
<pre>
182行目: 180行目:
 
</pre>
 
</pre>
  
これを次のように使用すると:
+
これを次のように使用すると:
  
 
  [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>
200行目: 198行目:
 
これは意図したとおり、またはそうではない動作かもしれません。ショートコードが生の HTML の出力を許可しないようにするには、エスケープまたはフィルター関数を使用してから結果を返すようにしてください。
 
これは意図したとおり、またはそうではない動作かもしれません。ショートコードが生の HTML の出力を許可しないようにするには、エスケープまたはフィルター関数を使用してから結果を返すようにしてください。
  
ショートコードのパーサーは投稿コンテンツを一度だけパースします。つまりショートコードハンドラーの <code>$content</code> パラメータが別のショートコードを含む場合、それはパースされません。次の場合:
+
ショートコードのパーサーは投稿コンテンツを一度だけパースします。つまりショートコードハンドラーの <code>$content</code> パラメータが別のショートコードを含む場合、それはパースされません。次の場合:
  
 
  [caption]Caption: [myshortcode][/caption]
 
  [caption]Caption: [myshortcode][/caption]
  
出力はこうなるでしょう:
+
出力はこうなるでしょう:
  
 
<pre class="screen"><span class="caption">Caption: [myshortcode]</span></pre>
 
<pre class="screen"><span class="caption">Caption: [myshortcode]</span></pre>
220行目: 218行目:
 
<pre class="screen"><span class="caption">Caption: myshortcode のハンドラー関数の結果</span></pre>
 
<pre class="screen"><span class="caption">Caption: myshortcode のハンドラー関数の結果</span></pre>
  
パーサーは同じショートコードの囲み型と自己完結型のミックスを、そうして欲しいようには処理しません。例えば次のように書いたとします:
+
パーサーは同じショートコードの囲み型と自己完結型のミックスを、そうして欲しいようには処理しません。例えば次のように書いたとします:
  
 
  [myshortcode example='non-enclosing' /] non-enclosed content [myshortcode] enclosed content [/myshortcode]
 
  [myshortcode example='non-enclosing' /] non-enclosed content [myshortcode] enclosed content [/myshortcode]
226行目: 224行目:
 
これを「 non-enclosed content 」というテキストで区切られた2つのショートコードとして処理するのではなく、パーサーは「 non-enclosed content [myshortcode] enclosed content 」を囲むひとつのショートコードとして処理します。
 
これを「 non-enclosed content 」というテキストで区切られた2つのショートコードとして処理するのではなく、パーサーは「 non-enclosed content [myshortcode] enclosed content 」を囲むひとつのショートコードとして処理します。
  
囲み型ショートコードは自己完結型ショートコードと同様に属性をサポートします。<code>class</code> 属性をサポートするように改良された <code>caption_shortcode()</code> の例を以下に示します:
+
囲み型ショートコードは自己完結型ショートコードと同様に属性をサポートします。<code>class</code> 属性をサポートするように改良された <code>caption_shortcode()</code> の例を以下に示します:
  
 
<pre>
 
<pre>
238行目: 236行目:
 
</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>
252行目: 250行目:
 
* パーサーは <code>[myshortcode /]</code> のような xhtml スタイルのショートコードをサポートしていますが、これはオプションです。
 
* パーサーは <code>[myshortcode /]</code> のような xhtml スタイルのショートコードをサポートしていますが、これはオプションです。
  
* ショートコードマクロの属性の値にはシングルクォートとダブルクォートのどちらも使えます。属性の値が空白を含まない場合はクォートを省略できます。<code>[myshortcode foo='123' bar=456]</code> は <code>[myshortcode foo="123" bar="456"]</code> と同等です。参考:最後尾の属性の値はスラッシュ「/」で終わることができません。ひとつ前に説明した機能がそのスラッシュを消してしまうためです。
+
* ショートコードマクロの属性の値にはシングルクォートとダブルクォートのどちらも使えます。属性の値が空白を含まない場合はクォートを省略できます。<code>[myshortcode foo='123' bar=456]</code> は <code>[myshortcode foo="123" bar="456"]</code> と同等です。 '''参考:''' 最後尾の属性の値はスラッシュ「/」で終わることができません。ひとつ前に説明した機能がそのスラッシュを消してしまうためです。
  
 
* 古くてアドホックなショートコードとの後方互換性のため、属性名を省略することができます。属性名がない場合は位置を表す数値キーをつけて <code>$atts</code> 配列へ入れられます。例えば、<code>[myshortcode 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/trunk/tests/shortcode.php で公開されています。
  
 
<div id="Function_reference">
 
<div id="Function_reference">
 +
 
== 関数リファレンス ==
 
== 関数リファレンス ==
 
</div>
 
</div>
307行目: 306行目:
 
</div>
 
</div>
  
ショートコードパーサーは、再帰的に <code>do_shortcode()</code> を呼び出すことでハンドラー関数がサポートしていれば、入れ子になったショートコードマクロを正しく処理することができます:
+
ショートコードパーサーは、再帰的に <code>do_shortcode()</code> を呼び出すことでハンドラー関数がサポートしていれば、入れ子になったショートコードマクロを正しく処理することができます:
  
  [tag-a]
+
  [tag_a]
     [tag-b]
+
     [tag_b]
       [tag-c]
+
       [tag_c]
     [/tag-b]
+
     [/tag_b]
  [/tag-a]
+
  [/tag_a]
  
しかしショートコードマクロが同じ名前のマクロをもうひとつ囲むように使用するとパースに失敗します:
+
しかしショートコードマクロが同じ名前のマクロをもうひとつ囲むように使用するとパースに失敗します:
  
  [tag-a]
+
  [tag_a]
     [tag-a]
+
     [tag_a]
     [/tag-a]
+
     [/tag_a]
  [/tag-a]
+
  [/tag_a]
  
 
これは [[関数リファレンス/do_shortcode|<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.
+
WordPress の将来のバージョンでは、wptexturize() の処理が内側のコードを邪魔しないようにすることが、入れ子のショートコードを持つプラグインに対して求められるかもしれません。そういう複雑な構文の場合、外側のタグについて [[プラグイン API/フィルターフック一覧/no_texturize_shortcodes|no_texturize_shortcodes]] /[[:en:Plugin_API/Filter_Reference/no_texturize_shortcodes|en]] フィルターの適用が推奨されます。ここで用いた例でいうと、texturize しないショートコードのリストへ tag_a を追加すべきです。tag_a や tag_b のコンテンツを texturize する必要があるなら、上で説明したように [[関数リファレンス/do_shortcode|do_shortcode()]] の呼び出し前に [[関数リファレンス/wptexturize|wptexturize()]] を呼び出すことができます。
  
=== Unregistered Names ===
+
<div id="Unregistered_Names">
 +
=== 未登録のショートコード名 ===
 +
</div>
  
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_a unit="north"]
     [tag-b size="24"]
+
     [tag_b size="24"]
       [tag-c color="red"]
+
       [tag_c color="red"]
     [/tag-b]
+
     [/tag_b]
  [/tag-a]
+
  [/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:
+
バージョン 4.0.1 以降、プラグインが tag_b と tag_c を有効なショートコードとして登録し損なうと、wptexturize() の処理はショートコードのパースを始める前に次のようなテキストを出力します:
  
  [tag-a unit="north"]
+
  [tag_a unit="north"]
     [tag-b size=&amp;#8221;24&amp;#8221;]
+
     [tag_b size=&amp;#8221;24&amp;#8221;]
       [tag-c color=&amp;#8221;red&amp;#8221;]
+
       [tag_c color=&amp;#8221;red&amp;#8221;]
     [/tag-b]
+
     [/tag_b]
  [/tag-a]
+
  [/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:
+
未登録のショートコードは特別な意味を持たない普通のプレーンなテキストとして扱われるべきであり、ショートコードをわざと未登録にするのは勧められません。もしショートコードの間に生のコードをはさみ込む必要があるなら、少なくとも tag_a のコンテンツの texturize 処理を避けるために [[プラグイン API/フィルターフック一覧/no_texturize_shortcodes|no_texturize_shortcodes]] /[[:en:Plugin_API/Filter_Reference/no_texturize_shortcodes|en]] フィルターの使用を検討してください:
  
  add_shortcode( 'tag-a', 'my_tag_a_handler' );
+
  add_shortcode( 'tag_a', 'my_tag_a_handler' );
 
  add_filter( 'no_texturize_shortcodes', 'ignore_tag_a' );
 
  add_filter( 'no_texturize_shortcodes', 'ignore_tag_a' );
 
   
 
   
 
  function ignore_tag_a( $list ) {
 
  function ignore_tag_a( $list ) {
   $list[] = 'tag-a';
+
   $list[] = 'tag_a';
 
   return $list;
 
   return $list;
 
  }
 
  }
  
=== Unclosed Shortcodes ===
+
<div id="Unclosed_Shortcodes">
 +
=== 閉じないショートコード ===
 +
</div>
  
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:
+
ある状況ではショートコードのパーサーが閉じたショートコードと閉じないショートコードの両方を正しく処理できません。例えば次の場合、パーサーは2番目のショートコードだけを正しく識別します:
  
 
  [tag]
 
  [tag]
 
  [tag]
 
  [tag]
     CONTENT
+
     コンテンツ
 
  [/tag]
 
  [/tag]
  
However in this case the parser will identify both:
+
しかし次の場合はパーサーが両方とも識別します:
  
 
  [tag]
 
  [tag]
     CONTENT
+
     コンテンツ
 
  [/tag]
 
  [/tag]
 
  [tag]
 
  [tag]
  
=== Hyphens ===
+
<div id="Hyphens">
 +
=== ハイフン ===
 +
</div>
  
'''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().
+
'''参考:''' 以下で説明するハイフン ('-') を使ったショートコードに関する動作は WordPress 3 以上にも当てはまります。これは do_shortcode() 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):
+
ショートコードの名前にハイフンを使うときは注意してください。次の例では WordPress が2番目のショートコードを1番目と同じだと見る場合があります(WordPress は基本的にハイフンより前の部分を見ます):
  
 
  [tag]
 
  [tag]
 
  [tag-a]
 
  [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]
389行目: 394行目:
 
  [taga]
 
  [taga]
  
If the first part of the shortcode is different from one another, you can get away with using hyphens:
+
ショートコードの最初の部分がどれも異なっていれば、ハイフンを使っても問題ありません:
  
 
  [tag]
 
  [tag]
 
  [tagfoo-a]
 
  [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
 
  // plugin-A
402行目: 407行目:
 
  [is-admin]
 
  [is-admin]
  
=== Square Brackets ===
+
<div id="Square_Brackets">
 +
=== 角括弧 ===
 +
</div>
  
The shortcode parser does not accept square brackets within attributes. Thus the following will fail:
+
ショートコードのパーサーは属性に含まれる角括弧を受け付けません。そのため次の使い方は失敗します:
  
 
  [tag attribute="[Some value]"]
 
  [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:
+
飾りの角括弧 (cosmetic brackets) で囲まれたタグは wptexturize() やそのフィルターで完全にはサポートされていません。そのため次のコードは予想外の結果になるかもしれません:
  
 
  [I put random text near my captions. [caption]]
 
  [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.
+
'''参考:''' これらの制限は WordPress の将来のバージョンで変わるかもしれませんので、確実さを求めるならテストすべきです。
  
 
=== HTML ===
 
=== 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:
+
バージョン 3.9.3 から、ショートコードの属性内の HTML 使用は制限されるようになりました。例えば次のショートコードは「&gt;」文字を含むので正しく動作しません:
  
 
  [tag value1="35" value2="25" compare="&gt;"]
 
  [tag value1="35" value2="25" compare="&gt;"]
  
Version 4.0 is designed to allow validated HTML, so this will work:
+
バージョン 4.0 は予め認められた HTML を許すようになったので、次のコードは動作します:
  
 
  [tag description="&lt;b&gt;Greetings&lt;/b&gt;"]
 
  [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.
+
HTML の制限に対する推奨の回避方法は、すべてのユーザー入力に HTML エンコードを行った上で、カスタムショートコードハンドラー内で HTML デコードを行うというものです。拡張 API 関数が計画されています。
  
Full usage of HTML in shortcode attributes was never officially supported, and this will not be expanded in future versions.
+
ショートコード属性における HTML のフルサポートはこれまで公式に行われたことはなく、将来のバージョンで拡張される予定もありません。
  
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:
+
バージョン 4.2.3 からは、類似の制限が HTML 内でのショートコード利用に対しても行われました。例えば次のショートコードは、スクリプト属性の入れ子なので正しく動作しません:
  
 
  &lt;a onclick="[tag]"&gt;
 
  &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:
+
動的な属性値に対する推奨の回避方法は、ひとつだけ値を出力するのでなく必要な HTML 全体を出力するショートコードを設計するというものです。これは動くでしょう:
  
 
  [link onclick="tag"]
 
  [link onclick="tag"]
  
Also notice the following shortcode is no longer allowed because of incorrect attribute quoting:
+
また次のショートコードは属性のクォートが正しくないので使用できません:
  
 
  &lt;a title="[tag attr="id"]"&gt;
 
  &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:
+
これを正しい HTML としてパースする唯一の方法はシングルクォートとダブルクォートによる入れ子を使うというものです:
  
 
  &lt;a title="[tag attr='id']"&gt;
 
  &lt;a title="[tag attr='id']"&gt;
  
=== Registration Count ===
+
<div id="Registration_Count">
 +
=== 登録する個数 ===
 +
</div>
  
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.
+
ショートコードを数百個も登録すると API が不安定になることが知られています。プラグイン作者は少数のショートコード名だけで実現できる解決方法を用意すべきです。この制限は将来のバージョンで変わる可能性があります。
  
  
 
<div id="Formal_Syntax">
 
<div id="Formal_Syntax">
== Formal Syntax ==
+
== 正式な構文 ==
 
</div>
 
</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:
+
WordPress のショートコードは特殊文字の扱いが HTML とは異なります。角括弧は一見魔法のように思えますが、決してどんな言語の一部でもありません。例えば:
  
 
  [gallery]
 
  [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:
+
gallery ショートコードは登録済みショートコードなので API によって特別なシンボルとしてパースされます。一方、ショートコードが登録されていなければ角括弧は単に無視されます:
  
 
  [randomthing]
 
  [randomthing]
  
The randomthing symbol and its square braces are ignored because they are not part of any registered shortcode.
+
randomthing シンボルと角括弧は登録済みショートコードの一部ではないので無視されます。
  
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.
+
完璧な世界なら、どんな [*] シンボルも API で扱うことができるでしょう。しかし次のようなチャレンジを考えておく必要があります: 角括弧 ( <nowiki>[</nowiki>・<nowiki>]</nowiki> ) は HTML の中で使うことができて常にショートコードというわけではなく、山括弧 ( &lt;・&gt; ) は限られた状況でのみショートコード内で使うことができ、そしてショートコードは出力される前に何層ものカスタマイズ可能なフィルターとパーサーを潜り抜けなければなりません。こうした言語の互換性問題があるので、角括弧は魔法になれません。
  
The shortcode syntax uses these general parts:
+
ショートコード構文は次のような一般形を使います:
  
  [name attributes close]
+
  [名前 属性 閉じる]
  
  [name attributes]Any HTML or shortcode may go here.[/name]
+
  [名前 属性]任意の HTML やショートコードをここへ書くことができる。[/名前]
  
Escaped shortcodes are identical but have exactly two extra braces:
+
エスケープされたショートコードは角括弧がちょうど2つ多いだけで同じ形になります:
  
  &#91;&#91;name attributes close]]
+
  &#91;&#91;名前 属性 閉じる]]
  
  &#91;&#91;name attributes]Any HTML or shortcode may go here.[/name]]
+
  &#91;&#91;名前 属性]任意の HTML やショートコードをここへ書くことができる。[/名前]]
  
Again, the shortcode name must be registered, otherwise all four examples would be ignored.
+
繰り返しますがショートコード名は登録されている必要があります。さもないと4つの例はどれも無視されます。
  
=== Names ===
+
<div id="Names">
 +
=== ショートコード名 ===
 +
</div>
  
Shortcode names must never contain the following characters:
+
ショートコードの名前は以下の文字を絶対に含んではいけません:
  
* Square braces: [ ]
+
* 角括弧: <tt>[ ]</tt>
* Angle braces: &lt; &gt;
+
* 山括弧: <tt>&lt; &gt;</tt>
* Ampersand: &amp;
+
* アンパサンド: <tt>&amp;</tt>
* Forward slash: /
+
* スラッシュ: <tt>/</tt>
* Whitespace: space linefeed tab
+
* 空白: スペース 改行(ラインフィード) タブ
* Non-printing characters: \x00 - \x20
+
* 印刷できない文字: <tt>\x00 - \x20</tt>
  
It is recommended to also avoid quotes in the names of shortcodes:
+
クォートもショートコード名に含めないことを推奨します:
  
* Quotes: ' "
+
* クォート: <tt>' "</tt>
  
=== Attributes ===
+
<div id="Attributes">
 +
=== 属性 ===
 +
</div>
  
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.
+
属性はオプションです。ショートコード名とショートコードの属性の間にひとつスペースが必要です。2つ以上の属性を使うときは少なくともひとつのスペースで区切らなければなりません。
  
Each attribute should conform to one of these formats:
+
ひとつひとつの属性は次のいずれかの形式に従う必要があります:
  
  attribute_name = 'value'
+
  属性名 = ''
 +
 +
属性名 = "値"
 +
 +
属性名 = 値
 +
 +
"値"
 +
 +
  
attribute_name = "value"
+
属性名はオプションです。どのプラットフォームでも互換性を保つために次の文字だけを含む必要があります:
  
attribute_name = value
+
* 大文字と小文字のアルファベット: <tt>A-Z a-z</tt>
 +
* 数字: <tt>0-9</tt>
 +
* 下線: <tt>_</tt>
 +
* ハイフン: <tt>-</tt> (バージョン 4.3.0 より前は使えませんでした)
  
"value"
+
属性名にスペースは使えません。名前と <code>=</code> の間、それから <code>=</code> と値の間にスペースを入れるのは構いません。
  
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
+
* 角括弧: <tt>[ ]</tt>
* Digits: 0-9
+
* クォート: <tt>" '</tt>
* 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:
+
HTML 文字の <tt>&lt;</tt> と <tt>&gt;</tt> は属性の中で限定的な使用がサポートされます。
  
* Square braces: [ ]
+
ショートコード属性の中で特殊文字をエスケープする推奨の方法は HTML エンコードです。一番重要なのは、ショートコード属性にユーザーが入力した値を入れるなら必ずエスケープするか特殊文字を除去することです。
* 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.
+
* [[Wikipedia:ja:ノーブレークスペース|ノーブレークスペース]]: \xC2\xA0
 +
* ゼロ幅スペース: \xE2\x80\x8B
  
Note that double quotes are allowed inside of single-quoted values and vice versa, however this is not recommended when dealing with user input.
+
<div id="Self-Closing">
 
+
=== セルフクロージング ===
The following characters, if they are not escaped within an attribute value, will be automatically stripped and converted to spaces:
+
</div>
 
+
* 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 /]
 
  [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 ===
+
<div id="Escaping">
 +
=== エスケープ ===
 +
</div>
  
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:
+
WordPress [name] [/name] タグに挟まれた部分へ曲線形のクォートを入れようとします。他の部分と同じように処理するわけです。4.0.1 以降、未登録のショートコードも同様に「texturize」されるので予期しない曲線形のクォートが入る場合があります:
  
 
  [randomthing param="test"]
 
  [randomthing param="test"]
  
A better example would be:
+
良い例は次のようなものです:
  
 
  &lt;code&gt;[randomthing param="test"]&lt;/code&gt;
 
  &lt;code&gt;[randomthing param="test"]&lt;/code&gt;
  
The &lt;code&gt; element is always avoided for the sake of curly quotes.
+
<tt>&lt;code&gt;</tt> 要素はいつも texturize 処理の対象外になります。
  
Registered shortcodes are still processed inside of &lt;code&gt; elements.  To escape a registered shortcode for display on your website, the syntax becomes:
+
登録済みショートコードは &lt;code&gt; 要素の内側でも処理されます。登録済みショートコードを web サイトへ表示するためにエスケープする書き方は次のようになります:
  
 
  &#91;&#91;caption param="test"]]
 
  &#91;&#91;caption param="test"]]
  
... which will output ...
+
... このように出力されます ...
  
 
  [caption param="test"]
 
  [caption param="test"]
  
The &lt;code&gt; element is optional in that situation.
+
この状況では &lt;code&gt; 要素を使わなくても大丈夫です。
  
 +
囲み型ショートコードの場合は次の構文を使ってください:
  
== History ==
+
[[caption]My Caption[/caption]]
  
The Shortcode API was introduced in WordPress 2.5.
 
  
 
<div id=External_Resources"">
 
<div id=External_Resources"">
579行目: 598行目:
  
 
* [http://generatewp.com/shortcodes/ WordPress Shortcodes Generator]
 
* [http://generatewp.com/shortcodes/ WordPress Shortcodes Generator]
 +
* [https://www.nimbusthemes.com/add-shortcode-wordpress-snippet-generator/ Add Shortcode – WordPress Code Snippet Generator] - A snippet generator and full documentation about how to add the code to a WordPress website.
 
* [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://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://bluedogwebservices.com/wordpress-25-shortcodes/ Shortcode summary by  Aaron D. Campbell] に、ショートコードの説明およびサンプルが掲載されています。JavaScript を使用してショートコードをメタボックスに組み込み、エディターへ送信するサンプルも含まれています。
586行目: 606行目:
 
* [http://wordpress.org/extend/plugins/bbcode/ Simple shortcode-powered BBCode plugin] に、ショートコードを用いて BBCode をサポートするプラグインが紹介されています。ショートコードの動作を見るのに良いでしょう。
 
* [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://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
 
* [http://wptricks.net/added-permalinks-shortcode-on-wordpress/ Added Permalinks Shortcode] Simple Tutorial how to added Permalinks Shortcode on WordPress
  
594行目: 613行目:
  
 
* <code>[[Audio Shortcode|[audio]]] /[[:en:Audio Shortcode|en]]</code>
 
* <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>[[Caption Shortcode|[caption]]] /[[:en:Caption Shortcode|en]]</code>
 
* <code>[[Embed Shortcode|[embed]]] /[[:en:Embed Shortcode|en]]</code>
 
* <code>[[Embed Shortcode|[embed]]] /[[:en:Embed Shortcode|en]]</code>
603行目: 621行目:
 
== 活用事例 ==
 
== 活用事例 ==
  
* [http://another.maple4ever.net/archives/244/ hiromasa.another :o) » WordPress 2.5 のショートコードと wp-kougabu 画像ギャラリー] (2008-05-05)
+
* [http://another.maple4ever.net/archives/244/ hiromasa.another :o) &raquo; WordPress 2.5 のショートコードと wp-kougabu 画像ギャラリー] (2008-05-05)
* [http://dogmap.jp/2008/05/07/shortcode-api/ 独断と偏見の何でもレビュー » WordPress 2.5.x のショートコードAPI] (2008-05-07)
+
* [http://dogmap.jp/2008/05/07/shortcode-api/ 独断と偏見の何でもレビュー &raquo; WordPress 2.5.x のショートコードAPI] (2008-05-07)
  
 +
<div id="History">
 
== 変更履歴 ==
 
== 変更履歴 ==
 +
</div>
  
 
* [[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 になりました。
 
<!-- ** あともう一つ仕様変更 or バグフィクス -->
 
<!-- ** あともう一つ仕様変更 or バグフィクス -->
* [[Version 2.5|2.5]] : 新規機能
+
* [[Version 2.5|2.5]] : 新規導入
  
 
<div id="Related">
 
<div id="Related">
619行目: 639行目:
 
{{Shortcode Tags}}
 
{{Shortcode Tags}}
  
{{原文|Shortcode API|154257}} <!-- 01:16, 2 October 2015 Miqrogroove 版 -->
+
{{原文|Shortcode API|162356}} <!-- 12:33, 8 April 2018 Feindbild 版 -->
  
 
{{DEFAULTSORT:しよおとこおとAPI}}
 
{{DEFAULTSORT:しよおとこおとAPI}}

2018年5月3日 (木) 08:31時点における最新版

ショートコード 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 )

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

WordPress の将来のバージョンでは、wptexturize() の処理が内側のコードを邪魔しないようにすることが、入れ子のショートコードを持つプラグインに対して求められるかもしれません。そういう複雑な構文の場合、外側のタグについて no_texturize_shortcodes /en フィルターの適用が推奨されます。ここで用いた例でいうと、texturize しないショートコードのリストへ tag_a を追加すべきです。tag_a や tag_b のコンテンツを texturize する必要があるなら、上で説明したように do_shortcode() の呼び出し前に wptexturize() を呼び出すことができます。

未登録のショートコード名

一部のプラグイン作者はショートコード名を登録しないという戦略を選んでいます。これは例えば親のショートコードのハンドラー関数が呼び出されるまで入れ子のショートコードを無効化するためです。これはショートコードの属性値のパースを失敗するような、意図しない結果をもたらすかもしれません。例えば:

[tag_a unit="north"]
   [tag_b size="24"]
      [tag_c color="red"]
   [/tag_b]
[/tag_a]

バージョン 4.0.1 以降、プラグインが tag_b と tag_c を有効なショートコードとして登録し損なうと、wptexturize() の処理はショートコードのパースを始める前に次のようなテキストを出力します:

[tag_a unit="north"]
   [tag_b size=&#8221;24&#8221;]
      [tag_c color=&#8221;red&#8221;]
   [/tag_b]
[/tag_a]

未登録のショートコードは特別な意味を持たない普通のプレーンなテキストとして扱われるべきであり、ショートコードをわざと未登録にするのは勧められません。もしショートコードの間に生のコードをはさみ込む必要があるなら、少なくとも tag_a のコンテンツの texturize 処理を避けるために no_texturize_shortcodes /en フィルターの使用を検討してください:

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

閉じないショートコード

ある状況ではショートコードのパーサーが閉じたショートコードと閉じないショートコードの両方を正しく処理できません。例えば次の場合、パーサーは2番目のショートコードだけを正しく識別します:

[tag]
[tag]
   コンテンツ
[/tag]

しかし次の場合はパーサーが両方とも識別します:

[tag]
   コンテンツ
[/tag]
[tag]

ハイフン

参考: 以下で説明するハイフン ('-') を使ったショートコードに関する動作は WordPress 3 以上にも当てはまります。これは do_shortcode() や get_shortcode_regex() のバグによるものかもしれません。

ショートコードの名前にハイフンを使うときは注意してください。次の例では WordPress が2番目のショートコードを1番目と同じだと見る場合があります(WordPress は基本的にハイフンより前の部分を見ます):

[tag]
[tag-a]

結果はどのショートコードが最初に定義されたかに完全に依存します。もしハイフンを使うつもりなら一番短いショートコードを最初に定義してください。

これを避けるには下線を使うか、区切り文字なしにしてください:

[tag]
[tag_a]

[tag]
[taga]

ショートコードの最初の部分がどれも異なっていれば、ハイフンを使っても問題ありません:

[tag]
[tagfoo-a]

重要: ハイフンを使うと知らないうちに影響を与える可能性があります。もしインストールされた他のショートコードもハイフンを使っていると、ハイフンをつけた一般的な単語が衝突するかもしれません(同じリクエスト内で両方のショートコードが使われた場合):

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

// plugin-B
[is-admin]

角括弧

ショートコードのパーサーは属性に含まれる角括弧を受け付けません。そのため次の使い方は失敗します:

[tag attribute="[Some value]"]

飾りの角括弧 (cosmetic brackets) で囲まれたタグは wptexturize() やそのフィルターで完全にはサポートされていません。そのため次のコードは予想外の結果になるかもしれません:

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

参考: これらの制限は WordPress の将来のバージョンで変わるかもしれませんので、確実さを求めるならテストすべきです。

HTML

バージョン 3.9.3 から、ショートコードの属性内の HTML 使用は制限されるようになりました。例えば次のショートコードは「>」文字を含むので正しく動作しません:

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

バージョン 4.0 は予め認められた HTML を許すようになったので、次のコードは動作します:

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

HTML の制限に対する推奨の回避方法は、すべてのユーザー入力に HTML エンコードを行った上で、カスタムショートコードハンドラー内で HTML デコードを行うというものです。拡張 API 関数が計画されています。

ショートコード属性における HTML のフルサポートはこれまで公式に行われたことはなく、将来のバージョンで拡張される予定もありません。

バージョン 4.2.3 からは、類似の制限が HTML 内でのショートコード利用に対しても行われました。例えば次のショートコードは、スクリプト属性の入れ子なので正しく動作しません:

<a onclick="[tag]">

動的な属性値に対する推奨の回避方法は、ひとつだけ値を出力するのでなく必要な HTML 全体を出力するショートコードを設計するというものです。これは動くでしょう:

[link onclick="tag"]

また次のショートコードは属性のクォートが正しくないので使用できません:

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

これを正しい HTML としてパースする唯一の方法はシングルクォートとダブルクォートによる入れ子を使うというものです:

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

登録する個数

ショートコードを数百個も登録すると API が不安定になることが知られています。プラグイン作者は少数のショートコード名だけで実現できる解決方法を用意すべきです。この制限は将来のバージョンで変わる可能性があります。


正式な構文

WordPress のショートコードは特殊文字の扱いが HTML とは異なります。角括弧は一見魔法のように思えますが、決してどんな言語の一部でもありません。例えば:

[gallery]

gallery ショートコードは登録済みショートコードなので API によって特別なシンボルとしてパースされます。一方、ショートコードが登録されていなければ角括弧は単に無視されます:

[randomthing]

randomthing シンボルと角括弧は登録済みショートコードの一部ではないので無視されます。

完璧な世界なら、どんな [*] シンボルも API で扱うことができるでしょう。しかし次のようなチャレンジを考えておく必要があります: 角括弧 ( [・] ) は HTML の中で使うことができて常にショートコードというわけではなく、山括弧 ( <・> ) は限られた状況でのみショートコード内で使うことができ、そしてショートコードは出力される前に何層ものカスタマイズ可能なフィルターとパーサーを潜り抜けなければなりません。こうした言語の互換性問題があるので、角括弧は魔法になれません。

ショートコード構文は次のような一般形を使います:

[名前 属性 閉じる]
[名前 属性]任意の HTML やショートコードをここへ書くことができる。[/名前]

エスケープされたショートコードは角括弧がちょうど2つ多いだけで同じ形になります:

[[名前 属性 閉じる]]
[[名前 属性]任意の HTML やショートコードをここへ書くことができる。[/名前]]

繰り返しますがショートコード名は登録されている必要があります。さもないと4つの例はどれも無視されます。

ショートコード名

ショートコードの名前は以下の文字を絶対に含んではいけません:

  • 角括弧: [ ]
  • 山括弧: < >
  • アンパサンド: &
  • スラッシュ: /
  • 空白: スペース 改行(ラインフィード) タブ
  • 印刷できない文字: \x00 - \x20

クォートもショートコード名に含めないことを推奨します:

  • クォート: ' "

属性

属性はオプションです。ショートコード名とショートコードの属性の間にひとつスペースが必要です。2つ以上の属性を使うときは少なくともひとつのスペースで区切らなければなりません。

ひとつひとつの属性は次のいずれかの形式に従う必要があります:

属性名 = '値'

属性名 = "値"

属性名 = 値

"値"

値

属性名はオプションです。どのプラットフォームでも互換性を保つために次の文字だけを含む必要があります:

  • 大文字と小文字のアルファベット: A-Z a-z
  • 数字: 0-9
  • 下線: _
  • ハイフン: - (バージョン 4.3.0 より前は使えませんでした)

属性名にスペースは使えません。名前と = の間、それから = と値の間にスペースを入れるのは構いません。

注意: 属性名は大文字と小文字が混在可能ですが、パース後はいつも小文字になります。

属性値は次の文字を含んではいけません:

  • 角括弧: [ ]
  • クォート: " '

クォートで囲まない値は絶対にスペースを含んではなりません。

HTML 文字の <> は属性の中で限定的な使用がサポートされます。

ショートコード属性の中で特殊文字をエスケープする推奨の方法は HTML エンコードです。一番重要なのは、ショートコード属性にユーザーが入力した値を入れるなら必ずエスケープするか特殊文字を除去することです。

参考: シングルクォートで囲んだ値にダブルクォートを含めることができます。その逆も可能です。しかしこの方法はユーザー入力を扱うときは推奨されません。

次の文字は、属性値の中でエスケープされなければ、自動的に除去されてスペースへ置換されます:

セルフクロージング

セルフクロージングの印(スラッシュひとつ)はオプションです。印の前のスペースはオプションです。印の後にスペースを入れるのは禁止です。

[example /]

セルフクロージングの印は純粋に飾りであって効果を持ちませんが、ショートコードのパーサーはその後に来る「閉じるタグ」を無視します。

囲み型ショートコードはセルフクロージングの印を使ってはいけません。

エスケープ

WordPress は [name] と [/name] タグに挟まれた部分へ曲線形のクォートを入れようとします。他の部分と同じように処理するわけです。4.0.1 以降、未登録のショートコードも同様に「texturize」されるので予期しない曲線形のクォートが入る場合があります:

[randomthing param="test"]

良い例は次のようなものです:

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

<code> 要素はいつも texturize 処理の対象外になります。

登録済みショートコードは <code> 要素の内側でも処理されます。登録済みショートコードを web サイトへ表示するためにエスケープする書き方は次のようになります:

[[caption param="test"]]

... このように出力されます ...

[caption param="test"]

この状況では <code> 要素を使わなくても大丈夫です。

囲み型ショートコードの場合は次の構文を使ってください:

[[caption]My Caption[/caption]]


外部リソース

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

活用事例

変更履歴

  • 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最新版との差分