新型Kindle 4/10発売

[WordPress]ショートコードを自作する方法。PHPデビューにも最適です

ウィジェットやカスタムフィールドは紹介していたのに、ショートコードの書き方を記事化していなかったので今更ご紹介。

ちなみにショートコードとは

コード
[shortcode param]

といった感じで、記事中でPHPで書かれたプログラムを呼び出す機能のことです。
テーマやプラグインなどで用意されているので、使ったことがある方も多いと思います。

PHPを勉強し始めると、真っ先にやりたくなるのが、このショートコード作成。
ショートコードには複数の記述法があるので、それらをご紹介していきます。

ショートコードの基本

ショートコードは functions.php に記述していきます。
子テーマを導入し、子テーマの functions.php に追記していく形になりますね。

ショートコードをWordPressに登録する

add_shortcode( ショートコード名, 呼び出す関数名 );

自作したショートコードを add_shortcode関数を使って、WordPress側に登録します。
ショートコード名に設定した文字列が記事編集画面で記述する名前になります。
呼び出す関数名に記述した関数が、実際にコールバックで呼び出される関数です。

参考 関数リファレンス/add shortcodeCodex

記述例を見たほうが理解しやすいかと思いますので、次に進みましょう。

引数なしのショートコード

引数が何もいらないパターンです。
下記のショートコードは [red_hello] と記述することで、赤字で

こんにちは

と表示するだけのショートコードです。

コード
function shortcode_RedHelloPrint(){
	$msg = '<p style="color:red;">' . 'こんにちは' . '</p>';
	return $msg;
}
add_shortcode('red_hello', 'shortcode_RedHelloPrint');

上記で作成したショートコードの呼び出し

[red_hello]

こんにちは

returnした戻り値が、実際にHTMLとして出力されることになります。
HTMLが複数行に渡る場合は、ピリオドなどで文字列連結してあげればOKです。

引数ありのショートコード

引数$attsにショートコードで指定した属性情報を受け取ります。
こちらのショートコードは、引数に「文字色」「スタイル」「太さ」を受け取って、「こんにちは」を出力します。

コード
function shortcode_ColorHelloPrint($atts){
	$atts = shortcode_atts(array(
				'color' => 'red',	//colorの初期値
				'font-style' => 'normal',
				'font-weight' => 'normal'
			), 
			$atts,
			'color_hello'//ショートコード名。省略可能だが含めるのが推奨
		);
	
	$msg = "<p style=\"color:{$atts['color']}; font-style:{$atts['font-style']}; font-weight:{$atts['font-weight']};\">こんにちは</p>";
	return $msg;
}
add_shortcode('color_hello', 'shortcode_ColorHelloPrint');

上記で作成したショートコードの呼び出し

[color_hello]

こんにちは

[color_hello color='blue']

こんにちは

[color_hello color='green' font-style='italic']

こんにちは

[color_hello color='orange' font-weight=900]

こんにちは

上記例は 'font-style' のように変数名で使えない文字、ハイフン(-)が含まれた文字をキーにしていたため、$atts['font-style']で連想配列から値を取得していますが、extractを使用してキー名を変数可して取得する方法もよく見られます。

コード
function shortcode_ColorHelloPrint2($atts){
	$atts = shortcode_atts(array(
				'color' => 'red',	//colorの初期値
				'style' => 'normal',
				'weight' => 'normal'
			), 
			$atts,
			'color_hello2'//ショートコード名。省略可能だが含めるのが推奨
		);
	extract($atts);	//連想配列のキーから同名の変数を作成し、値も代入する
	
	$msg = "<p style=\"color:{$color}; font-style:{$style}; font-weight:{$weight};\">こんにちは</p>";
	return $msg;
}
add_shortcode('color_hello2', 'shortcode_ColorHelloPrint2');

上記で作成したショートコードの呼び出し

[color_hello2 color='green' style='italic' weight=900]

こんにちは

引数に配列を渡したい

ショートコードの引数に配列は渡せません。

NGな例 [color_hello2 colors=['red', 'blue', 'green']]

配列のように可変長のデータを渡したい場合、1つの文字列としてまとめ、文字列分割して値を取り出すようにします。

コード
[color_hello2 colors='red,blue,green']

ショートコード先の関数内で文字列分割し配列化。
$colors_array = explode(',', $colors);
参考 shortcode_attsCodex 参考 extractPHP.net 参考 explodePHP.net

コンテンツを囲むパターン

[ショートコード名]コンテンツ[/ショートコード名]
コード
//テキストを外側から渡してもらって、赤色で出力
function shortcode_ColorStringPrint($atts, $content = null){
	$msg = "<p style=\"color:red;\">{$content}</p>";
	return $msg;
}
add_shortcode('color_string', 'shortcode_ColorStringPrint');
[color_string]あいうえお[/color_string]

あいうえお

引数ありの場合

コード
//テキストを外側から渡してもらって、赤色で出力(引数あり)
function shortcode_ColorStringPrint2($atts, $content = null){
	$atts = shortcode_atts(array(
				'color' => 'red',	//colorの初期値
				'style' => 'normal',
				'weight' => 'normal'
			), 
			$atts,
			'color_string2'//ショートコード名。省略可能だが含めるのが推奨
		);
	extract($atts);	//連想配列のキーから同名の変数を作成し、値も代入する
	
	$msg = "<p style=\"color:{$color}; font-style:{$style}; font-weight:{$weight};\">{$content}</p>";
	return $msg;
}
add_shortcode('color_string2', 'shortcode_ColorStringPrint2');
[color_string2 color='blue' weight='bold']かきくけこ[/color_string2]

かきくけこ

コンテンツにショートコードが含まれる場合

囲むコンテンツにショートコードが含まれる場合、shortcode_unautopを実行することでコンテンツ内のショートコードが全て実行されます。

コード
[card_box]
[card_item ...]
[card_item ...]
[card_item ...]
[/card_box]
コード
function shortcode_CardBox($atts, $content = null){
	$content = do_shortcode( shortcode_unautop($content) );
	if($content){
		return '<div class="cardbox">' . $content . '</div>';
	}
	return '';
}
add_shortcode('card_box', 'shortcode_CardBox');

無名関数でもOK

ショートコードの使い方は上記3パターンです。
今まで作成例として、通常の関数を作成し、コールバックとして登録していましたが、無名関数でショートコードを作成することもできます。

コード
add_shortcode(
	'red_hello3', 
	function(){
		$msg = '<p style="color:red;">' . 'こんにちは' . '</p>';
		return $msg;
	}
);
[red_hello3]

こんにちは

個人的にはスペルミスの可能性が無くなる無名関数の書き方のほうが好きですね。
無名関数はPHP5.3以降で使用できます。

テンプレートファイルからショートコードを呼び出す

テンプレートファイルからショートコードを呼び出したいシーンもあるかと思います。
特に無名関数を使っている場合は、関数名自体が無いですからね。
ショートコード名から呼び出す必要があります。

do_shortcode($content)

使用例

コード
<?php do_shortcode('[red_hello]'); ?>

これでテンプレートファイルからも呼び出せます。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です