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

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

ショートコード API

提供: WordPress Codex 日本語版
2015年10月10日 (土) 23:27時点におけるGblsm (トーク | 投稿記録)による版 (デフォルトで使えるショートコード)

移動先: 案内検索

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

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

[gallery]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

add_shortcode( 'myshortcode', 'my_shortcode_handler' );

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

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

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

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

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

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

属性の処理

生の $atts 配列にはユーザーが指定した任意の属性が含まれている可能性があります。

省略された属性にデフォルト値を付与し、ショートコードが認識しない属性をすべて取り除くために、API には shortcode_atts() 関数が用意されています。

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

shortcode_atts( $defaults_array, $atts );

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

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

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

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

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

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

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


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


出力

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

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

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

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

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

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


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

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

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

function my_shortcode_handler( $atts, $content = null )

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

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

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

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

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

[caption]My Caption[/caption]

出力は以下のようになります:

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

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

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

これは次のような結果を生成します:

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

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

ショートコードのパーサーは投稿コンテンツを一度だけパースします。つまりショートコードハンドラーの $content パラメータが別のショートコードを含む場合、それはパースされません。次の場合:

[caption]Caption: [myshortcode][/caption]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

その他の機能

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

関数リファレンス

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

add_shortcode()

function add_shortcode( $tag, $func )

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

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

remove_shortcode()

function remove_shortcode( $tag )

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

remove_all_shortcodes()

function remove_all_shortcodes()

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

shortcode_atts()

function shortcode_atts( $pairs, $atts )

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

do_shortcode()

function do_shortcode( $content )

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

do_shortcode()'the_content' フックのデフォルトフィルターとして優先度11で登録されます。


制限事項

入れ子のショートコード

ショートコードパーサーは、再帰的に do_shortcode() を呼び出すことでハンドラー関数がサポートしていれば、入れ子になったショートコードマクロを正しく処理することができます:

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

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

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

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

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

Unregistered Names

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

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

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

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

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

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

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

Unclosed Shortcodes

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

[tag]
[tag]
   CONTENT
[/tag]

However in this case the parser will identify both:

[tag]
   CONTENT
[/tag]
[tag]

Hyphens

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

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

[tag]
[tag-a]

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

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

[tag]
[tag_a]

[tag]
[taga]

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

[tag]
[tagfoo-a]

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

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

// plugin-B
[is-admin]

Square Brackets

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

[tag attribute="[Some value]"]

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

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

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

HTML

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

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

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

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

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

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

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

<a onclick="[tag]">

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

[link onclick="tag"]

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

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

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

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

Registration Count

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


Formal Syntax

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

[gallery]

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

[randomthing]

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

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

The shortcode syntax uses these general parts:

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

Escaped shortcodes are identical but have exactly two extra braces:

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

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

Names

Shortcode names must never contain the following characters:

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

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

  • Quotes: ' "

Attributes

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

Each attribute should conform to one of these formats:

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

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

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

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

Attribute values must never contain the following characters:

  • Square braces: [ ]
  • Quotes: " '

Unquoted values also must never contain spaces.

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

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

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

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

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

Self-Closing

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

[example /]

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

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

Escaping

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

[randomthing param="test"]

A better example would be:

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

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

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

[[caption param="test"]]

... which will output ...

[caption param="test"]

The <code> element is optional in that situation.


History

The Shortcode API was introduced in WordPress 2.5.

外部リソース

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

活用事例

変更履歴

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


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


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