【WordPress】ショートコードを自作する方法と応用例や注意点

今回は、WordPressの「ショートコード」の作り方と使用方法、そして応用例や作る際の注意点を解説したい。

主に使用するもの

ショートコードを組み立て、使用する際に使うファイルの場所を紹介する。

子テーマの「functions.php」

おもに、というかほぼこのファイルしか使わない。

ただし、もしあなたが使用しているテーマにショートコード用のPHPファイルが用意されていたら、そちらを使ったほうがいいかもしれない

子テーマの「style.css」

こちらは必要に応じて使う。

インラインでCSSを書く方法もあるが、やはりfunctions.phpの容量が増えてしまう。なので、ショートコードで作った要素のデザインを変えるときは、極力CSSファイルを利用しよう。

ショートコードの簡単な解説

まず、ショートコードには、大きく分けてふたつの種類が存在する。

まずは、「完結型ショートコード」と呼ばれるもの。

つまり

[hoge]

のような、角括弧で囲んだだけのもの。

そして、もうひとつが

[hoge]hogehogehoge[/hoge]

といった「囲み型ショートコード」と呼ばれるものだ。

おそらく、完結型のショートコードのほうが、使用する機会も自作する機会も多いだろう。

また、ショートコードには「引数」を設定することもできる。

例えば

// 完結型
[hoge late=good]

// 囲み型
[hoge link="https://hoge.com"]hoge watch![/hoge]

とすることで、表示する画像を変えたり、リンク付きのボタンを表示したりすることが出来る。

これらが、主な機能となっている。

ショートコードの作り方

それでは、実際にショートコードを作ってみよう。

使用した関数の解説は後にするので、まずはコピペして作って実感してみてほしい。

完結型ショートコード

まずは、完結型と呼ばれるものだ。こちらは簡単に作ることが出来る。

ショートコードの例

// ショートコード：[mycus_hellow]
function mycus_hellow_world_func() {
  $message = '<p>Hellow World!</p>';
  return $message;
}
add_shortcode('mycus_hellow', 'mycus_hellow_world_func');

このショートコードを使い

[mycus_hellow]

とブロックエディターの段落に入力することで、本文中に

出力される文字列

Hellow World!

が出力表示される。

これが基本的な作り方になる。

引数を追加する

しかし、これでは別の文字列を表示したいとき、また新たにショートコードを作る必要が出てくる。

そこで、ショートコードに配列「$atts」を追加して、「World」の部分を自由に変更できるようにしてみよう。

つまり、「Hellow World!」を「Hellow Space!」と出力できたりする、ということだ。

ショートコードの例

// ショートコード：[mycus_hellow_any]
function mycus_hellow_any_func( $atts ) {
  $word = shortcode_atts( array(
    'world' => 'World'
  ), $atts );
  $message = '<p>Hellow ' . $word['world'] . '!</p>';
  return $message;
}
add_shortcode('mycus_hellow_any', 'mycus_hellow_any_func');

このショートコードは

[mycus_hellow_any world=Space]

このように入力することで

出力される文字列

Hellow Space!

と、本文中に表示されるようになる。もちろん、配列の部分は何を入れても良い。「hoge」でも「USA」でも「ワールド」でもよい。

また

[mycus_hellow_any]

このようにパラメーターを使用しなかった場合は、「Hellow World!」と表示される。

これは、最初にデフォルトのパラメーターである「World」を指定しているからだ。

先ほどの配列を使えば、このようなショートコードを作ることもできる。

ショートコードの例

// ショートコード：[mycus_self_introduction]
function mycus_self_introduction_func( $atts ) {
  $myself = shortcode_atts( array(
    'name' => '小野寺耕之助',
    'food' => 'カレーライス',
    'like' => 'タンバリンを叩く',
    'hobby' => '家庭菜園',
    'motto' => '七転び八起き'
  ), $atts );
  $greeting = '<p>初めまして。私の名前は' . $myself['name'] . 'です。</p><p>好きな食べ物は' . $myself['food'] . 'で、好きなことは' . $myself['like'] . 'ことです。</p><p>趣味は' . $myself['hobby'] . 'で、座右の銘は' . $myself['motto'] . 'です。</p><p>これからよろしくお願いします。</p>';
  return $greeting;
}
add_shortcode('mycus_self_introduction', 'mycus_self_introduction_func');

これは、見ての通り「自己紹介」のショートコードである。

また、こちらは段落の背景色と文字色と文章を変えることが出来るショートコードだ。

ショートコードの例

// ショートコード：[mycus_colored_paragraph]
function mycus_colored_paragraph_func( $atts ) {
  $color = shortcode_atts( array(
    'background-color' => 'black',
    'color' => 'white',
    'letter' => '色付きの段落です。パラメーターを使ってみよう！'
  ), $atts );
  $colored = '<p style=" background-color:' . $color['background-color'] . '; color:' . $color['color'] . ';">' . $color['letter'] . '</p>';
  return $colored;
}
add_shortcode('mycus_colored_paragraph', 'mycus_colored_paragraph_func');

インラインでCSSを設定しているため、配列の引数を弄るだけで自由に色を変更することが出来る。

いろいろ作ってコツをつかんでみよう。

囲み型ショートコード

次は、囲み型と呼ばれているものだ。これは、このように作ることが出来る。

ショートコードの例

// ショートコード：[mycus_hellow_pack][/mycus_hellow_pack]
function mycus_hellow_pack_func( $atts, $content = null ) {
  $hellow_pack = '<p class="mycus-hellow-pack">' . $content . '</p>';
  return $hellow_pack;
}
add_shortcode('mycus_hellow_pack', 'mycus_hellow_pack_func');

そして、このショートコードは以下のように使用することにより

[mycus_hellow_pack]Hellow World![/mycus_hellow_pack]

このようなクラス名が付与された段落を作ることが出来る。

<p class="mycus-hellow-pack">Hellow World!</p>

F12キーを押してデベロッパーツールを開き、エレメントを確認してみよう。

このような要素が確認できるはずだ。

おおざっぱな説明だが、これが囲み型ショートコードの作り方と使い方だ。

引数の活用

こちらのショートコードも、先ほどの完結型のように配列を組み込むことが出来る。

例えば、先ほど紹介した色付きの段落を出力するショートコード。あのままでは使いにくいはずだ。

なので、下のように変更して、もっと使いやすくすることができる。

ショートコードの例

// ショートコード：[mycus_colored_paragraph_pack][/mycus_colored_paragraph_pack]
function mycus_colored_paragraph_pack_func( $atts, $content = null ) {
  $color = shortcode_atts( array(
    'background-color' => 'black',
    'color' => 'white'
  ), $atts );
  $colored = '<p style=" background-color:' . $color['background-color'] . '; color:' . $color['color'] . ';">' . $content . '</p>';
  return $colored;
}
add_shortcode('mycus_colored_paragraph_pack', 'mycus_colored_paragraph_pack_func');

こうすることで、例えば背景を青くしたいときは

[mycus_colored_paragraph_pack background-color=blue]背景が青くなります。[/mycus_colored_paragraph_pack]

とできるし、逆に文字の色を「#eee」、背景の色を「#f1f1f1」にしたいときは

[mycus_colored_paragraph_pack background-color=#f1f1f1 color=#eee]ウェブカラー表記でも大丈夫！[/mycus_colored_paragraph_pack]

こう書けばよい。

このように、内部に好きな文章を入れたいときは、囲み型のショートコードのほうが自由が利く。

さて、先ほどはインラインのCSSを用意し配列を組み込んで段落の色を制御した。しかし、これでは投稿記事ページの容量が嵩んでしまうし、もっといろいろ指定したいときはmarginやpaddingやその他いろいろなプロパティを前もってショートコードに組み込まなくてはならなくなる。

そこで、このようにしてみよう。

ショートコードの例

// ショートコード：[mycus_packed_paragraph][/mycus_packed_paragraph]
function mycus_packed_paragraph_func( $atts, $content = null ) {
  $type = shortcode_atts( array(
    'class' => 'default'
  ), $atts );
  $colored = '<p class="mycus-packed-paragraph ' . $type['class'] . '">' . $content . '</p>';
  return $colored;
}
add_shortcode('mycus_packed_paragraph', 'mycus_packed_paragraph_func');

見ての通り、このショートコードの配列はpタグのクラス名に設定されている。

なので、デフォルトのときは

[mycus_packed_paragraph]デフォルトですよー。[/mycus_packed_paragraph]

とし、子テーマのスタイルシートを開いて

/*CSSコード*/
p.mycus-packed-paragraph.default {
    background-color: #fff;
    color: #333;
}

とすればよいし、背景を黒くしてpaddingの余裕を取った段落を作りたければ

[mycus_packed_paragraph class=type-black]モノクロって、カッコいい。[/mycus_packed_paragraph]

/*CSSコード*/
p.mycus-packed-paragraph.type-black {
    padding: 10px;
    background-color: #333;
    color: #fff;
}

としたらよい。

このように、引数の名前を変えるだけで簡単にクラス名を変更することができ、それに応じてスタイルシートをカスタマイズすることができる。

他にも、このような使い方もある。

ショートコードの例

// ショートコード：[mycus_sns_link][/mycus_sns_link]
function mycus_sns_link_func( $atts, $content = null ) {
  $sns = shortcode_atts( array(
    'account' => ''
  ), $atts );
  $service = '<span class="mycus-sns-link"><a target="_blank" href="' . $sns['account'] . '">' . $content . '</a></span>';
  return $service;
}
add_shortcode('mycus_sns_link', 'mycus_sns_link_func');

上のショートコードは、オリジナルのSNSリンク要素を出力する。

デフォルトでは引数が空になっているので意味のないリンクを生成するだけだが、引数「account=」に自分の各種SNSアカウントのリンクを入れると、閲覧者を外部リンクで誘導することができる。

このように、囲み型ショートコードは手打ちのHTMLのように扱うことができる。

今回使った関数など

それでは、後回しにしていた関数の解説をしていきたい。

add_shortcode

これが、「新しいショートコードを登録する」関数である。この関数を使わないと、作ったショートコード関数を呼び出して出力することができない。つまり、これがないと始まらない。

add_shortcode( string $tag, callback $callback );

関数の内訳を簡単に説明すると、「$tag」の部分がショートコード名、「$callback」の部分がショートコード関数の呼び出しである。

勘違いしている人もいるかもしれないが、add_shortcodeは「ショートコード関数」ではない。

「自分で作った関数をショートコードとしてWordPressに登録する」関数である。

shortcode_atts

この関数をひとことで説明するのは難しいが、ここは単純に「引数を設定することができる」関数だと覚えておいたらよい。

もう少し詳しく説明すると、デフォルトの引数を設定した配列を作成する。引数を使わなかった場合は、デフォルトの引数をもった配列が出力される。しかし、ユーザーが引数を入力した場合は、そちらが新たな引数となって配列が出力される。

shortcode_atts( array $pairs, array $atts, string $shortcode = ” );

内訳を説明すると、「$pair」がデフォルトの引数で、「$atts」がユーザーの引数である。「$shortcode」の部分はショートコード名を入れるところだが、今回作った一連のショートコードではとくに指定してはいない。

この関数は、ショートコード関数に組み込んだ形で入力されることが多い。そして、あえてショートコード関数とは分けて作る必要も無い。

なので、ピンと来ないかもしれないが、今回の「ショートコードの例」のように書けば、デフォルトの引数の設定もユーザー引数の設置も既に済んでいることになる。

ショートコード関数のパラメーターとは

自作したショートコード関数では、3種類のパラメーターを使うことができる。

これらは「ハンドラー関数」であり、ショートコードハンドラーとも呼ばれる。

$atts

これは、ショートコードに引数を設定するもの。

使う機会はいちばん多いだろう。

$content

こちらは、囲み型ショートコードで使用される。

これを使うことで、自由に本文を出力することができる。

$tag

上の例で書いたショートコードでは使わなかったが、これは「ショートコード名」を設定するものである。

このパラメーターは、ひとつのショートコード関数で、ひとつ以上のショートコードを登録するときに使用される。

詳しくは後ろのほうで説明したい。

ショートコード関数内での引数の設置について

引数を作ったら、次は目的の場所にその引数を置かなければならない。

このときは、以下のように書く必要がある。

' . $xxxx['yyyy'] . '

これは、まず文字列として出力するために「’（シングルクォート）」で全体を囲う。

次に、変数をそのまま入れることは出来ないので、「.（ピリオド）」で変数「$xxxx[‘yyyy’]」を囲う。このピリオドは「連結演算子」である。

そして、引数の文字列の部分は変数ではないので、シングルクォートで囲うだけでよい。

このように表記しないと、正しく表示されないどころかエラーを吐いてWebサイトが真っ白になってしまうので注意したい。

もうちょっと発展的なこと

機会があったら必要になってくることも書いておく。

PHPファイル内でのショートコードの実行

もしかすると、本文やウィジェットだけではなく、PHPの関数の中でショートコードを使う機会も出てくるかもしれない。

そんなときは、「do_shortcode」関数を使えばよい。

<?php echo do_shortcode( '[this_is_shortcode]' ); ?>

こうすることで、PHPファイル内でもショートコードを実行できる。

もちろん、ショートコード関数を実行するショートコード関数を作ることもできる。

// ショートコード：[mycus_shortcode_run_shortcode]
function mycus_shortcode_run_shortcode_func() {
  $run = do_shortcode( '[mycus_shortcode]' );
  return $run;
}
add_shortcode( 'mycus_shortcode_run_shortcode', 'mycus_shortcode_run_shortcode_func' );

このように、do_shortcodeを使うことで、作ったショートコードを活用することができる。

ひとつの関数にひとつ以上のショートコードを登録するには

さて、先ほどパラメーターのところで説明した「$tag」、これはどのようにして使えばよいのだろうか？

とくに特別な事情でもない限り、「ひとつの関数」につき「ひとつのショートコード」を登録するものだろう。しかし、「ひとつの関数」に「ふたつのショートコード」を登録したいときはどうしたらよいのだろうか？

こんなときに、「$tag」パラメーターが活躍してくれる。

下のコードを見てほしい。

ショートコードの例

// ショートコードその1：[mycus_shortcode_one]、ショートコードその2：[mycus_shortcode_two]
function mycus_one_or_two_shortcode_func( $atts, $content = null, $tag = '' ) {
  if( $tag == 'mycus_shortcode_one' ) {
    $one = '<p>これは「ショートコードその1」です。</p>';
    return $one;
  } else if( $tag == 'mycus_shortcode_two' ) {
    $two = '<p>これは「ショートコードその2」です。</p>';
    return $two;
  } else {
    $default = '<p>これは「ショートコードその1」でも「ショートコードその2」でもありません。</p>';
    return $default;
  }
}
add_shortcode( 'mycus_shortcode_one', 'mycus_one_or_two_shortcode_func' );
add_shortcode( 'mycus_shortcode_two', 'mycus_one_or_two_shortcode_func' );

同じ関数にショートコードがふたつ登録されていることが確認できるだろうか？

そして、使いたいときはこうしよう。

「ショートコードその1」を出力したいときは

[mycus_shortcode_one]

と入力し、「ショートコードその2」を出力したいときは

[mycus_shortcode_two]

と入力したらよい。

また、何らかの理由でショートコードがどちらも使えない・どちらも使いたくないときは、デフォルトに設定した文章を呼び出すことができる。

このように、「$tag」を使うことで、ひとつの関数に複数のショートコードを登録することができる。

ショートコードを作るときに注意したいこと

通常、「echo」を使うことは出来ない

ショートコード関数内に「echo」を使用すると、不具合が起きる。

具体的に説明すると、例えば以下のような「間違ったショートコード関数」を作って登録したとする。

間違ったショートコードの例

// 間違ったショートコード：[mycus_wrong_hellow]
function mycus_wrong_hellow_func() {
  echo '<p>Hellow World!</p>';
}
add_shortcode( 'mycus_wrong_hellow', 'mycus_wrong_hellow_func' );

これを使用すると、記事編集画面の上のほうに、以下のようなダイアログが表示される。

このように、「更新に失敗しました。返答が正しい JSON レスポンスではありません。」と表示され、WEBサイトのどこかで不具合が起きてしまう（ショートコード自体は表示されることはされるが、意図しない場所に出力されることが多い）。

なので、ショートコード関数を組み立てるときは、必ず「return」を使うようにしよう。

それでもechoを使いたいときは

しかし、どうしても「echo」を使いたい！「echo」を含んだショートコードを作りたい！といったときもあるかもしれない。

そんなときは、このようにしたらよい。

ショートコードの例

// echoが存在するショートコード：[mycus_echo_hellow]
function mycus_echo_hellow_func() {
  ob_start();
  echo '<p>Hellow World!</p>';
  $message = ob_get_contents();
  ob_end_clean();
  return $message;
}
add_shortcode( 'mycus_echo_hellow', 'mycus_echo_hellow_func' );

このショートコードは、「ob_start」関数と「ob_end_clean」関数でバッファリングの領域を作り出し、変数を用いた「ob_get_contents」を使ってバッファの中身を取り出し、「return」で返す。といった動作を行うことで、本文中に「Hellow World!」と書かれた段落を出力する仕組みとなっている。

そして、この方法を使うと、引数を設定した場合でも問題なく動作する。

ショートコードの例

// echoがあるショートコード：[mycus_echo_hellow_any]
function mycus_echo_hellow_any_func( $atts) {
  ob_start();
  $word = shortcode_atts( array(
    'world' => 'World'
  ), $atts );
  echo '<p>Hellow ' . $word['world'] . '!</p>';
  $message = ob_get_contents();
  ob_end_clean();
  return $message;
}
add_shortcode( 'mycus_echo_hellow_any', 'mycus_echo_hellow_any_func' );

引数の部分はバッファの外に出してもよい。

// echoがあるショートコード：[mycus_echo_hellow_any]
function mycus_echo_hellow_any_func( $atts) {
  $word = shortcode_atts( array(
    'world' => 'World'
  ), $atts );
  ob_start();
  echo '<p>Hellow ' . $word['world'] . '!</p>';
  $message = ob_get_contents();
  ob_end_clean();
  return $message;
}
add_shortcode( 'mycus_echo_hellow_any', 'mycus_echo_hellow_any_func' );

このコードでは、引数「world」を使うことにより、Hellowの単語を変えることができる。

これらふたつの例はとても単純なコードなので実感が湧きにくいかもしれないが、より大きく複雑なショートコードを作りたいときは「echo」があると便利になる。

そのときは、バッファリングを忘れず行うようにしよう。