複数の記事で使用する内容や、PHPで生成が必要な場合はショートコードを作成することで記事の任意の場所に手軽に挿入が可能になります。

ショートコードとは？

ショートコードは投稿画面に[]で囲まれた短いコードを記述することでPHPの処理を走らせその結果をHTMLとして記事に埋め込むことが出来るワードプレスの機能です。

短いコードを記述･･･
直訳だよね？それって説明なの？

ツン子

そこはスルーしてよ！

ちたまん

基本的なショートコードの書き方

下記コードは単純なショートコードのプログラム例で基本的にはfunctions.phpに記述します。

<?php
function shortCodeFunc(){
  $html = '<h3>Hello</h3>';
	return $html;
}
add_shortcode('shortCodeName','shortCodeFunc');
?>

ショートコードを作成するにはadd_shortcode関数を実行します。

add_shortcode関数には二つの引数が必要で、以下のようになっています。

  • 第１引数：ショートコード名
  • 第２引数：出力用の関数名

上記コードの場合、ショートコード名は「shortCodeName」となっていますので、実際に使用するときには

[shortCodeName]

このように記事に書きます。そしてその時出力される内容は第２引数で指定した関数で決まります。この場合は「shortCodeFunc」が指定されていますのでshortCodeFunc関数が実行されます。

shortCodeFunc関数の中身を見てみると$hemlに簡単なhtmlコードを代入しreturnしていますので、結果として記事中に[shortCodeName]と書いた部分が$htmlの内容に置き換わって出力されます。

このようにショートコード出力で使用する関数はHTMLコードをreturnするようにしなければ動作しないです。

関数名とショートコード名は任意に決められますが、被らないように固有の名前である必要があるので命名規則を自分で決めておいた方がいいですね。

ShortCodeの略としての意味で頭に「st」と付けるとかね

ちたまん

引数付きのショートコード

先ほどの例では決まった内容を出力するだけでしたが、出力内容を変化させたい場合もあります。そのような時にはショートコードに引数を与えることも可能です。

function shortCodeFunc($atts){
  $html = '<h3>' . $atts[0] . 'さん、' . $atts[1] . '！</h3>';
	return $html;
}
add_shortcode('shortCodeName','shortCodeFunc');

このコードの場合

[shortCodeName 佐藤 こんばんは]

このようにショートコードを記述すると出力結果は

<h3>佐藤さん、こんばんは！</h3>

となります。このようにショートコード名の後にスペース区切りで引数を与えることができます。上記の場合は「佐藤」と「こんばんは」の２つの文字列を引数として与えています。このようにスペースで区切って複数の引数を与えることが出来ます。

関数のコードを見ると引数として「$atts」が設定されています。この変数名は何でもよいです。ここで指定した変数は配列になっており、ショートコードで指定した引数が順番に収められています。

そのため$atts[0]には「佐藤」、$atts[1]には「こんばんは」が入るという仕組みです

引数を連想配列として受け取る

さて先ほどのショートコードですが

[shortCodeName こんばんは 佐藤]

このように引数を反対にしたらどうなるでしょう？

<h3>こんばんはさん、佐藤！</h3>

当然このようになってしまいますね。

決まった順番で引数を入力しなければ正しく表示されません。しかしこれでは使い勝手が悪いです。

そこでコードを下記のように変更します。

function shortCodeFunc($atts){
  $html = '<h3>' . $atts['name'] . 'さん、' . $atts['word'] . '！</h3>';
	return $html;
}
add_shortcode('shortCodeName','shortCodeFunc');

$attsの仕様部分を連想配列にしました。ショートコードを使用する時には･･･

[shortCodeName name=こんばんは word=佐藤]

このように使用します。これで順不同でショートコードに引数を与えることが出来ます。

引数付きのショートコード利用時の注意点

このように引数を与えることでショートコードで出来ることが増えますが注意点もあります。色々あると思いますが、代表的な注意点として２つ紹介します。

引数はシングルコーテーションで囲むべし

上記のショートコードは正しく動作しますが、本来なら

[shortCodeName name=‘こんばんは’ word=‘佐藤’]

このようにシングルコーテーションで囲んだほうが良いです。例えば囲まずに「word=佐藤 太郎」としてしまうと$atts[‘word’]には「佐藤」しか入りません。スペースで区切られてしまうからですね。このように文字列中にスペースが入る場合はシングルコーテーションで囲む必要があります。

ただし文字列中にシングルコーテーションが入ると駄目ですので、その場合はダブルコーテーションを使います。ただシングルコーテーションはスペースに比べて出現頻度は少ないはずなのでシングルコーテーションで囲むことを癖づけたほうが良いです。

とはいえスペースやシングルコーテーションなど様々な記号が、入り乱れて出現する可能性もあると思います。そのような時の特徴として文字列も非常に長くなることが多いと思いますので、後に説明する「開始と終了のショートコードで囲む方法」が使い勝手が良いはずですので、利用を検討してみてください

引数のエラー処理を行うこと

上記コード例は単純な出力なので問題ないですが、例えば記事IDを引数に与えて記事の情報を出力させるなどのショートコードでは、記事IDの存在を確認して処理をする必要があります。

ショートコードは実際の表示だけでなく投稿画面でも中身が評価されています。もしショートコードでエラーが出ると記事が保存できなくなります。この際に画面を強引に切り替えるとエラーを起こした記事の投稿画面が表示できなくなることがあります。

号泣イメージ

苦労して書いた記事なのにショートコード改良してたら開かなくなった！
詰んだ？詰んだの！？

ちたまん

落ち着け！対策はちゃんとあるらしい。
ところで写真はちたまん本人？ｗｗｗ

ツン子

ショートコードのエラーで投稿画面が開かなくなった場合の対処

この場合の対処方法は２つあります。

  1. コードを正しく修正する
  2. ワードプレスのテーマを一時的に変更する

通常ショートコードはfunctions.phpに作成すると思いますが、そのコードに問題があるからエラーになるわけで、問題点を修正すれば表示されるはずです。ただどのように修正すれば問題が解決するのかすぐにはわからないことも多いですよね。

それに記事が消えてしまったとテンパってしまうと、正しい対処が出来なくなってしまいます。

修正してアップロードしたのに反映されない！？壊れた！？

ちたまん

違うディレクトリにアップロードしてたとかあるあるですよｗ

ツン子

落ち着いて作業しないと解決するものもしないです。そこでオススメなのがテーマを一時的に変更することです。

テーマを変更すれば該当のショートコードは存在しないことになります。存在しないショートコードはただの文字列として扱われますので、投稿画面が開けるようになります。

投稿画面を開いたら、該当のショートコードの記述のみ削除して記事を保存し、元のテーマに戻せばきちんと表示されます。一安心したところでゆっくりとコードを修正しましょう。

開始と終了のショートコードで囲む方法

ショートコードに使用する第１引数はショートコード側の引数の配列になるけど、第２引数を指定するタグのように囲んで使用することもできる

[shortCodeName]こんにちは[/shortCodeName]

こういう風に

function shortCodeFunc($atts,$content){
  $html = '<h3>'. $content .'</h3>';
	return $html;
}
add_shortcode('shortCodeName','shortCodeFunc');

ここでは第２引数として$contentを用意。ショートコードで囲まれた文字列が$contentに代入されるので出力は「こんにちは」となります。もちろんこの変数名も自由に設定して大丈夫。

引数との使い分けは？

引数に長い文字列を指定することは好ましくないです。単純に見難いのもそうですし、長い文字列には様々な記号が含まれるので、前述したように引数として正しく認識されない可能性があります。そんなわけで長い文字列はショートコードで囲ってしまうのが良いと思います。

また囲めるのは文字列だけでなく、ブロックなども対象ですので複数のブロックをグループ化してスタイルを適用したりもできます。

出力内容が多い場合の書き方

このようにショートコードを使えば様々なHTMLを記事中に埋め込むことができるけど、出力内容が多い場合は１行で代入することは困難。

３つの例を紹介する

<?php
// パターン１ 「.」でつないで記述
$html = '１行目'.
  '２行目'.
  '３行目'
  ;
// パターン２　「.=」で各行を記述
$html = '１行目';
$html .= '２行目';
$html .= '３行目';

// パターン３　バッファを使う
ob_start();
?>
１行目
２行目
３行目
<?php
$html = ob_get_contents();
ob_end_clean();

?>

パターン１ 「.」でつないで記述

これが最もスタンダートと思える方法。ただこの方法はまずHTMLとして読解性が悪いです。さらに「.」のつけ忘れや、消し忘れによるエラーを起こしやすいのが難点。メリットとしてはechoせずに変数を入れられることですが、変数を入れるとさらに読解性が落ちます。また改行コードは別途挿入する必要がある。

パターン２ 「.=」で各行を記述

これもパターン１とほぼ同じですが、各行が独立しているため行の間に別の処理を入れたり、行を挿入、組み換えが容易な点で優位と思ってます。10行くらいまではオススメ

パターン３ バッファを使う

PHPにはあらかじめ記述したHTML等のテキストをバッファに貯めて一気に変数に流し込む方法が用意されています。ob_start()もその一つ。この方法はHTMLをそのまま記述できる点が最大のメリット。改行もそのまま適用される。そのかわり変数の挿入はややめんどくさいけど大量にHTMLを出力するなら最もおすすめ。よく似たものにヒアドキュメントもあるけど、ヒアドキュメントは行頭にタブやスペースを入れられないので気持ち悪いので却下

それぞれ一長一短があるので、状況に応じて使い分けたほうがいいと思います。

まとめ

  • ショートコードを使うと記事にPHPで生成したHTMLを埋め込める
  • ショートコードには引数が使える
  • 引数の使用時には注意点がある
  • ショートコードで文字列等を囲む使い方もある

という感じです。色々書きましたがショートコードの使い方自体は難しくないですので、いろいろ試しながら慣れていけば十分に使えるようになりますよ。

完全攻略はやっぱり言い過ぎだと思うけど？

ツン子

安心しろ！
僕は吐いた唾を飲める漢だ！

ちたまん

汚い！無理！

ツン子