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

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(変更履歴: {{Shortcode Tags}})
(en:Shortcode API 12:33, 8 April 2018 Feindbild 版をマージ、翻訳。)
 
(3人の利用者による、間の8版が非表示)
1行目: 1行目:
__TOC__
+
'''ショートコード API''' は、投稿や固定ページで使える WordPress の[[ショートコード]]を作るための関数のシンプルなセットです。例えば次のショートコードは(投稿や固定ページの本文に書くと)その投稿や固定ページへ添付されたイメージのギャラリーを追加します:
[[Version 2.5|WordPress 2.5]]で新しく追加された'''ショートコード API'''機能は、コンテンツ記事投稿に用いるマクロコードの作成する機能を備えています。ショートコードの単純な例は次のとおりです。
+
  
 
  [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}";
+
}
+
add_shortcode('bartag', 'bartag_func');
+
  
このコードは、<code>[bartag]</code> ショートコードを作成し、2つの属性 <code>[bartag foo="something" bar="something else"]</code> をサポートします。どちらの属性もオプションであり、値が付与されない場合はデフォルト値が使用されます。
+
これで <code>[foobar]</code> ショートコードが作られて、使用すると次の値を返します: foo and bar
 +
 
 +
属性を持つショートコードの場合は:
 +
 
 +
<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>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行目: 139行目:
 
</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行目: 162行目:
 
</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>empty( $content )</code> を使用して囲み型と自己完結型を区別することができます。
  
コンテンツがタグで囲まれている場合は、そのコンテンツを含むショートコードマクロ全体が、関数の出力に置き換えられます。  生のコンテンツ文字列に必要なエスケープやエンコードを適用し、出力に含めることが、ハンドラ関数に要求されています。
+
コンテンツがタグで囲まれている場合は、そのコンテンツを含むショートコードマクロ全体が関数の出力で置き換えられます。生のコンテンツ文字列に必要なエスケープやエンコードを適用し、出力に含める処理は、ハンドラー関数が行う必要があります。
  
囲み型ショートコードの例を以下に示します。
+
囲み型ショートコードの例を以下に示します:
  
 
<pre>
 
<pre>
119行目: 180行目:
 
</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行目: 214行目:
 
</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行目: 235行目:
 
}
 
}
 
</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>[myshortcode foo='123' bar=456]</code> <code>[myshortcode foo="123" bar="456"]</code> と同等です。 '''参考:''' 最後尾の属性の値はスラッシュ「/」で終わることができません。ひとつ前に説明した機能がそのスラッシュを消してしまうためです。
  
* ショートコードマクロは、シングルクォーテーションまたはダブルクォーテーションが利用できます。属性の値が空白を含まない場合は、クォーテーションの省略も可能です。<code>[my-shortcode foo='123' bar=456]</code> は、<code>[my-shortcode foo="123" bar="456"]</code> と同等です。
+
* 古くてアドホックなショートコードとの後方互換性のため、属性名を省略することができます。属性名がない場合は位置を表す数値キーをつけて <code>$atts</code> 配列へ入れられます。例えば、<code>[myshortcode 123]</code> <code>$atts = array( 0 => 123 )</code> を生成します。属性名を省略した属性と属性名のある属性を混ぜて使うことができます。そして値が空白や他の特殊文字を含む場合はクォートを使用することができます。
  
* 古い、アドホックなショートコードとの後方互換性のため、属性名を省略することができます。属性名がない場合は、<code>$atts</code> 配列の順序キーが付与されます。たとえば、<code>[my-shortcode 123]</code> は <code>$atts = array( 0 => 123 )</code> を生成します。順序で規定される属性と、属性名のある属性を混合することができます。また値が空白やその他の重要な文字を含む場合は引用符を使用することができます。
+
* ショートコード API にはテストケースがあります。エラーケースや異常な構文の例を含むテストが http://svn.automattic.com/wordpress-tests/trunk/tests/shortcode.php で公開されています。
  
* ショートコード API にはテストケースがあります。http://svn.automattic.com/wordpress-tests/wp-testcase/test_shortcode.php でエラーケースや異常な構文の例を含むテストが公開されています。
+
<div id="Function_reference">
  
<div id="Function_reference">
 
 
== 関数リファレンス ==
 
== 関数リファレンス ==
 
</div>
 
</div>
198行目: 265行目:
 
=== 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行目: 285行目:
 
=== 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行目: 302行目:
 
</div>
 
</div>
  
ショートコードパーザーは、ハンドラ関数が再帰的に <code>do_shortcode()</code> を呼び出すことをサポートしていれば、ネストされたショートコードマクロを処理することができます。
+
<div id="Nested_Shortcodes">
 +
=== 入れ子のショートコード ===
 +
</div>
  
[tag-a]
+
ショートコードパーサーは、再帰的に <code>do_shortcode()</code> を呼び出すことでハンドラー関数がサポートしていれば、入れ子になったショートコードマクロを正しく処理することができます:
    [tab-b]
+
      [tag-c]
+
    [/tag-b]
+
[/tag-a]
+
  
しかし、ショートコードマクロが、同じ名前の別のマクロを囲むように使用すると、パースに失敗します。
+
[tag_a]
 +
    [tag_b]
 +
      [tag_c]
 +
    [/tag_b]
 +
[/tag_a]
  
 +
しかしショートコードマクロが同じ名前のマクロをもうひとつ囲むように使用するとパースに失敗します:
 +
 +
[tag_a]
 +
    [tag_a]
 +
    [/tag_a]
 +
[/tag_a]
 +
 +
これは [[関数リファレンス/do_shortcode|<code>do_shortcode()</code>]] で使われる文脈自由正規表現パーサーの制限によるものです。このパーサーはとても高速ですが入れ子のレベルを数えることができません。そのためこの場合にはそれぞれの開始タグを正しい終了タグとマッチさせることができません。
 +
 +
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()]] を呼び出すことができます。
 +
 +
<div id="Unregistered_Names">
 +
=== 未登録のショートコード名 ===
 +
</div>
 +
 +
一部のプラグイン作者はショートコード名を登録しないという戦略を選んでいます。これは例えば親のショートコードのハンドラー関数が呼び出されるまで入れ子のショートコードを無効化するためです。これはショートコードの属性値のパースを失敗するような、意図しない結果をもたらすかもしれません。例えば:
 +
 +
[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=&amp;#8221;24&amp;#8221;]
 +
      [tag_c color=&amp;#8221;red&amp;#8221;]
 +
    [/tag_b]
 +
[/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_filter( 'no_texturize_shortcodes', 'ignore_tag_a' );
 +
 +
function ignore_tag_a( $list ) {
 +
  $list[] = 'tag_a';
 +
  return $list;
 +
}
 +
 +
<div id="Unclosed_Shortcodes">
 +
=== 閉じないショートコード ===
 +
</div>
 +
 +
ある状況ではショートコードのパーサーが閉じたショートコードと閉じないショートコードの両方を正しく処理できません。例えば次の場合、パーサーは2番目のショートコードだけを正しく識別します:
 +
 +
[tag]
 +
[tag]
 +
    コンテンツ
 +
[/tag]
 +
 +
しかし次の場合はパーサーが両方とも識別します:
 +
 +
[tag]
 +
    コンテンツ
 +
[/tag]
 +
[tag]
 +
 +
<div id="Hyphens">
 +
=== ハイフン ===
 +
</div>
 +
 +
'''参考:''' 以下で説明するハイフン ('-') を使ったショートコードに関する動作は WordPress 3 以上にも当てはまります。これは do_shortcode() や get_shortcode_regex() のバグによるものかもしれません。
 +
 +
ショートコードの名前にハイフンを使うときは注意してください。次の例では WordPress が2番目のショートコードを1番目と同じだと見る場合があります(WordPress は基本的にハイフンより前の部分を見ます):
 +
 +
[tag]
 
  [tag-a]
 
  [tag-a]
    [tag-a]
 
    [/tag-a]
 
[/tag-a]
 
  
これは、<code>do_shortcode()</code> で使われる文脈自由正規パーザーの制限です。非常に高速ですが、ネストの階層を数えることができません。そのため、この場合には各開始タグを正しい終了タグとマッチさせることができません。
+
結果はどのショートコードが最初に定義されたかに完全に依存します。もしハイフンを使うつもりなら一番短いショートコードを最初に定義してください。
 +
 
 +
これを避けるには下線を使うか、区切り文字なしにしてください:
 +
 
 +
[tag]
 +
[tag_a]
 +
 +
[tag]
 +
[taga]
 +
 
 +
ショートコードの最初の部分がどれも異なっていれば、ハイフンを使っても問題ありません:
 +
 
 +
[tag]
 +
[tagfoo-a]
 +
 
 +
'''重要:''' ハイフンを使うと知らないうちに影響を与える可能性があります。もしインストールされた他のショートコードもハイフンを使っていると、ハイフンをつけた一般的な単語が衝突するかもしれません(同じリクエスト内で両方のショートコードが使われた場合):
 +
 
 +
// plugin-A
 +
[is-logged-in]
 +
 +
// plugin-B
 +
[is-admin]
 +
 
 +
<div id="Square_Brackets">
 +
=== 角括弧 ===
 +
</div>
 +
 
 +
ショートコードのパーサーは属性に含まれる角括弧を受け付けません。そのため次の使い方は失敗します:
 +
 
 +
[tag attribute="[Some value]"]
 +
 
 +
飾りの角括弧 (cosmetic brackets) で囲まれたタグは wptexturize() やそのフィルターで完全にはサポートされていません。そのため次のコードは予想外の結果になるかもしれません:
 +
 
 +
[I put random text near my captions. [caption]]
 +
 
 +
'''参考:''' これらの制限は WordPress の将来のバージョンで変わるかもしれませんので、確実さを求めるならテストすべきです。
 +
 
 +
=== HTML ===
 +
 
 +
バージョン 3.9.3 から、ショートコードの属性内の HTML 使用は制限されるようになりました。例えば次のショートコードは「&gt;」文字を含むので正しく動作しません:
 +
 
 +
[tag value1="35" value2="25" compare="&gt;"]
 +
 
 +
バージョン 4.0 は予め認められた HTML を許すようになったので、次のコードは動作します:
 +
 
 +
[tag description="&lt;b&gt;Greetings&lt;/b&gt;"]
 +
 
 +
HTML の制限に対する推奨の回避方法は、すべてのユーザー入力に HTML エンコードを行った上で、カスタムショートコードハンドラー内で HTML デコードを行うというものです。拡張 API 関数が計画されています。
 +
 
 +
ショートコード属性における HTML のフルサポートはこれまで公式に行われたことはなく、将来のバージョンで拡張される予定もありません。
 +
 
 +
バージョン 4.2.3 からは、類似の制限が HTML 内でのショートコード利用に対しても行われました。例えば次のショートコードは、スクリプト属性の入れ子なので正しく動作しません:
 +
 
 +
&lt;a onclick="[tag]"&gt;
 +
 
 +
動的な属性値に対する推奨の回避方法は、ひとつだけ値を出力するのでなく必要な HTML 全体を出力するショートコードを設計するというものです。これは動くでしょう:
 +
 
 +
[link onclick="tag"]
 +
 
 +
また次のショートコードは属性のクォートが正しくないので使用できません:
 +
 
 +
&lt;a title="[tag attr="id"]"&gt;
 +
 
 +
これを正しい HTML としてパースする唯一の方法はシングルクォートとダブルクォートによる入れ子を使うというものです:
 +
 
 +
&lt;a title="[tag attr='id']"&gt;
 +
 
 +
<div id="Registration_Count">
 +
=== 登録する個数 ===
 +
</div>
 +
 
 +
ショートコードを数百個も登録すると API が不安定になることが知られています。プラグイン作者は少数のショートコード名だけで実現できる解決方法を用意すべきです。この制限は将来のバージョンで変わる可能性があります。
 +
 
 +
 
 +
<div id="Formal_Syntax">
 +
== 正式な構文 ==
 +
</div>
 +
 
 +
WordPress のショートコードは特殊文字の扱いが HTML とは異なります。角括弧は一見魔法のように思えますが、決してどんな言語の一部でもありません。例えば:
 +
 
 +
[gallery]
 +
 
 +
gallery ショートコードは登録済みショートコードなので API によって特別なシンボルとしてパースされます。一方、ショートコードが登録されていなければ角括弧は単に無視されます:
 +
 
 +
[randomthing]
 +
 
 +
randomthing シンボルと角括弧は登録済みショートコードの一部ではないので無視されます。
 +
 
 +
完璧な世界なら、どんな [*] シンボルも API で扱うことができるでしょう。しかし次のようなチャレンジを考えておく必要があります: 角括弧 ( <nowiki>[</nowiki>・<nowiki>]</nowiki> ) は HTML の中で使うことができて常にショートコードというわけではなく、山括弧 ( &lt;・&gt; ) は限られた状況でのみショートコード内で使うことができ、そしてショートコードは出力される前に何層ものカスタマイズ可能なフィルターとパーサーを潜り抜けなければなりません。こうした言語の互換性問題があるので、角括弧は魔法になれません。
 +
 
 +
ショートコード構文は次のような一般形を使います:
 +
 
 +
[名前 属性 閉じる]
 +
 
 +
[名前 属性]任意の HTML やショートコードをここへ書くことができる。[/名前]
 +
 
 +
エスケープされたショートコードは角括弧がちょうど2つ多いだけで同じ形になります:
 +
 
 +
&#91;&#91;名前 属性 閉じる]]
 +
 
 +
&#91;&#91;名前 属性]任意の HTML やショートコードをここへ書くことができる。[/名前]]
 +
 
 +
繰り返しますがショートコード名は登録されている必要があります。さもないと4つの例はどれも無視されます。
 +
 
 +
<div id="Names">
 +
=== ショートコード名 ===
 +
</div>
 +
 
 +
ショートコードの名前は以下の文字を絶対に含んではいけません:
 +
 
 +
* 角括弧: <tt>[ ]</tt>
 +
* 山括弧: <tt>&lt; &gt;</tt>
 +
* アンパサンド: <tt>&amp;</tt>
 +
* スラッシュ: <tt>/</tt>
 +
* 空白: スペース 改行(ラインフィード) タブ
 +
* 印刷できない文字: <tt>\x00 - \x20</tt>
 +
 
 +
クォートもショートコード名に含めないことを推奨します:
 +
 
 +
* クォート: <tt>' "</tt>
 +
 
 +
<div id="Attributes">
 +
=== 属性 ===
 +
</div>
 +
 
 +
属性はオプションです。ショートコード名とショートコードの属性の間にひとつスペースが必要です。2つ以上の属性を使うときは少なくともひとつのスペースで区切らなければなりません。
 +
 
 +
ひとつひとつの属性は次のいずれかの形式に従う必要があります:
 +
 
 +
属性名 = '値'
 +
 +
属性名 = "値"
 +
 +
属性名 = 値
 +
 +
"値"
 +
 +
 +
 
 +
属性名はオプションです。どのプラットフォームでも互換性を保つために次の文字だけを含む必要があります:
 +
 
 +
* 大文字と小文字のアルファベット: <tt>A-Z a-z</tt>
 +
* 数字: <tt>0-9</tt>
 +
* 下線: <tt>_</tt>
 +
* ハイフン: <tt>-</tt> (バージョン 4.3.0 より前は使えませんでした)
 +
 
 +
属性名にスペースは使えません。名前と <code>=</code> の間、それから <code>=</code> と値の間にスペースを入れるのは構いません。
 +
 
 +
: '''注意:''' 属性名は大文字と小文字が混在可能ですが、パース後はいつも小文字になります。
 +
 
 +
属性値は次の文字を含んではいけません:
 +
 
 +
* 角括弧: <tt>[ ]</tt>
 +
* クォート: <tt>" '</tt>
 +
 
 +
クォートで囲まない値は絶対にスペースを含んではなりません。
 +
 
 +
HTML 文字の <tt>&lt;</tt> と <tt>&gt;</tt> は属性の中で限定的な使用がサポートされます。
 +
 
 +
ショートコード属性の中で特殊文字をエスケープする推奨の方法は HTML エンコードです。一番重要なのは、ショートコード属性にユーザーが入力した値を入れるなら必ずエスケープするか特殊文字を除去することです。
 +
 
 +
参考: シングルクォートで囲んだ値にダブルクォートを含めることができます。その逆も可能です。しかしこの方法はユーザー入力を扱うときは推奨されません。
 +
 
 +
次の文字は、属性値の中でエスケープされなければ、自動的に除去されてスペースへ置換されます:
 +
 
 +
* [[Wikipedia:ja:ノーブレークスペース|ノーブレークスペース]]: \xC2\xA0
 +
* ゼロ幅スペース: \xE2\x80\x8B
 +
 
 +
<div id="Self-Closing">
 +
=== セルフクロージング ===
 +
</div>
 +
 
 +
セルフクロージングの印(スラッシュひとつ)はオプションです。印の前のスペースはオプションです。印の後にスペースを入れるのは禁止です。
 +
 
 +
[example /]
 +
 
 +
セルフクロージングの印は純粋に飾りであって効果を持ちませんが、ショートコードのパーサーはその後に来る「閉じるタグ」を無視します。
 +
 
 +
囲み型ショートコードはセルフクロージングの印を使ってはいけません。
 +
 
 +
<div id="Escaping">
 +
=== エスケープ ===
 +
</div>
 +
 
 +
WordPress は [name] と [/name] タグに挟まれた部分へ曲線形のクォートを入れようとします。他の部分と同じように処理するわけです。4.0.1 以降、未登録のショートコードも同様に「texturize」されるので予期しない曲線形のクォートが入る場合があります:
 +
 
 +
[randomthing param="test"]
 +
 
 +
良い例は次のようなものです:
 +
 
 +
&lt;code&gt;[randomthing param="test"]&lt;/code&gt;
 +
 
 +
<tt>&lt;code&gt;</tt> 要素はいつも texturize 処理の対象外になります。
 +
 
 +
登録済みショートコードは &lt;code&gt; 要素の内側でも処理されます。登録済みショートコードを web サイトへ表示するためにエスケープする書き方は次のようになります:
 +
 
 +
&#91;&#91;caption param="test"]]
 +
 
 +
... このように出力されます ...
 +
 
 +
[caption param="test"]
 +
 
 +
この状況では &lt;code&gt; 要素を使わなくても大丈夫です。
 +
 
 +
囲み型ショートコードの場合は次の構文を使ってください:
 +
 
 +
[[caption]My Caption[/caption]]
 +
 
  
 
<div id=External_Resources"">
 
<div id=External_Resources"">
255行目: 597行目:
 
</div>
 
</div>
  
* [http://xavisys.com/wordpress-25-shortcodes/ Shortcode summary by  Aaron D. Campbell] に、ショートコードの説明およびサンプルが掲載されています。javascriptを使用して、ショートコードをメタボックスに組み込んで編集者へと送信するサンプルも含まれています。
+
* [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://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://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|[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>
  
 
== 活用事例 ==
 
== 活用事例 ==
  
* [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>
  
 
{{Shortcode Tags}}
 
{{Shortcode Tags}}
  
{{原文|Shortcode API|65562}}<!-- 22:52, December 29, 2008 Ozh 版 -->
+
{{原文|Shortcode API|162356}} <!-- 12:33, 8 April 2018 Feindbild 版 -->
  
 
{{DEFAULTSORT:しよおとこおとAPI}}
 
{{DEFAULTSORT:しよおとこおとAPI}}
284行目: 649行目:
  
 
[[en:Shortcode API]]
 
[[en:Shortcode API]]
 +
[[it:Le API degli Shortcode]]
 +
[[pt-br:Shortcode API]]
 +
[[ru:Shortcode 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最新版との差分