ブログの始め方・WordPress・レンタルサーバー
B!

WordPress ショートコードの書き方と引数の指定方法

WordPress ショートコードの書き方と引数の指定方法
UPDATE:
CATEGORY:
WordPress
TAG:
ショートコード

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

ちょっとした機能を追加や独自機能、プラグインを使うまでもない小さな機能などはショートコードで簡単に作成できます。

この記事ではWordPressのショートコードの書き方・作り方・引数の指定方法・ショートコードが表示されないときの対処法を紹介します。

ショートコードの書き方

ショートコードの作成はadd_shortcode()に、登録名と関数を渡すだけです。

コードはfunctions.php等に記述します。

//ショートコードの書き方1
add_shortcode('my_shortcode', function ($atts) {
    //実際の処理
});
//ショートコードの書き方2
function my_callback($atts) {
  //実際の処理
}
add_shortcode('my_shortcode', 'my_callback');
//Code Reference
add_shortcode( string $tag, callable $callback )
$tagショートコードの登録名。呼び出すときに使用する。
$callbackショートコードで実行する関数

ショートコードの呼び出し方は、登録したショートコード名を [] の中に記述します。

//ショートコードの呼び出し方
[my_shortcode]

ブロックエディタの場合は「ショートコードブロック」を使う方がおすすめです。

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

ショートコードブロックを使えば、WordPress側の文字修正が起ここらないので余計なトラブルを回避できます。視覚的にもどこにショートコードがあるか分かりやすいです。

ショートコードはエディタだけでなくウィジェットでも使用できます。

引数の書き方

ショートコードに引数を書くときは、ショートコード名の後に半角スペースを挟んで値を書きます。

//引数の書き方
[my_shortcode 引数1 引数2]

値は配列に格納されるので、取り出す場合は次のように記述します。

function my_callback($atts) {
  //引数の値を取り出す
  $arg1 = $atts[0];
  $arg2 = $atts[1];
}

ショートコード引数の書き方は「値で書く方法」と「キーと値をペアにして書く方法」の2種類があります。

引数に値をそのまま書く

//引数に値をそのまま書く
[my_shortcode メロン]

// 実行結果
/* 好きな果物はメロン */
add_shortcode('my_shortcode', function ($atts) {
  $atts = shortcode_atts([
    'fruit' => $atts[0],
  ], $atts);
  extract($atts);

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

shortcode_atts()は配列の要素をマージします。

extract()は配列内の要素を変数に変えるPHP関数です。

簡単に説明すると、変数として扱いやすい形に変換しているだけです。言葉で説明するよりも実際にコードを使ってみる方が分かりやすいと思います。

キーと値をペアにして書きたいときは次の方法を使ってください。

キーと値をペアにして書く

//キーと値をペアにして書く
[my_shortcode country=アメリカ num=2]

// 実行結果
/* 私はアメリカを2回訪れたことがあります。*/
add_shortcode('my_shortcode', function ($atts) {
  $atts = shortcode_atts([
    'country' => 'フランス',
    'num' => 1,
  ], $atts);
  extract($atts);

  $str = '私は'. $country . 'を' . $num . '回訪れたことがあります。';
  return $str;
});

country, numの初期値はそれぞれ「フランス」と「1」ですが、引数に同じキーを指定することでそれらを上書きできます。

上の例では国を「アメリカ」、訪問回数を「2」に変更しています。

引数に配列を渡す方法

ショートコードの引数に配列を渡そうとしても、普通の書き方では渡せません。

追加のコードを書いて配列に変換する必要があります。

文章を引数に渡す

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

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

上のように書くと囲まれた範囲の文章を引数に渡して処理を行うことができます。

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

add_shortcode('comoji', function($atts, $content) {
  return strtolower($content);
});
[comoji]ショートコードでPHPのSTRING関数を使えばWORDPRESSエディタで様々な文字列処理を行うことができます。[/comoji]

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

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

特定の文字列を置換する

add_shortcode('my_str_replace', function($atts, $content) {
  $atts = shortcode_atts([
    'str' => 'null',
    'to' => '',
  ], $atts);
  extract($atts);

  return str_replace($str, $to, $content);
});
[my_str_replace str=ショートコード to=shortcode]ショートコードはとても便利。自分が欲しい機能をショートコードで作ればエディタでの作業がとても楽になります。簡単な機能はプラグインを使わずショートコードで実現しよう。[/my_str_replace]

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

ショートコードが表示されないとき

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

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

  • 返答が正しいJSONのレスポンスではありませんと表示される
  • echo()は使わないこと・コードをデバッグする
  • 必ず「return」を返すこと
  • 文字列の打ち間違いに注意する
  • ショートコードブロックを使用する

「返答が正しいJSONのレスポンスではありません」と表示される

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

初めてショートコードを触った人なら誰もが目にするエラーです。

大抵の場合は、echo()が原因です。

関数内でecho()を使ってHTMLを出力すると上のようなエラーが起こります。ショートコードではecho()はそのまま使えません。

HTMLコードは文字列にしてreturnしましょう。

function my_callback($atts) {
  $str = '<p class="">' . 'ショートコード内ではHTMLを出力しない' . '</p>';
  return $str;
}

echo()を使用すると投稿の保存時にエラーが起こります。保存が完了しないので注意してください。

var_dump()でも同じエラーが起こります。

ショートコードのデバッグ方法

var_dump()などのデバッグ関数は内部でHTMLを出力します。

ショートコードの場合このままではエラーが起こるので、バッファを使ってください。

//ショートコードのデバッグ方法
function my_callback($atts) {
  //バッファ
  ob_start();
  var_dump($atts);
  return ob_get_clean();
}

ob_start()でバッファリングが有効になり、ob_get_clean()でバッファの内容を取得できます。

この方法ならecho()も使用可能です。

必ず「return」を返す

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

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

文字列の打ち間違いに注意する

個人的にこのミスはとても多いです。

登録したショート名を手打ちするとよく間違えます。文字列は打ち間違えてもエディタの校正機能が働かないので注意が必要です。

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

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

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

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

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

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

WordPressのショートコードまとめ

WordPressのショートコードの書き方・作り方・引数の指定方法・ショートコードが表示されないときの対処法を紹介します。

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

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

パラメータの複雑なショートコードはブロックパターンを作成して呼び出しすのがおすすめです。

B!
CATEGORY:
WordPress
TAG:
ショートコード
ブログを作りたい人へ。
ブログを始めたいと思っても実際に何をすればいいか分からないかもしれません。ブログを作りたい人へWordPressの始め方と必要な基礎知識を解説します。具体的なブログの始め方と関連記事を一覧にまとめているので参考にしてください。
Read More
  1. Home
  2. WordPress