ブログ初心者・Web制作の情報サイト
【WordPress】ショートコードの書き方と注意点

【WordPress】ショートコードの書き方と注意点

この記事ではWordPressでWebページを作成する際に便利なショートコードの書き方とその注意点を紹介します。

ちょっとした機能を追加したいときや、独自の機能が欲しいと思ったとき、プラグインを使うまでもない小さな機能などはショートコードを作ればエディタ上で簡単に追加することができます。

ショートコードを覚え使いこなせるようになれば自分が欲しい機能を手軽に呼び出せるのでWebページ作成が楽になりますよ。

ショートコードで出来ること

ショートコードで出来ることの例を紹介します。ここであげているのはほんの一例です。

  • 投稿を取得し表示する
  • カテゴリー一覧を取得し表示する
  • WordPressのエディタ上でアイコンフォントを挿入する
  • 文字列に特定の処理を加える
  • 目次のような形式の決まったデータを表示する

ショートコード内にはPHPを記述します。PHPで出来ることはショートコードで実現できるといっても間違いではないでしょう。つまり何でも出来るわけです。

ショートコードの書き方

WordPressにおけるショートコードとはユーザーが作成したコードを呼び出すための機能です。HTMLへ任意のデータを追加するときによく使われます。

ショートコードの作り方

ショートコードの作成はとても簡単で add_shortcode() に関数を渡すだけで作成可能です。以下に例を示すので実際に作成してみて下さい。コードは functions.php に記述します。

add_shortcode('my_shortcode', function($atts) {
    //実際の処理
});

add_shortcode(ショートコード名, 登録する関数);

ショートコード名呼び出すときに使用する名称を記述します。
登録する関数ショートコードで実行する関数を指定します。

ショートコードの実行

呼び出し方は登録したショートコード名を [] の中に記述します。ショートコードのブロックを使うとエディタ上で識別しやすくなります。

[my_shortcode]

ショートコードブロックは ウィジェット > ショートコードから呼び出せます。

WordPress ショートコードブロック

引数の書き方

引数を書く方法は値で書く方法と属性を指定して書く方法の2種類があります。

■値で書く

add_shortcode('my_shortcode9', function($atts) {
    $atts = shortcode_atts(array(
        'fruit' => $atts[0],
    ), $atts);
    extract($atts);

    return '好きな果物は'. $fruit;
});

shortcode_atts() は配列の要素をマージします。第一引数の配列内にあるキーが第二引数(ここでは $atts)に存在すれば値を代入し、なければキーと値を新しく追加します。extract() は配列のキーと値を変数に変えるPHP関数です。

[my_shortcode メロン]
実行結果

好きな果物はメロン

■属性を指定して書く

add_shortcode('my_shortcode', function($atts) {
    $atts = shortcode_atts(array(
        'country' => 'フランス',
        'visit_frequency' => 1,
    ), $atts);
    extract($atts);

    $str = '私は'.$country.'を'.$visit_frequency.'回訪れたことがあります。';
    return $str;
});
[my_shortcode country=カンボジア visit_frequency=2]
実行結果

私はカンボジアを2回訪れたことがあります。

country、visit_frequency の初期値はそれぞれフランスと1ですが引数に同じ属性を指定することでそれらを上書きできます。上の例では国をカンボジア、訪問回数を2に変えています。

文字を囲んで書く方法

範囲内の文字列に対して処理を行う方法です。

[shortcode_name]ショートコードに渡す文章[/shortcode_name]

上のように書くと囲まれた範囲の文章をショートコードに渡し処理を行うことができます。PHPには文字列を操作する関数が多く用意されているので多様な処理を行えますよ。

PHP: String関数

■例1:アルファベットを小文字にして返す

add_shortcode('comoji', function($atts, $content) {
    return strtolower($content);
});

範囲で囲った文字列は関数の第二引数(ここでは$content)に入るので、この文字列を strtolower() で小文字に換えて返しています。

[comoji]ショートコードでPHPのSTRING関数を使えばWORDPRESSエディタで様々な文字列処理を行うことができますよ。[/comoji]
実行結果

ショートコードでphpのstring関数を使えばwordpressエディタで様々な文字列処理を行うことができますよ。

■例2:特定の文字列を置換する

add_shortcode('my_str_replace', function($atts, $content) {
    $atts = shortcode_atts(array(
        'from' => 'null',
        'to' => 'ヌル',
    ), $atts);
    extract($atts);

    return str_replace($from, $to, $content);
});

文字列を引数で指定して範囲内のマッチ部分を置換します。この例では from にショートコード、to に</>を指定して変換しました。

[my_str_replace from=ショートコード to=</>]ショートコードはとても便利。自分が欲しい機能をショートコードで作ればエディタでの作業がとても楽になります。簡単な機能はプラグインを使わずショートコードで実現しよう。[/my_str_replace]
実行結果

</>はとても便利。自分が欲しい機能を</>で作ればエディタでの作業がとても楽になります。簡単な機能はプラグインを使わず</>で実現しよう。

再利用可能ブロックを使用してさらに便利に使い回す

目次や関連記事表示のようなデータで引数を使わないまたは引数を変える必要がないものは再利用可能ブロックを使用して使い回すと便利です。

再利用可能ブロックとはブロックを登録して呼び出せるようになるお気に入りのような機能です。

使用方法

再利用可能ブロックにするにはブロックを選択し再利用ブロックに追加を選ぶと登録されます。

WordPress 再利用可能ブロックに追加

呼び出したいときは再利用可能から登録したブロックを選択すればOKです。

WordPress 再利用可能ブロック呼び出し

ショートコードが表示されないときに確認する項目

ショートコードを作成するときに注意すべき項目を紹介します。

初めてショートコードを作ると思ったように動かなかったりエラーが出たりすることがあると思います。そんな時は下記項目をチェックしてみて下さい。

文字列の打ち間違い

ショートコードを呼び出す際は、登録したショートを手打ちするとよく間違えます。文字列は打ち間違えてもエディタ上では分からないので注意が必要です。

コードからコピー&ペーストするか全角で入力し予測変換の機能を利用することで間違いを減らすことができます。

ショートコードに限らず文字列は打ち間違いやすいのでコードを書く際はミスが起こりにくいような方法で記述することが大切です。

必ず return を返す

HTMLに出力するときは必ず return を返しましょう。忘れると何も出力されません。

function my_say_hello() { 
    return '<p>Hello</p>';
}
add_shortcode('say_hello', 'my_say_hello');
実行結果

Hello

echo は使わない

ショートコードでは実行する関数では echo はそのまま使えません。

echo を使用すると意図しない場所に出力されてしまいます。さらに下記のような保存できないエラーも発生するので注意してください。

WordPress 更新に失敗しました。返答が正しいJSONのレスポンスではありません。

add_shortcode() は function の外に記述する

add_shortcode() と function を分けて書いたとき add_shortcode()をうっかり function の中に書いていたとういうミス。

//間違いの例
function my_say_hello() { 
    add_shortcode('say_hello', 'my_say_hello');
    return '<p>Hello</p>';
}

エラーは発生しておらず、コードにも文字列にも間違いがないのにショートコードが動かないというときに起こっていたりするのがこのミスです。

function の中に add_shortcode() を書くとadd_shortcode() が呼ばれなくなり登録されません。

この場合何も起こらずショートコードに書いた文字列がそのまま表示されます。

ショートコードブロックを使用する

稀にですが、段落にショートコードを書いている場合コードがうまく動かないことがあります。

ショートコードを使う場合はショートコードブロックを使用する方が、余計な不具合を防げる点で安全です。

最後に

ショートコードの作成方法と注意点について紹介しました。

ショートコードは一度作成すると使い回しができて便利です。WordPressを使っていてちょっとした機能が欲しいと思ったときは自分でショートコードを作成してみましょう。

後のWebサイト制作の手間を省くためにもショートコードを活用してどんどん機能としてまとめていくと楽しいですよ。