いろいろな種類のショートコードの作り方をおさらい

最近のWordPressでは、編集画面でも同じ表現・動作をさせることができるブロック機能が主流になりつつあります。

しかしながら、独自の表現・動作をさせるブロックをしっかり作成するには、開発環境を整えたり、仕組みをよく理解していく必要があり、テーマやプラグインの提供者ではなく、ちょっとテーマをカスタマイズして思い通りの投稿などを作ろうとする場合には敷居が高いのではないかと思います。

現在のブロックエディタに変わる以前のWordPressには、角括弧で囲むことで独自の動作をさせることができるショートコードというのが、通常のコンテンツに何かを加える上で主流の機能でした。

ショートコードは基本的にPHPの基礎知識と、作り方の基本さえ覚えてしまえば、ブロック制作と比べて比較的簡単に作成することができます。

また、将来的にも恐らくショートコードが無効になることはないと思いますので、覚えておいて損はない機能だと思います。

そこで今回は、いろいろな形式のショートコードを作る方法を自身のおさらいも兼ねて紹介していきます。

WordPressのショートコードの種類

ショートコードの基本構造は、大別すると「自己完結型」「囲み型」の2つ、細かく分けると以下の4種類があります。

恐らく何かのプラグインでショートコードを使用するものを利用したことがあれば、なんとなく見たことがあるのではないでしょうか？

次項移行でこれらのショートコードの作り方を、例や補足を交えて紹介していきます。

一応プログラムが重複してトラブルにならないよう、各ショートコードを有効化しているテーマのfunctions.phpへ追加し、投稿などで実際にショートコードを挿入して、どのようになるのかを確認しながら進めていただければと思います。

テーマのfunctions.phpへのコード追加に関するスキルに不安のある方、万が一トラブルが発生したときの対処が不安な方は安易にコードのコピペをしないでください（トラブルが発生しても責任は負いません）

長いページになるのを少しでも避けるため、ショートコードを動作させるためにテーマのfunctions.phpへ追加するサンプルコードをアコーディオン表示にしています。コードは各セクション内の「functions.phpへ追記するコードを表示する」をクリックすることで表示、コピーできます

自己完結型ショートコードの作成方法

単純に記述されている内容を出力するショートコード

先ほどの分類でいう、「自己完結型」のショートコードです。

以下は、「my_shortcode_default」というユーザー定義関数を使って、「出力する内容」に書かれている内容を「sc-default」で出力するという基本的なコードです。

function my_shortcode_default() {

$output = '出力する内容';

return $output;
}
add_shortcode('sc-default', 'my_shortcode_default');

このまま上記コードをfunctions.phpへ追記し、投稿や固定ページの編集画面で以下のショートコードを挿入した後に、プレビューで表示すると、ショートコードの部分が「出力する内容」という文字として表示されます。

[sc-default]

これが本当に基本の基本のショートコードです。コード中の「出力する内容」の部分を変えて再びプレビューするなどして、表示される文字列が指示通りに変わるかなど試してみてください。

記述されている内容の一部を任意の文字列へ変更するショートコード

先ほどの分類でいう、「自己完結型（パラメーター付き）」ショートコードです。

「my_shortcode_atts_default」というユーザー定義関数を使って、「出力する内容」に書かれている内容のうち、「title」の文字列を変更可能にして「sc-atts-default」というショートコードで出力するという基本的なコードです。

パラメーターのない自己完結型のショートコードとは以下の違いがあります

• ユーザー定義関数の()の中にパラメーター（$atts）を使いますよという宣言をする
• 「title」というパラメーターを使いますよという記述をする（2～5行目）
• パラメーターの記述がショートコード内にない場合に備えて、「title」というパラメーターに「My Title」という文字列を設定しておく（4行目）
• 出力する内容の部分で「$atts[‘title‘]」を使って「title」というパラメーターの値を代入して出力する

function my_shortcode_atts_default( $atts ) {
	$atts = shortcode_atts(
		array(
			'title' => 'My Title',
		),$atts);
	
$output_before = '出力する内容「';
$output_after = '」出力する内容';
	
	return $output_before .$atts['title'] .$output_after;
}
add_shortcode('sc-atts-default', 'my_shortcode_atts_default');

このまま上記コードをfunctions.phpへ追記し、投稿や固定ページの編集画面で以下のショートコードを挿入した後に、プレビューで表示すると、ショートコードの部分が、【出力する内容「My Title」出力する内容】という文字として表示されます。

[sc-atts-default]

次に、以下のショートコードを挿入してプレビューしてみてください

[sc-atts-default title="パラメーターの内容"]

ショートコードの部分が【出力する内容「パラメーターの内容」出力する内容】に変化したのを確認してください。

これがパラメーター機能です。

上記コード中の以下の部分でパラメーターの設定とショートコードにパラメーター指定がない場合の出力内容（デフォルト値）が書かれています（以下のコードでは「title」というパラメーターに「My Title」というデフォルト値が設定されています）。

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

このパラメーターの値は、内容を出力させるための以下のコードのように、「$atts[‘パラメーター‘]」で呼び出すことができます。

return $output_before .$atts['title'] .$output_after;

上記のサンプルコードではパラメーターはtitle１つにしていますが、いくつでも追加して使用することができます。

内容の変更やパラメーターの追加などをして、いろいろと試してみてください。

いろいろ試していただいたときに1点お気づきになりませんでしたか？

それは、ショートコードにパラメーターの記述があって、内容がないときに表示内容がおかしくなる現象です。

具体的には以下のようなショートコードを挿入したときに発生します。

[sc-atts-default title=""]

このショートコードでプレビュー表示すると【出力する内容「」出力する内容】と、カギ括弧の中が何もない状態になってしまいます。

いろいろ試してこれに気づいた方はすばらしい、👏👏👏👏です（笑）

原因は、パラメーターがあったら指定したものへ変更してくださいね！というパラメーター付きショートコードの特性にあります。

つまり「title=””」と「”」の間に何もない（空）を指定しているから、指示通り何も表示しないようになっているのです。バグではなく、正確に処理されている証拠といえます。

実はショートコードについていろいろなサイトやページで作り方の紹介がされていても、この現象に対する対処については、あまり紹介されていません。

自身で使うサイトで自身だけで使用するならよいのですが、そうでない場合は「何で？」と聞かれること必至ですからきちんと対処しておきましょう。

具体的には以下のようにします。

function my_shortcode_atts_emp_default( $atts ) {
	$atts = shortcode_atts(
		array(
			'title' => 'My Title',
		),$atts);
	
	if(empty($atts['title'])){
		$atts['title'] = 'Your Title';
	}else{
		$atts['title'] = $atts['title'];
	}

$output_before = '出力する内容「';
$output_after = '」出力する内容';
	
	return $output_before .$atts['title'] .$output_after;
}
add_shortcode('sc-atts-emp-default', 'my_shortcode_atts_emp_default');

functions.phpへ追加するコードは先のコードと入れ替えていただいても、新たに追加しても大丈夫です

このコードをfunctions.phpへ挿入（または入れ替え）後、以下のショートコードを挿入してプレビューしてみてください。

[sc-atts-emp-default title=""]

ショートコード内のtitleパラメーターが未指定（空）でも、きちんと【出力する内容「My Title」出力する内容】になっていますよね？

ならない．．という方は、今一度コード挿入の確認とショートコードの確認をしてください（対策済のショートコードは、先のショートコードと区別するため、sc-atts-emp-defaultにしています）。

前後に紹介したコードの違いを確認してみましょう。

後で紹介したコードには以下の記述が追加されていますね。

if(empty($atts['title'])){
$atts['title'] = 'Your Title';
}else{
$atts['title'] = $atts['title'];
}

これは、

1. 「$atts[‘title’]（titleというパラメーター）」がempty（空）だったら、「$atts[‘title’]」には「Your Title」という文字を格納（表示）させなさい
2. 「$atts[‘title’]（titleというパラメーター）」がempty（空）でなかったら、「$atts[‘title’]」には「$atts[‘title’]」パラメーターの値を格納（表示）させなさい

という意味のコードで、これを加えることで、

1. 「$atts[‘title’]（titleというパラメーター）」がショートコード内になかったら「$atts[‘title’]」には「Your Title」という文字を格納（表示）させなさい
2. 「$atts[‘title’]（titleというパラメーター）」がempty（空）だったら、「$atts[‘title’]」には「Your Title」という文字を格納（表示）させなさい
3. 「$atts[‘title’]（titleというパラメーター）」がempty（空）でなかったら、「$atts[‘title’]」には「$atts[‘title’]」パラメーターの値を格納（表示）させなさい

という、まずは当初のコードでショートコードにパラメーターが書かれているかを判定して処理をし、パラメーターがあったらどうするというのを判定して処理するようになり、パラメーターのあるなしに関わらずきちんと処理されるようになるのです。

ここまで自己完結型のショートコードの作成方法を紹介してきました。

どうでしょう？問題なくできましたか？

次に紹介する囲み型ショートコードは、基本的に自己完結型のショートコードにちょっと手を加えればよいものですので、まずはここまでしっかり理解しましょう。

って私も完全ではないので、こうして解説記事にしていつでもおさらいできるようにしてるんですけどね（笑）。

囲み型ショートコードの作成方法

前述した通り、囲み型ショートコードと自己完結型ショートコードは以下のような違いがあるだけで、基本的なプログラムの記述方法に変わりはありません。

• 開始ショートコードと終了ショートコードがあり、その間にある文字列やブロックがショートコードでの制御対象になる
• プログラム上では、ショートコード間にある文字列やブロックがあるという記述を追加する

具体的にプログラムの基本構造は以下のようになります。

function my_shortcode_su_default($atts, $content = null) {

return $content;
}
add_shortcode('sc-su-default', 'my_shortcode_su_default');

自己完結型ショートコードとの違いは先頭行の(括弧)の中に、「$atts, $content = null」というのを追加するだけです。

これを書くことで囲み型ショートコードになる、と一種おまじないのように考えればよいでしょう。

上記コードの場合、投稿や固定ページでの編集画面で

[sc-su-default]囲みショートコード内の文章[/sc-su-default]

と書いてプレビューすれば、「囲みショートコード内の文章」という文字が表示されるはずです。

パラメーターを持たない囲み型ショートコード

例えば、ショートコードで囲んだ文章に外枠を付けたいといったケースで使用されることが多い形です。

以下のようなコードをfunctions.phpへ追加してみてください。

function my_shortcode_su_nopara($atts, $content = null) {
$div_before ='<div class="border-content">';
$div_after ='</div>';

return $div_before .$content .$div_after;
}
add_shortcode('sc-su-nopara', 'my_shortcode_su_nopara');

そして以下のショートコードを投稿編集画面に加えてプレビューしてください。

[sc-su-nopara]囲み型ショートコードの内容[/sc-su-nopara]

単純に「囲み型ショートコードの内容」という文字列が表示されます。

そして、以下のコードをテーマカスタマイザーの追加CSSや子テーマのstyle.cssへ追加してみてください。

.border-content {
    border: 2px solid #000000;
    border-radius: 4px;
    padding: 4px;
}

再びプレビューすると．．．黒い線で囲まれた「囲み型ショートコードの内容」という文字列が表示されます。

そう、上記のプログラムは、border-contentというクラスを持つdiv要素の中にショートコードで囲まれた文字列を表示しなさいというものです。

そして、追加CSSなどへスタイルコードを追加することで、外枠が表示されるようになるのです。

使い道はこれに限らずいろいろあって、例えば以下のプログラムを追加して、

function ha_onlypc_show( $atts, $content = null ) {
if(!wp_is_mobile()) {

	return $content;
} else {
	return '';
}
}
add_shortcode('pc-only', 'ha_onlypc_show');

以下のショートコードを追加すると、を入れると、パソコンでアクセスされたときだけ「パソコンの時だけ表示」という文字列を表示させることができます。

[pc-only]パソコンの時だけ表示[/pc-only]

もちろん、複数のブロックをこのショートコードで囲めば、ショートコードで囲んだブロックすべてがパソコンから閲覧したときだけ表示されるようになります。

パラメーターを持つ囲み型ショートコードの作成方法

ここまでくると「パラメーターなしの囲み型ショートコードに自己完結型でやったパラメーター設定をすればいいんでしょ！」ともう恐らく肌感覚でわかるかと思います。

例として、以下のようなコンテンツが作れます

ここでは「ショートコード内のボックスタイトル」となっているところを任意に変えられるようにするためにパラメーターを使用します。

以下をfunctions.phpへ追加してください。

function my_shortcode_box($atts, $content = null) {

$atts = shortcode_atts(
array(
'title' => 'Box Title',
),$atts);

if(empty($atts['title'])){
$atts['title'] = 'Box Title';
}else{
	$atts['title'] = $atts['title'];
}

$div_before ='<div class="border-content"><div class="box-title">';
$div_mid ='</div><div class="box-content">';
$div_after ='</div></div>';

$content = $div_before .$atts['title'] .$div_mid .$content .$div_after;

return $content;
}
add_shortcode('sc-su-box', 'my_shortcode_box');

そしてパラメーターなしの囲みショートコードと同じように、スタイルコードを追加します。

.border-content {
    border: 2px solid #000;
    border-radius: 8px;
    overflow: hidden;
}

.box-title {
    background: #000;
    color: #fff;
    padding: 8px;
    font-size: 1.2em;
}

.box-content {
    padding: 12px;
}

そして以下のショートコードを入れて、プレビューしてみると、サンプルのようなボックスコンテンツが表示されます。

[sc-su-box title="ショートコード内のボックスタイトル"]ボックスの中身[/sc-su-box]

これまでの自己完結型、囲み型のショートコードの応用ですので、詳しいコード内容は割愛しますから、じーっと見比べてどうなっているのかを確認ください。

今回のショートコードでは、

• ショートコードで囲んである文字列やブロックがボックス内に表示される
• titleパラメーターがない、またはパラメーターはあるけど空の場合は「Box Title」という文字列をボックスタイトルとして表示
• titleパラメーターに入れた任意の文字列がボックスタイトルとして表示される

囲み型ショートコードの中で別のショートコードを実行する

ここまでくるとカオスな感じもしますが、囲み型ショートコードで囲んだ範囲にショートコードを挿入して実行させたいということがあると思います。

もしも自身で囲み型ショートコード用のプログラムを作ってみて、その中に別のショートコードを入れても動作しなかった場合には、以下のコードを、コンテンツの返却（「return」行）よりも前に挿入すると解決できます。

//ショートコードの中にショートコードがあっても実行
	$content = do_shortcode( shortcode_unautop( $content ) );

コードの意味としては、$content(出力するコンテンツ)の中にショートコードと判定できるものがあったら、段落タグを解除（つまりはショートコードを実行）しなさいというものです。

ここまでいろいろな形式のショートコードの基本的な作り方を紹介してきました。

ここからはショートコードを作る際のヒント、疑問となりそうな事柄の解決方法ですので併せてご覧ください。

独自ショートコードを作る際の補足事項

shortcode_attsにextract()を使用する必要があるかの判断

PHPの解説ページやWordPressのショートコードの作り方などを見ていると、shortcode_attsの一連のコードをextract()で囲むことで、「無効なキーを除外したキーと値の連想配列」として処理してくれるなんて書いてあります。

私も正確には理解していませんが、以下のようなことをしてくれます。

• shortcode_attsで指定したキー（パラメーター）がショートコード内にあるかどうかを判別する
• パラメーターがない、または、指定した以外のパラメーターがある場合は無視して処理する
• 本来「$atts[‘パラメーター’] 」で代入すべきパラメーターの値を「$パラメーター」という変数で代入できるようにしてくれる

一見便利そうに見えますが、これで囲まないとどうしても思ったように動作しないという場合を除き、使用する必要はないでしょう。

shortcode_attsにextract()を使用する機会

一見必要ないと思われるextract()ですが、1つのパラメーターに対して複数条件を指定する場合には重宝します。

ただ、以下のようにして使わないと思わぬ結果が出る可能性がありますから注意が必要です。

1. extract()を使ってパラメーターを配列として扱うようにする
2. $argsを使ってパラメーターを変数に変換する
3. 条件にexplode()を使って複数のパラメーター値の区切り文字を指定する

よくわからないのがたくさん出てきましたね。

例として、ショートコードで囲まれた部分を投稿タイプで出しわける囲み型ショートコードのサンプルコードを紹介しておきます。

/***** 投稿タイプで制限するショートコード *****/
function ha_conditon_postytpe_sc($atts, $content = null){
//パラメーターの設定（extractで配列として取得させる）
	$atts = extract(shortcode_atts(
	array(
	'posttype' => 'post',
	),$atts));

//投稿タイプを変数として扱う
	$args = array(
	'posttype' => $posttype,
	);

//パラメーターはあるけど空の場合
	if(empty($posttype)){
		$posttype = 'post';
	}

//投稿タイプの条件をセット
	$post_type_set = is_singular(explode(",",$posttype));

//ショートコードの中にショートコードがあっても実行
	$content = do_shortcode( shortcode_unautop( $content ) );

//パラメーターで指定した投稿タイプでのみショートコード内コンテンツを出力
//未設定の場合は「post(投稿)」のみ
	if($post_type_set){
		return $content;
	}

}
add_shortcode('ptype-rest-sc','ha_conditon_postytpe_sc');

くどいようですが、以下の流れで表示／非表示の切り替えをさせています。

1. posttypeというパラメーターを使い、パラメーターは配列（extract()）で取得します
2. posttypeというパラメーターは今後のプログラム上では$posttypeという変数で表します
3. posttypeというパラメーターがショートコード内にあるけど空の場合はpost(投稿)を$posttypeへ格納します
4. is_singular()で投稿タイプの限定をするが、posttypeパラメーターの中に書かれている「,」で区切られた文字列は別のものとして扱う（explode()）
5. ショートコードの中にあるコンテンツ（$content）内のショートコードは文字列として扱わず実行する
6. 上記の条件を基にショートコードで囲まれたコンテンツの表示／非表示をする

上記のコードをテーマのfunctions.phpへ追加した場合には、以下のショートコードを使います。

[ptype-rest-sc posttype=""]
ショートコード内のコンテンツ
[/ptype-rest-sc]

補足　エラーで保存できないときに確認することいろいろ

PHPで何かのコードを作ろう！どこかに載ってるコードを流用しよう！とコードを追加するも、エラーとなって保存できなかったり、テーマエディタ外から編集したら「重大なエラー．．」などと表示されてサイト自体が動作しなくなってしまったなんて経験が、初心者の方にはあろうかと思います。

ネット情報の中には、WordPressのテーマエディタは使わない方がいいという意見もありますが、コードエディタでエラーとなるような記述をして保存した場合、エラー内容が表示され、未保存の状態でストップしてくれ、サイト自体がストップしてしまうことがないので、個人的にはテーマエディタの使用をおすすめしています

そこで、本ページ自体とは直接関係はないものの、よくある構文エラーの対処方法のヒントを紹介しておきます。

return '';
または
return "";
または
return $変数;

return $変数A .$変数B;

return '文字列' .$変数A. '文字列';

ショートコードをテンプレート内で使用する方法

ショートコードを投稿テンプレート（single.php）や固定ページテンプレート（page.php）内で使用する場合は、以下のようにします。

自己完結型と囲み型、テンプレート内のPHPコードの書き方でそれぞれ異なりますので注意してください。

ショートコード内のパラメーターの囲み文字が「’」の場合は、ショートコード前後の囲み文字を「”」にするなど、同じ記号で囲まないようにしましょう

自己完結型ショートコードの場合

独立したPHPで書かれているテンプレートの場合

<?php echo do_shortcode('[ショートコード]'); ?>

1つのPHPでまとめて書かれているテンプレートの場合

echo do_shortcode('[ショートコード]');

囲み型ショートコードの場合

開始ショートコードと終了ショートコード前後にのみ囲み文字があるのがポイントです

独立したPHPで書かれているテンプレートの場合

<?php echo do_shortcode('[ショートコード名]コード内の内容[/ショートコード名]'); ?>

1つのPHPでまとめて書かれているテンプレートの場合

echo do_shortcode('[ショートコード名]コード内の内容[/ショートコード名]');

ブロックエディタでショートコードを便利に呼び出せるようにする方法

ここまで紹介したように、ショートコードは、いろいろなことを自由に編集画面で、見ながらその場で変えることができるブロックまでの機能を持たせるのは難しいものの、定型文を入れたり、表示の制御をしたりということができる便利な機能です。

しかし、ブロックエディタ上で使用する際に困るのが、「あれ？その機能のショートコードってなんだっけ？」となってしまう点です。

せっかく作ったショートコードなのに使えなかったらもったいないですね。

そこでブロックエディタのブロックパターンという機能を利用して、ショートコードを簡単に呼び出せるようにする方法を最後に紹介しておきます。

任意のブロックパターンを追加する

ブロックパターンは、いろいろな形に設定されているテンプレート（パターン）を呼び出して加工することで簡単にいい感じのコンテンツが作れるようにする機能です。

標準では、登録されているパターンの中から選択するだけの機能のみ実装されていますが、テーマのfunctions.phpへコードを追加することで、自身で制作したパターンを登録することもできます。

この機能を使って、ショートコードを簡単に呼び出そうというのがここでの目的です。

ブロックパターンに任意のカテゴリーを追加する

以下のコードをfunctions.phpへ追加して、ブロックパターンの一覧へ任意のカテゴリー（今回の場合はショートコード類を入れるカテゴリー）を追加します。

/***** ブロックパターンカテゴリーの登録 *****/
function ha_sc_block_pattern_category_init(){
	register_block_pattern_category('sc-pattern-category', ['label' => __('Original Shortcode','textdomain')]);
}
add_action('init','ha_sc_block_pattern_category_init');

コード内の「Original Shortcode」の部分を任意の文字列にすることで、カテゴリーの表示名を変更できます

作成したカテゴリーへショートコードを入れたパターンを登録する

前項で追加したカテゴリーへブロックパターンとして、作成したショートコードを1つ1つ追加していきます。

以下はfunctions.phpへ追記するための基本となるコードです。

/* ショートコード１ */
function ha_block_patterns_init_a(){
  $pattern = [
    "title" => __('Block Pattern 1','textdomain'),
    "categories" => ["sc-pattern-category"],
    "descripiton" => '',
    "content" => 'ショートコードの内容',
  ];

  register_block_pattern($pattern["title"], $pattern);
}
add_action('admin_init', 'ha_block_patterns_init_a');

コード中の「Block Pattern 1」を変更すると表示名が変わります。

「ショートコードの内容」の部分は、以下のようにして作ったものをコピーします。

1. 投稿の新規作成で、ショートコードブロックを追加する
2. 作成したショートコードをショートコードブロックへ書く
3. ショートコードブロック（またはブロックパターンとして登録するブロック群）をコピーする
4. メモ帳などへ一度貼り付ける（貼り付けたものがブロックを形成するコードです）
5. 4を「ショートコードの内容」と入れ替える

2つ以上のブロックパターンを登録する場合には、上記コードをコピーして、

• ユーザー定義関数名（ha_block_patterns_init_a）を別名にする（ha_block_patterns_init_bなど）
  ※ユーザー定義関数名は先頭行と最終行の2か所ありますのでご注意ください
• titleの表示名（Block Pattern 1）を変更する
• ショートコードの内容を変更する

という作業を必要分だけ繰り返してください。

実際に呼び出してみる

ブロックカテゴリー、ブロックパターンの登録が終わったら、実際に投稿編集画面から、

1. ブロックの追加をクリック
2. 「すべて表示」をクリック
3. 「パターン」タブをクリック
4. プルダウンメニュー（WordPress6.0.1のデフォルトでは「注目」になってる部分）をクリックして、先ほど追加したカテゴリーをクリック
5. 目的のショートコードをクリック

して、きちんとショートコード（ブロック）他が追加されるかを確認ください。

本記事の更新（変更）履歴