【ワードプレス】テーマの作り方⑦：ショートコードを自作する

このページにはプロモーションが含まれています

個人的にワードプレスを使っていて便利だなぁと思うのがショートコードです。ショートコードを使用することで簡単に複雑な表示を行うことができます。

私はこのウェブサイトで SANGO というテーマを使用していますが、このテーマには下の図のように吹き出しを表示したり、

ショートコードの例

サムネ付きの関連ページを表示したりするようなショートコードが用意されており、めちゃめちゃ便利です。

【ワードプレス】テーマの作り方⑥：ウィジェットを自作する

SANGO は素晴らしいテーマだと思います。が、別に SANGO の宣伝がしたいというわけではありません。何が言いたいかというと、「テーマにショートコードが用意されていると、お洒落なウェブサイト制作が簡単に行える」ということです。

つまり、テーマに多彩なショートコードを用意しておくことで、テーマの価値が上がります。

このページでは、このショートコードの作り方について解説します。

一口にショートコードといっても様々な形式のショートコードが存在します。

例えば下記のようにショートコードのタグ名のみを指定するショートコード、

[mybox]

下記のように属性が指定できるショートコード、

[mybox title="タイトル" color="red"]

さらにはコンテンツも指定できるショートコードが存在します。

[mybox title="タイトル" color="red"]ボックスを表示します[/mybox]

このページではこの３種類のショートコードの作成方法について解説します。

Contents

ショートコード作成の基本
属性を指定可能なショートコード作成
コンテンツを指定可能なショートコード作成
- コンテンツ指定可能なショートコードとは
- コンテンツ指定可能なショートコード作成方法
まとめ

ショートコード作成の基本

まずは一番基本的な、タグ名のみを指定するショートコード（属性やコンテンツは無し）の作成方法について解説します。

ショートコードの仕組み

最初なのでショートコードの仕組みを簡単におさらいしておきましょう。

投稿画面でショートコードを記述するだけで、なぜページ表示時に「吹き出しを表示」したり「サムネ付きの関連ページを表示」したりできるのか考えたことあるでしょうか？

この理由は実に単純で、ショートコード記述部分がページとして表示される時に、関数（吹き出しを表示する関数やサムネ付きの関連ページを表示する関数）が実行されるからです。

ではどの関数が実行されるかと言うと、これはショートコード記述時に指定するショートコードタグに関連付けられた関数になります。

この関連付けはテーマ開発者が行えますので、指定されるショートコードタグに応じて実行される関数を自由に操ることができます。

ここまでがショートコードの簡単な仕組みの解説になります。

ショートコード作成の手順

ショートコードの仕組みが理解できれば、ショートコードを作成するために必要な手順も自然と見えてくると思います。

まずショートコード記述時に指定するタグ名が必要になります。

そして、そのタグを指定された時に実行する関数が必要です。

さらに、そのタグと関数との関連付けが必要です。

まとめると、ショートコード作成の手順は下記となります。

ショートコードタグ名の決定
ショートコードタグ指定時に実行する関数を作成
ショートコードタグを作成した関数に関連付けて登録

各手順を解説しながら、実際に「ボックス表示」を行うショートコードタグを作成する例を紹介していきたいと思います。

1. ショートコードタグ名の決定

まずはショートコードタグの名前を決めましょう。そのショートコードの機能が分かりやすいような名前を付けるのが良いと思います（既にショートコードが定義されているテーマを利用している場合は、タグ名が重複しないように気をつける必要はあります）。

ここではボックス表示を行うショートコードを作成するため、タグ名は ‘mybox’ と名付けます。

2. ショートコード表示時に実行する関数を作成

続いてショートコード記述部分をページに表示する時に実行する関数を作成します。

関数の作成先は functions.php になります。作成する関数は下記の形のものになります。

function 関数名(){
	/* 処理 */
	return 戻り値;
}

今回作成するのはタグ名だけを指定する一番基本的な形のショートコードですので、引数は不要です。関数の戻り値として指定した値や文字列が、ページ表示時に HTML として出力されます。

例えばボックス表示を行うのであれば、下記のような関数を作成すれば良いです。

function mybox_shortcode_func(){
	$result = '';
	$result = $result . '<div class="blue-box">';
	$result = $result . '<div class="box-title">ボックス</div>';
	$result = $result . '<p>ボックス表示します</p>';
	$result = $result . '</div>';

	return $result;
}

ボックスらしさを出すために、style.css に下記を追記してスタイル設定を行ってください。

.blue-box {
	margin: 4px;
    background: #ddddff;
}
.blue-box .box-title {
    font-size: 1.4em;
    background: #0000ff;
    text-align: center;
    font-weight: bold;
    color : #ffffff;
}
.blue-box p {
	margin: 0px;
	padding: 10px;
}

3. ショートコードタグを作成した関数に関連付けて登録

最後に行うのがショートコードタグと関数の関連付けです。この関連付けは add_shortcode 関数で実行することができます。

◼️add_shortcode 関数

add_shortcode 関数はショートコードのタグ名と関数を関連付ける関数です。この関数を実行することにより、引数で指定したタグ名が含まれるショートコードをページ表示する際に、引数で指定した関数が呼び出されるようになります。

◼️使い方

add_shortcode 関数の使い方は下記の通りです。

<?php add_shortcode( $tag , $func ); ?>

◼️引数

第一引数には $tag を、第二引数には $func を指定します。

$tag：ショートコードのタグ名（必須）
$funcname：関数名（必須）

◼️戻り値

なし

ボックス表示を行うショートコードを作成するためには 1. でボックス表示を行うショートコードとしてショートコードのタグ名を ‘mybox’ 、2. でボックス表示を行うための関数の名前を ‘mybox_shortcode_func’ としていますので、$tag に ‘mybox’ 、$func に ‘mybox_shortcode_func’ を指定して add_shortcode 関数を実行します。具体的には下記のように記述します。

add_shortcode( 'mybox', 'mybox_shortcode_func' );

この add_shortcode 関数は、ショートコードのタグ名と関連付ける関数の定義の直後の記述しておくとソースコードを読むときに分かりやすいと思います。

ショートコードの動作確認

作成したショートコードの動作確認は、実際に投稿画面からショートコードを記述し、そのページを表示することで行うことができます。

例えば今回は ‘mybox’ をショートコードタグ名としたショートコードを作成しましたので、下記のように投稿画面に記述します。

[mybox]

そしてページ表示を行い、自身の作成した関数がうまく動いていれば（関数で記述した内容が表示されていれば）オーケーです。今回作成したボックス表示のショートコードの場合は、下の図のように表示されるはずです。

属性を指定可能なショートコード作成

ショートコード作成の基本ではタグ名のみを指定できるショートコードの作成方法を解説しました。

しかし、タグ名だけだと表示される内容が毎回同じになってしまうのでイマイチです。

ここからはショートコード表示時に実行される関数に引数を渡し、引数に応じて表示内容を切り替える方法を解説していきます。

まずは引数に「属性」を指定する方法について解説します。

属性を指定可能なショートコードとは

ショートコードには下記のように記述できるものがあります。

[mybox title="ボックスのタイトル" color="red"]

このショートコードにおける title や color を属性と言います。さらにその属性には設定を指定することができます。例えば上記であれば、title 属性の設定は “ボックスのタイトル” 、 color 属性の設定は “red” となります。

この属性の設定に応じて表示を切り替えるショートコードが「属性を指定可能なショートコード」になります。

例えば color 属性を指定可能なボックス表示を行うショートコードについて考えてみましょう。color 属性が指定できれば、color 属性が “red” の場合は赤色をベースとしたボックス表示を行うようにしたり、color 属性が “green” の場合は緑色をベースとしたボックス表示を行うように、といった制御を行うことができます（属性に応じて表示のどの部分を変更するかは関数の作り方次第で決められます）。

このように属性を指定可能なショートコードでは、同じショートコードタグを用いた場合にも属性の設定を変更することでショートコードによって表示される結果を切り替えることが可能になります。

属性を指定可能なショートコード作成方法

それではその属性を指定可能なショートコード作成方法について解説していきます。

手順自体は作成手順はショートコード作成の手順で紹介した手順 1. 〜 3. と全く同じです。

ただし、作成する関数の形が異なります。属性を指定可能なショートコードの場合、作成する関数の形は下記のようになります。

function 関数名($atts){
	/* 処理 */
	return $result;
}

つまり、引数として $atts を取るように関数を作成します。

属性が記述されたショートコードを表示する際には、その属性をキーとする連想配列が関数の引数として上記の $atts に渡されます。

したがって、この $atts の連想配列に格納される設定値に応じて処理を切り替えるような関数を作成すれば、ページ表示時に属性に応じて表示内容を切り替えることができるようになります。

引数に $atts がないと、ユーザーがショートコード記述時に属性を指定しても、その属性の設定を関数が受け取ることができないので注意してください。

ショートコード作成の手順で紹介したボックス表示の例であれば、mybox_shortcode_func を下記のように変更すれば、属性を指定可能なショートコードに発展させることができます。

function mybox_shortcode_func($atts){
	/* color 属性の指定によってクラスを設定 */
	if ( $atts['color'] == 'red' ) {
		$classname = 'red-box';
	} elseif ($atts['color'] == 'green' ) {
		$classname = 'green-box';
	} elseif ($atts['color'] == 'blue' ) {
		$classname = 'blue-box';
	}

	$result = '';
	$result = $result . '<div class="' . $classname . '">';
	$result = $result . '<div class="box-title">' . $arts['title'] . '</div>';
 	$result = $result . '<p>' . '本文' . '</p>';
	$result = $result . '</div>';

	return $result;
}

具体的には、color 属性によりボックスの背景を、title 属性によりボックスのタイトルを指定できるようにしています。

例えば投稿画面でユーザーがショートコードを下記のように記述した場合、

[mybox color="red" title="赤色のボックス表示です"]

ページ表示時に関数が実行される際には $atts には下記のように属性の設定が格納されることになります。

$atts[‘color’]：”red”
$atts[‘title’]：”赤色のボックス表示です”

$atts[‘color’] に応じてボックスのタグのクラスを指定することで、ボックスの背景を指定された色で表示させるようにしています。

また $atts[‘title’] をボックスのタイトル部分に表示することで、指定されたタイトルを表示できるようにしています。

ショートコード作成の手順では、CSS に青色のボックス表示を行うためのスタイル設定しか行っていませんでしたので、下記のように赤色および緑色のボックス表示を行うための設定を style.css に追記します。

.red-box {
    margin: 4px;
    background: #ffdddd;
}
.red-box .box-title {
    font-size: 1.4em;
    background: #ff0000;
    text-align: center;
    font-weight: bold;
    color : #ffffff;
}
.red-box p {
    margin: 0px;
    padding: 10px;
}

.green-box {
    margin: 4px;
    background: #ddffdd;
}
.green-box .box-title {
    font-size: 1.4em;
    background: #00ff00;
    text-align: center;
    font-weight: bold;
    color : #ffffff;
}
.green-box p {
    margin: 0px;
    padding: 10px;
}

例えば color 属性に “red” 、title 属性に “赤色のボックス表示です” を指定すれば表示結果は下のようになります。

また color 属性に “green” 、title 属性に “緑色のボックス表示です” を指定すれば表示結果は下のようになります。

shortcode_atts で属性のデフォルト値を設定

ショートコードには属性にデフォルト設定を持たせ、属性が指定されなかった場合にデフォルト設定を適用して表示するようなものがあります。

このような、属性にデフォルト設定を持たせたショートコードを作成するには shortcode_atts 関数を使用すると便利です。

◼️shortcode_atts 関数

add_shortcode 関数は、ユーザーが設定した属性設定とデフォルト設定を結合し、ユーザー設定していない属性にてデフォルト設定を適用させる関数です。

◼️使い方

shortcode_atts 関数の使い方は下記の通りです。

<?php shortcode_atts( $pairs ,$atts, $shortcode ); ?>

◼️引数

第一引数には $pairs を、第二引数には $atts を、第三引数には $shortcode を指定します。

$pairs：その関数でサポートする全ての属性とその設定を格納した連想配列（必須）
$atts：引数として指定されたユーザー指定した属性とその設定値を格納した連想配列（必須）
$shortcode：指定すると「shortcode_atts_{$shortcode}」フィルターフックが作成される。このフィルターフックにフックした関数は shortcode_atts 関数呼び出し時に $pairs と $atts の結合後に実行され、その関数の中で結合後の属性をフィルター（加工）することができる

◼️戻り値

結合＆フィルター後の属性

フィルターであったり引数の $shortcode についていきなり理解しようとすると難解なため、まずは $shortcode を指定しない場合の shortcode_atts 関数について理解しておけば良いと思います。

この場合、shortcode_atts 関数は単に、ユーザー設定した属性とデフォルトの属性を結合する関数になります。

どのように結合されるかは実例を見るとわかりやすいです。

先程紹介した color と title 属性が指定可能なショートコード mybox は、特に color の属性が指定されないとうまくページ表示が行えません。

デバッグモードをオンにしておくと下のようなエラーも表示されてしまいます。

このように属性が指定されていない場合にも shortcode_atts を利用すれば安全にページ表示が行えるショートコードが作成できるようになります。

shortcode_atts 関数を利用した mybox_shortcode_func は下記のようになります。

function mybox_shortcode_func( $atts ){
	/* デフォルトの設定を格納した配列を作成 */
	$default = array (
		'color' => 'blue',
		'title' => 'デフォルトのタイトル',
	);

	/* ユーザ設定とデフォルト設定を結合 */
	$atts = shortcode_atts( $default, $atts );

	/* color 属性の指定によってクラスを設定 */
	if ( $atts['color'] == 'red' ) {
		$classname = 'red-box';
	} elseif ($atts['color'] == 'green' ) {
		$classname = 'green-box';
	} elseif ($atts['color'] == 'blue' ) {
		$classname = 'blue-box';
	}

	$result = '';
	$result = $result . '<div class="' . $classname . '">';
	$result = $result . '<div class="box-title">' . $atts['title'] . '</div>';
	$result = $result . '<p>' . '本文' . '</p>';
	$result = $result . '</div>';

	return $result;
}

この関数で使用する属性に対するデフォルト設定を格納した配列 $default を最初に作成し、この $default とユーザーが設定した属性 $atts とを引数として shortcode_atts 関数を実行しています。

これにより、$default のキーとなる属性をユーザーが設定しなかった場合、shortcode_atts 関数の戻り値として、その属性にデフォルト設定を格納した配列が返却されます。

例えば下記のようにショートコードを記述した場合、

[mybox title="タイトル"]

color 属性を指定していないため、color 属性にはデフォルト設定 “blue” を格納した配列が戻り値となります。

$atts[‘color’]：”blue”
$atts[‘title’]：”タイトル”

また下記のようにショートコードを記述した場合、

[mybox]

属性を一つも指定していないため、color 属性と title 属性両方にデフォルト設定が格納された配列が戻り値となります。

$atts[‘color’]：”blue”
$atts[‘title’]：”デフォルトのタイトル表示”

こんな感じで shortcode_atts 関数を使用することで、属性を結合し、ショートコード表示時に実行される関数はサポートする属性全てが設定された状態で処理を行うことができます。

コンテンツを指定可能なショートコード作成

ショートコードでは、ここまで紹介したタグ名や属性だけでなく「コンテンツ」を指定することも可能です。ここからはこのコンテンツ指定可能なショートコードの作成方法について解説していきます。

コンテンツ指定可能なショートコードとは

ショートコードでは下記のように、文字列を囲む形で記述する書き方があります（このように文字列を囲む形で記述するショートコードを囲み型ショートコードと言います）。

[mybox]ショートコード[/mybox]

この囲まれた文字列がコンテンツです。

コンテンツと言うと曖昧に聞こえるかもしれませんが、要はショートコードで表示する本文部分と考えて良いです。

例えば吹き出しだと下の点線で囲った部分、

ここまで作成例を紹介してきたボックスだと下の点線で囲った部分に表示される文字列、これがコンテンツです。

ですので、コンテンツ指定可能なショートコードを作成することで、同じショートコードでもコンテンツの指定に応じて表示を変化させることができます。

コンテンツ指定可能なショートコード作成方法

それではそのコンテンツ指定可能なショートコード作成方法について解説していきます。

手順自体は作成手順は属性指定可能なショートコードと同様で、ショートコード作成の手順で紹介した手順 1. 〜 3. と全く同じです。

ただし、引数には下記のように $atts と $content が指定できるように関数を作成します。

function 関数名($atts, $content = null){
	/* 処理 */
	return $result;
}

第二引数の $content の初期値に null を設定しておくことで、ショートコードが囲み型で記述されなくても正常に動作させることができますので、$content の初期値は記述しておいた方が良いです。

コンテンツが記述されたショートコードを表示する際には、そのコンテンツが関数の引数として上記の $content に渡されます。

したがって、この $content を関数の戻り値に含ませるようにすれば、ページ表示時にコンテンツを表示できるようになります（関数の戻り値がページ表示時に HTML 出力される）。

引数に $content がないと、ユーザーがショートコード記述時にコンテンツを指定しても、そのコンテンツを関数が受け取ることができないので注意してください。

ここまで紹介したボックス表示ショートコード用の mybox_shortcode_func を下記のように変更すれば、コンテンツを指定可能なショートコードを作成することができます。

function mybox_shortcode_func( $atts, $content = null ){
	/* デフォルトの設定を格納した配列を作成 */
	$default = array(
		'color' => 'blue',
		'title' => 'デフォルトのタイトル',
	);

	/* ユーザ設定とデフォルト設定を結合 */
	$atts = shortcode_atts( $default, $atts );

	/* color 属性の指定によってクラスを設定 */
	if ( $atts['color'] == 'red' ) {
		$classname = 'red-box';
	} elseif ( $atts['color'] == 'green' ) {
		$classname = 'green-box';
	} elseif ( $atts['color'] == 'blue' ) {
		$classname = 'blue-box';
	}

	$result = '';
	$result = $result . '<div class="' . $classname . '">';
	$result = $result . '<div class="box-title">' . $atts['title'] . '</div>';
	$result = $result . '<p>' . $content . '</p>';
	$result = $result . '</div>';

	return $result;
}

このプログラムではショートコードに指定されたコンテンツが格納される $content をボックスの本文部分に表示するようにしています。

ですので下記のように投稿画面でショートコードを記述すれば、

[mybox title="コンテンツも表示できる"]ボックス表示の本文です[/mybox]

下のようにコンテンツがボックスの本文部分に表示されるようになります。

まとめ

このページではテーマ開発においてショートコードを自作する方法について解説しました。

ショートコードを作成するためには「ショートコードのタグ名の決定」「ショートコード表示時に実行する関数」「そのタグ名と関数との関連付け」が必要になります。

また関数に $atts や $content の引数を用意することで、属性やコンテンツが指定可能なショートコードも作成可能です。これらが指定できると同じショートコードで様々な表示が行えるようになり利便性が上がります。

是非ショートコードを自作して、より使いやすいテーマを作っていきましょう！