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

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(日本語活用事例を追加)
(ショートコード API)
2行目: 2行目:
  
 
<div id="The_Shortcode_API">
 
<div id="The_Shortcode_API">
== The Shortcode API ==
+
== ショートコード API ==
 
</div>
 
</div>
  
New in [[Version 2.5|WordPress 2.5]] is the '''Shortcode API''', a simple set of functions for creating macro codes for use in post content.  A trivial shortcode looks like this:
+
[[Version 2.5|WordPress 2.5]]で新しく追加された'''ショートコード API'''機能は、コンテンツ記事投稿に用いるマクロコードの作成する機能を備えています。ショートコードの単純な例は次のとおりです。
  
 
  [gallery]
 
  [gallery]
  
The Shortcode API makes it easy to create shortcodes that support attributes like this:
+
ショートコード API は、次の例のような属性をサポートするショートコードを作成することができます。
  
 
  [gallery id="123" size="medium"]
 
  [gallery id="123" size="medium"]
  
The API handles all the tricky parsing, eliminating the need for writing a custom regular expression for each shortcode. Helper functions are included for setting and fetching default attributes. The API support both self-closing and enclosing shortcodes.
+
API が手の込んだパージングを処理するので、ショートコードにカスタマイズされた正規表現を書く必要はありません。 デフォルト属性を設定し取り込むヘルパー関数が含まれています。 API は、自己完結型ショートコードと囲み型ショートコードの両方をサポートします。
  
As a quick start for those in a hurry, here's a minimal example of the PHP code required to create shortcode with attributes:
+
手っ取り早く使い始めたい人のために、属性を持つショートコードを作成するのに最低限必要な PHP コードの例を示します。
  
 
  // [bartag foo="bar"]
 
  // [bartag foo="bar"]
28行目: 28行目:
 
  add_shortcode('bartag', 'bartag_func');
 
  add_shortcode('bartag', 'bartag_func');
  
This creates a "<code>[bartag]</code>" shortcode that supports two attributes: <code>[bartag foo="something" bar="something else"]</code>.  Both attributes are optional and will take on default options if they are not provided.
+
このコードは、<code>[bartag]</code> ショートコードを作成し、2つの属性<code>[bartag foo=&quot;something&quot; bar=&quot;something else&quot;]</code>をサポートします。どちらの属性もオプションであり、値が付与されない場合はデフォルト値が使用されます。
  
 
<div id="Overview">
 
<div id="Overview">
=== Overview ===
+
=== 概観 ===
 
</div>
 
</div>
  
Shortcodes are written by providing a handler function. Shortcode handlers are broadly similar to WordPress filters: they accept parameters (attributes) and return a result (the shortcode output).
+
ショートコードを書くには、ハンドラ関数を記述します。 おおまかに言うと、ショートコードハンドラは、WordPress フィルタと類似しています。 フィルタがパラメータを受け入れ、結果を返すように、ハンドラは属性を受け入れ、ショートコードの出力を返します。
  
The [[#add_shortcode|<code>add_shortcode()</code>]] function is used to register a shortcode handler. It takes two parameters: the shortcode name (the string used in a post body), and the handler function name.
+
ショートコードハンドラを登録するには、[[#add_shortcode|<code>add_shortcode()</code>]] 関数が用いられます。 この関数には、2つのパラメータ、ショートコード名 (記事で用いられる文字列) とハンドラ関数名、があります。
  
A shortcode handler function should accept one or two attributes: $atts, an array of attributes, and $content, the enclosed content (if the shortcode is used in its enclosing form).  For example:
+
ショートコードハンドラ関数には、1つまたは2つの属性、属性の配列 $atts と、(ショートコードが囲み型で使用された場合) タグで囲まれたコンテンツ $content、があります。例を以下に示します。
  
 
  function my_shortcode_handler($atts, $content=null) {
 
  function my_shortcode_handler($atts, $content=null) {
 
  }
 
  }
  
The API call to register the shortcode handler would look something like this:
+
ショートコードハンドラを登録する API コールは、以下のようになります。
  
 
  add_shortcode('my-shortcode', 'my_shortcode_handler');
 
  add_shortcode('my-shortcode', 'my_shortcode_handler');
  
When <code>the_content</code> is displayed, the shortcode API will parse any registered shortcodes such as "<code>[my-shortcode]</code>", separate and parse the attributes and content, if any, and pass them the corresponding shorcode handler function. Any string returned by the shortcode handler will be inserted into the post body in place of the shortcode itself.
+
<code>the_content</code> が表示されるとき、ショートコード API <code>[my-shortcode]</code> のような登録されたショートコードをパースし、属性と (存在するならば) コンテンツをパースして分離し、対応するショートコードハンドラ関数に渡します。 ショートコードハンドラによって返される文字列は、ショートコードの代わりに記事本体に挿入されます。
  
Shortcode attributes such as these:
+
以下のようなショートコードの属性は、
  
 
  [my-shortcode foo="bar" baz="bing"]
 
  [my-shortcode foo="bar" baz="bing"]
  
Will be converted into an associative array like this, to be passed to the handler function as its <code>$atts</code> parameter:
+
以下に示す連想配列に変換され、<code>$atts</code> パラメータとしてハンドラ関数に渡されます。
  
 
  array( 'foo' => 'bar', 'baz' => 'bing')
 
  array( 'foo' => 'bar', 'baz' => 'bing')
  
The array keys are the attribute names, array values are the corresponding attribute values.
+
配列のキーは属性名で、値は対応する属性値です。
  
 
<div id="Attributes">
 
<div id="Attributes">
=== Attributes ===
+
=== 属性 ===
 
</div>
 
</div>
  
The raw <code>$atts</code> array may include any arbitrary attributes that are specified by the user. In order to help set default values for missing attributes, and eliminate any attributes that are not recognized by your shortcode, the API provides a [[#shortcode_atts|<code>shortcode_atts()</code>]] function.
+
生の <code>$atts</code> 配列には、ユーザーが指定した任意の属性が含まれている可能性があります。 欠けている属性にデフォルト値を付与し、ショートコードで認識されない属性をすべて取り除くために、API には [[#shortcode_atts|<code>shortcode_atts()</code>]] 関数が用意されています。
  
<code>shortcode_atts()</code> resembles the <code>wp_parse_args()</code> function, but has some important differences. Its parameters are:
+
<code>shortcode_atts()</code> は、<code>wp_parse_args()</code>  関数に似ていますが、重要な違いがあります。そのパラメータは、以下のとおりです。
  
 
  shortcode_atts( $defaults_array, $atts );
 
  shortcode_atts( $defaults_array, $atts );
  
Both parameters are required. <code>$defaults</code>_array is an associative array that specifies the recognized attribute names and their default values.  <code>$atts</code> is the raw attributes array as passed into your shortcode handler.  <code>shortcode_atts()</code> will return a normalized array containing all of the keys from the <code>$defaults_array</code>, filled in with values from the <code>$atts</code> array if present.  For example:
+
両方のパラメータが必須です。 <code>$defaults_array</code> は、認識される属性名とそのデフォルト値を指定する連想配列です。<code>$atts</code> は、ショートコードハンドラに渡される生の属性配列です。<code>shortcode_atts()</code> は、<code>$defaults_array</code> のキーを全て含み、<code>$atts</code> 配列からの値が存在すればその値を付与された正規化された配列を返します。例を以下に示します。
  
 
  $a = shortcode_atts( array(
 
  $a = shortcode_atts( array(
76行目: 76行目:
 
     ), $atts );
 
     ), $atts );
  
If <code>$atts</code> were to contain <code>array( 'foo' => 456, 'bar' => 'something' )</code>, the resulting <code>$a</code> would be <code>array( 'title' => 'My Title', 'foo' => 456 )</code>.  The value of <code>$atts['foo']</code> overrides the default of 123<code>$atts['title']</code> is not set, so the default 'My Title' is used.  And there is no 'bar' item in the defaults array, so it is not included in the result.
+
<code>$atts</code> <code>array( 'foo' =&gt; 456, 'bar' =&gt; 'something' )</code> を含むならば、出力 <code>$a</code> <code>array( 'title' =&gt; 'My Title', 'foo' =&gt; 456 )</code> になります。<code>$atts['foo']</code> の値は、デフォルト値 123 を上書きします。<code>$atts['title']</code> は設定されていないので、デフォルト値 'My Title' が使用されます。デフォルト配列には 'bar' 要素は含まれていないので、出力に含まれません。
  
A suggested code idiom for declaring defaults and parsing attributes in a shortcode handler is as follows:
+
ショートコードハンドラでデフォルト値を宣言し、属性をパースする推奨コードイディオムは、以下のとおりです。
  
 
  function my_shortcode_handler( $atts, $content = null ) {
 
  function my_shortcode_handler( $atts, $content = null ) {
88行目: 88行目:
 
  }
 
  }
  
This will parse the attributes, set default values, eliminate any unsupported attributes, and (using <code>extract()</code>) store the results in local variables named for the attribute keys - <code>$attr_1</code>, <code>$attr_2</code> and so on.  In other words, the array of defaults approximates a list of local variable declarations. (<code>extract()</code> is safe to use in this context without special flags to handle collisions because <code>shortcode_atts()</code> will strip out any keys not included in the defaults array).
+
この関数は、属性をパースし、デフォルト値を設定し、サポートされない属性を除去し、(<code>extract()</code> を用いて) <code>$attr_1</code>, <code>$attr_2</code> などの属性キーの名前のローカル変数に蓄積します。つまり、デフォルトの配列は、ローカル変数宣言のリストに類似しています。 (<code>shortcode_atts()</code> はデフォルト配列に含まれないキーをすべて取り除くため、ここでは衝突をハンドルする特別なフラグが無くても、<code>extract()</code> を安全に使用できます。)
  
 
<div id="Output">
 
<div id="Output">
=== Output ===
+
=== 出力 ===
 
</div>
 
</div>
  
The return value of a shortcode handler function is inserted into the post content output in place of the shortcode macro. Remember to use return and not echo - anything that is echoed will be output to the browser, but it won't appear in the correct place on the page.
+
ショートコードハンドラ関数の返り値は、ショートコードマクロの代わりに投稿コンテンツの出力に挿入されます。 echo ではなくて return を使用するようにしてください。echo されたものは全てブラウザに出力されますが、ページの適切な箇所に表示されません。
  
Shortcodes are parsed after [[関数リファレンス/wpautop|<code>wpautop</code>]]/[[:en:Function Reference/wpautop|en]] and [[関数リファレンス/wptexturize|<code>wptexturize</code>]]/[[:en:Function Reference/wptexturize|en]] post formatting has been applied (but see the note below about [[Version 2.5|2.5.0]] and [[Version 2.5.1|2.5.1]] differences).  This means that your shortcode output HTML won't automatically have curly quotes applied, p and br tags added, and so on. If you do want your shortcode output to be formatted, you should call <code>wpautop()</code> or <code>wptexturize()</code> directly when you return the output from your shortcode handler.
+
ショートコードは、[[関数リファレンス/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 は、カーリークォートが適用されず、p タグや br タグも付与されません。 ショートコードの出力を整形したい場合は、ショートコードハンドラが出力を返したときに、<code>wpautop()</code> <code>wptexturize()</code> を直接呼び出す必要があります。
  
<code>wpautop</code> recognizes shortcode syntax and will attempt not to wrap p or br tags around shortcodes that stand alone on a line by themselves. Shortcodes intended for use in this manner should ensure that the output is wrapped in an appropriate block tag such as <nowiki><p></nowiki> or <nowiki><div></nowiki>.
+
<code>wpautop</code> はショートコードの構文を認識し、独立した行のショートコードを p あるいは br タグで括らないようにします。 この方法で使用されるショートコードは、出力が <nowiki><p></nowiki><nowiki><div></nowiki>. などの適切なブロックタグで括られるようにする必要があります。
  
Note: in [[Version 2.5|WordPress 2.5.0]], shortcodes were parsed before post formatting was applied, so the shortcode output HTML was sometimes wrapped in <code>p</code> or <code>br</code> tags. This was incorrect behaviour that has been fixed in [[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]] で修正されました。
  
 
<div id="Enclosing_vs_self-closing_shortcodes">
 
<div id="Enclosing_vs_self-closing_shortcodes">
=== Enclosing vs self-closing shortcodes ===
+
=== 囲み型ショートコードと自己完結型ショートコード ===
 
</div>
 
</div>
  
The examples above show self-closing shortcode macros such as <code>[my-shortcode]</code>.  The API also supports enclosing shortcodes such as <code>[my-shortcode]content[/my-shortcode]</code>.
+
上で示した例は、<code>[my-shortcode]</code> のような、自己完結型ショートコードマクロでした。ショートコード API は、<code>[my-shortcode]content[/my-shortcode]</code> のような囲み型ショートコードもサポートしています。
  
If a shortcode macro is used to enclose content, its handler function will receive a second parameter containing that content. Users might write shortcodes in either form, so it is necessary to allow for either case by providing a default value for the second parameter to your handler function:
+
ショートコードマクロがコンテンツを囲むように使用された場合は、ハンドラ関数はそのコンテンツを含む第二パラメータを受け取ります。 ユーザーは、ショートコードをどちらの形式で記述しても構いません。そのため、ハンドラ関数に第二パラメータのデフォルト値を適用することで、どちらのケースにも対応する必要があります。
  
 
  function my_shortcode_handler( $atts, $content = null )
 
  function my_shortcode_handler( $atts, $content = null )
  
<code>is_null($content)</code> can be used to distinguish between the self-closing and enclosing cases.
+
<code>is_null($content)</code> を使用して囲み型と自己完結型を区別することができます。
  
When content is enclosed, the complete shortcode macro including its content will be replaced with the function output. It is the responsibility of the handler function to provide any necessary escaping or encoding of the raw content string, and include it in the output.
+
コンテンツがタグで囲まれている場合は、そのコンテンツを含むショートコードマクロ全体が、関数の出力に置き換えられます。 生のコンテンツ文字列に必要なエスケープやエンコードを適用し、出力に含めることが、ハンドラ関数に要求されています。
  
Here's a trivial example of an enclosing shortcode:
+
囲み型ショートコードの例を以下に示します。
  
 
  function caption_shortcode( $atts, $content = null ) {
 
  function caption_shortcode( $atts, $content = null ) {
124行目: 124行目:
 
  add_shortcode('caption', 'caption_shortcode');
 
  add_shortcode('caption', 'caption_shortcode');
  
When used like this:
+
このように使用したとき、
  
 
  [caption]My Caption[/caption]
 
  [caption]My Caption[/caption]
  
The output would be:
+
出力は以下の通りです。
  
 
<pre class="screen"><span class="caption">My Caption</span></pre>
 
<pre class="screen"><span class="caption">My Caption</span></pre>
  
Since <code>$content</code> is included in the return value without any escaping or encoding, the user can include raw HTML:
+
<code>$content</code> は、エスケープやエンコードされずに返り値に含まれているので、ユーザーが生 HTML を含めることができます。
  
 
  [caption]<a href="<nowiki>http://example.com/</nowiki>">My Caption</a>[/caption]
 
  [caption]<a href="<nowiki>http://example.com/</nowiki>">My Caption</a>[/caption]
  
Which would produce:
+
出力は以下の通りです。
  
 
<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>
  
This may or may not be intended behaviour - if the shortcode should not permit raw HTML in its output, it should use an escaping or filtering function to deal with it before returning the result.
+
これは、意図された動作のことも、意図されない動作のこともあるでしょう。ショートコードが生 HTML の出力を許可しないようにするには、エスケープまたはフィルタ関数を使用してから結果を返すようにしてください。
  
The shortcode parser uses a single pass on the post content.  This means that if the <code>$content</code> parameter of a shortcode handler contains another shortcode, it won't be parsed:
+
ショートコードパーザーは、投稿記事コンテンツにシングルパスを使用します。つまり、ショートコードハンドラの <code>$content</code> パラメータが別のショートコードを含む場合、それはパースされません。
  
 
  [caption]Caption: [my-shortcode][/caption]
 
  [caption]Caption: [my-shortcode][/caption]
  
This would produce:
+
出力は以下の通りです。
  
 
<pre class="screen"><span class="caption">Caption: [my-shortcode]</span></pre>
 
<pre class="screen"><span class="caption">Caption: [my-shortcode]</span></pre>
  
If the enclosing shortcode is intended to permit other shortcodes in its output, the handler function can call [[#do_shortcode|<code>do_shortcode()</code>]] recursively:
+
囲み型ショートコードが、出力に他のショートコードを許可している場合、ハンドラ関数は、[[#do_shortcode|<code>do_shortcode()</code>]] 関数を再帰的に呼び出します。
  
 
  function caption_shortcode( $atts, $content = null ) {
 
  function caption_shortcode( $atts, $content = null ) {
156行目: 156行目:
 
  }
 
  }
  
In the previous example, this would ensure the "<code>[my-shortcode]</code>" macro in the enclosed content is parsed, and its output enclosed by the caption span:
+
この例では、タグで囲まれたコンテンツ内の <code>[my-shortcode]</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: The result of my-shortcode's handler function</span></pre>
  
Enclosing shortcodes support attributes in the same way as self-closing shortcodes.  Here's an example of the <code>caption_shortcode()</code> improved to support a '<code>class</code>' attribute:
+
囲み型ショートコードは、自己完結型ショートコードと同様に、属性をサポートします。<code>class</code> 属性をサポートするように改良された<code>caption_shortcode()</code> の例を以下に示します。
  
 
  function caption_shortcode( $atts, $content = null ) {
 
  function caption_shortcode( $atts, $content = null ) {
175行目: 175行目:
  
 
<div id="Other_features_in_brief">
 
<div id="Other_features_in_brief">
=== Other features in brief ===
+
=== その他の特徴 ===
 
</div>
 
</div>
  
* The parser supports xhtml-style closing shortcodes like "<code>[my-shortcode /]</code>", but this is optional.
+
* パーザーは、<code>[my-shortcode /]</code> のような xhtml スタイルのショートコードをサポートしています。これはオプションです。
  
* Attribute names are always converted to lowercase before they are passed into the handler function.  Values are untouched. <code>[my-shortcode FOO="BAR"]</code> produces <code>$atts = array( 'foo' => 'BAR' )</code>.
+
* 属性名は、必ず小文字に変換されてからハンドラ関数に渡されます。 値は変更されません。<code>[my-shortcode FOO="BAR"]</code>は、<code>$atts = array( 'foo' =&gt; 'BAR' )</code> を生成します。
  
* Shortcode macros may use single or double quotes for attribute values, or omit them entirely if the attribute value does not contain spaces.  <code>[my-shortcode foo='123' bar=456]</code> is equivalent to <code>[my-shortcode foo="123" bar="456"]</code>.
+
* ショートコードマクロは、シングルクォーテーションまたはダブルクォーテーションが利用できます。属性の値が空白を含まない場合は、クォーテーションの省略も可能です。<code>[my-shortcode foo='123' bar=456]</code> は、<code>[my-shortcode foo="123" bar="456"]</code> と同等です。
  
* For backwards compatibility with older ad-hoc shortcodes, attribute names may be omitted.  If an attribute has no name it will be given a positional numeric key in the <code>$atts</code> array.  For example, <code>[my-shortcode 123]</code> will produce <code>$atts = array( 0 => 123 )</code>.  Positional attributes may be mixed with named ones, and quotes may be used if the values contain spaces or other significant characters.
+
* 古い、アドホックなショートコードとの後方互換性のため、属性名を省略することができます。属性名がない場合は、<code>$atts</code> 配列の順序キーが付与されます。たとえば、<code>[my-shortcode 123]</code> <code>$atts = array( 0 => 123 )</code> を生成します。順序で規定される属性と、属性名のある属性を混合することができます。また値が空白やその他の重要な文字を含む場合は引用符を使用することができます。
  
* The shortcode API is unit tested.  The tests -- which contain a number of examples of error cases and unusual syntax -- can be found at http://svn.automattic.com/wordpress-tests/wp-testcase/test_shortcode.php
+
* ショートコード API にはテストケースがあります。http://svn.automattic.com/wordpress-tests/wp-testcase/test_shortcode.php でエラーケースや異常な構文の例を含むテストが公開されています。
  
 
<div id="Function_reference">
 
<div id="Function_reference">
=== Function reference ===
+
=== 関数リファレンス ===
 
</div>
 
</div>
  
The following Shortcode API functions are available:
+
利用可能なショートコード API 関数を、以下に示します。
  
 
==== add_shortcode ====
 
==== add_shortcode ====
198行目: 198行目:
 
  function add_shortcode($tag, $func)
 
  function add_shortcode($tag, $func)
  
Registers a new shortcode handler function.  <code>$tag</code> is the shortcode string as written by the user (without braces), such as "my-shortcode".  <code>$func</code> is the handler function name.
+
新しいショートコードハンドラ関数を登録します。<code>$tag</code> は、my-shortcode のような、ユーザーによって記述されるショートコード文字列 (大カッコを除いたもの) です。<code>$func</code> は、ハンドラ関数名です。
  
Only one handler function may exist for a given shortcode.  Calling <code>add_shortcode()</code> again with the same <code>$tag</code> name will overwrite the previous handler.
+
ショートコードには、1つのハンドラ関数のみが存在できます。同じ <code>$tag</code> 名に対して再び <code>add_shortcode()</code> を呼び出した場合は、以前のハンドラに上書きします。
  
 
==== remove_shortcode ====
 
==== remove_shortcode ====
206行目: 206行目:
 
  function remove_shortcode($tag)
 
  function remove_shortcode($tag)
  
Deregisters an existing shortcode.  <code>$tag</code> is the shortcode name as used in <code>add_shortcode()</code>.
+
既存のショートコードを抹消します。<code>$tag</code> は、<code>add_shortcode()</code> で使用されるショートコード名です。
  
 
==== remove_all_shortcodes ====
 
==== remove_all_shortcodes ====
212行目: 212行目:
 
  function remove_all_shortcodes()
 
  function remove_all_shortcodes()
  
Deregisters all shortcodes.
+
すべてのショートコードを抹消します。
  
 
==== shortcode_atts ====
 
==== shortcode_atts ====
218行目: 218行目:
 
  function shortcode_atts($pairs, $atts)
 
  function shortcode_atts($pairs, $atts)
  
Process a raw array of attributes <code>$atts</code> against the set of defaults specified in <code>$pairs</code>.  Returns an array.  The result will contain every key from <code>$pairs</code>, merged with values from <code>$atts</code>.  Any keys in <code>$atts</code> that do not exist in <code>$pairs</code> are ignored.
+
<code>$pairs</code>で指定されているデフォルト値に対して、属性の生配列 <code>$atts</code> を処理し、配列を返します。結果は、<code>$pairs</code> のすべてのキーを含み、<code>$atts</code> の値をマージしたものになります。<code>$atts</code> に存在しても <code>$pairs</code> に存在しないキーは無視されます。
  
 
==== do_shortcode ====
 
==== do_shortcode ====
224行目: 224行目:
 
  function do_shortcode($content)
 
  function do_shortcode($content)
  
Parse any known shortcode macros in the <code>$content</code> string. Returns a string containing the original content with shortcode macros replaced by their handler functions' output.
+
<code>$content</code> 文字列の既知のショートコードをパースします。 元のコンテンツのショートコードマクロが、ハンドラ関数の出力で置き換えられた文字列を返します。
  
<code>do_shortcode()</code> is registered as a default filter on '<code>the_content</code>' with a priority of 11.
+
<code>do_shortcode()</code> は、<code>the_content</code> のデフォルトフィルターとして、プライオリティ11で登録されます。
  
 
<div id="Limitations">
 
<div id="Limitations">
=== Limitations ===
+
=== 制限事項 ===
 
</div>
 
</div>
  
The shortcode parser correctly deals with nested shortcode macros, provided their handler functions support it by recursively calling <code>do_shortcode()</code>:
+
ショートコードパーザーは、ハンドラ関数が再帰的に <code>do_shortcode()</code> を呼び出すことをサポートしていれば、ネストされたショートコードマクロを処理することができます。
  
 
  [tag-a]
 
  [tag-a]
240行目: 240行目:
 
  [/tag-a]
 
  [/tag-a]
  
However the parser will fail if a shortcode macro is used to enclose another macro of the same name:
+
しかし、ショートコードマクロが、同じ名前の別のマクロを囲むように使用すると、パースに失敗します。
  
 
  [tag-a]
 
  [tag-a]
247行目: 247行目:
 
  [/tag-a]
 
  [/tag-a]
  
This is a limitation of the context-free regexp parser used by <code>do_shortcode()</code> - it is very fast but does not count levels of nesting, so it can't match each opening tag with its correct closing tag in these cases.
+
これは、<code>do_shortcode()</code> で使われる文脈自由正規パーザーの制限です。非常に高速ですが、ネストの階層を数えることができません。そのため、この場合には各開始タグを正しい終了タグとマッチさせることができません。
  
 
<div id=External_Resources"">
 
<div id=External_Resources"">
=== External Resources ===
+
=== 外部リソース ===
 
</div>
 
</div>
  
[http://xavisys.com/wordpress-25-shortcodes/ Shortcode summary by  Aaron D. Campbell] - Explains shortcodes and gives examples including how to incorporate shortcodes into a meta box for sending them to the editor using js.
+
[http://xavisys.com/wordpress-25-shortcodes/ Shortcode summary by  Aaron D. Campbell] に、ショートコードの説明およびサンプルが掲載されています。javascriptを使用して、ショートコードをメタボックスに組み込んで編集者へと送信するサンプルも含まれています
  
 
== 活用事例 ==
 
== 活用事例 ==

2008年9月29日 (月) 21:54時点における版

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

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

[gallery]

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

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

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

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

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

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

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

概観

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

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

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

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

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

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

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

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

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

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

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

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

属性

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

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

shortcode_atts( $defaults_array, $atts );

両方のパラメータが必須です。 $defaults_array は、認識される属性名とそのデフォルト値を指定する連想配列です。$atts は、ショートコードハンドラに渡される生の属性配列です。shortcode_atts() は、$defaults_array のキーを全て含み、$atts 配列からの値が存在すればその値を付与された正規化された配列を返します。例を以下に示します。

$a = shortcode_atts( array(
   'title' => 'My Title'
   'foo' => 123,
   ), $atts );

$attsarray( 'foo' => 456, 'bar' => 'something' ) を含むならば、出力 $aarray( 'title' => 'My Title', 'foo' => 456 ) になります。$atts['foo'] の値は、デフォルト値 123 を上書きします。$atts['title'] は設定されていないので、デフォルト値 'My Title' が使用されます。デフォルト配列には 'bar' 要素は含まれていないので、出力に含まれません。

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

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

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

出力

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

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

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

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

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

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

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

function my_shortcode_handler( $atts, $content = null )

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

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

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

function caption_shortcode( $atts, $content = null ) {
   return '' . $content . '';
}
add_shortcode('caption', 'caption_shortcode');

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

[caption]My Caption[/caption]

出力は以下の通りです。

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

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

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

出力は以下の通りです。

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

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

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

[caption]Caption: [my-shortcode][/caption]

出力は以下の通りです。

<span class="caption">Caption: [my-shortcode]</span>

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

function caption_shortcode( $atts, $content = null ) {
   return '' . do_shortcode($content) . '';
}

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

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

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

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

その他の特徴

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

関数リファレンス

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

add_shortcode

function add_shortcode($tag, $func)

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

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

remove_shortcode

function remove_shortcode($tag)

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

remove_all_shortcodes

function remove_all_shortcodes()

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

shortcode_atts

function shortcode_atts($pairs, $atts)

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

do_shortcode

function do_shortcode($content)

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

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

制限事項

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

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

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

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

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

外部リソース

Shortcode summary by Aaron D. Campbell に、ショートコードの説明およびサンプルが掲載されています。javascriptを使用して、ショートコードをメタボックスに組み込んで編集者へと送信するサンプルも含まれています

活用事例

変更履歴

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