基本のショートコードの作成方法と、自己完結型と囲み型の使い方が分かったところで、ショートコード [$tag] とハンドラ関数でパラメータを使用する方法を説明します。
ショートコード [$tag] は、属性と呼ばれるパラメータを受け取ることができます:
[wporg title="WordPress.org"]
Having fun with WordPress.org shortcodes.
[/wporg]
ショートコード・ハンドラ関数は、3つのパラメータを受け取ることができます:
$atts– 配列 –[$tag]属性。$content– 文字列 – ショートコードの内容。上の例では、「Having fun with WordPress.org shortcodes」となります。$tag– 文字列 –[$tag]の名前です (つまりショートコードの名前)。
function wporg_shortcode( $atts = array(), $content = null, $tag = '' ) {}
属性のパース (構文解析)
ユーザーにとって、ショートコードは投稿コンテンツの中にある、角括弧 [] 付きの文字列でしかありません。ユーザーは、どの属性が利用可能で、舞台裏で何が起こっているのか分かりません。
プラグイン開発者にとって、属性の使用に関するポリシーを強制する方法はありません。ユーザーは、属性を1つ含めることも、2つ含めることも、まったく含めないこともできます。
ショートコードの使用方法を制御するには:
- ハンドラ関数用のデフォルトパラメータを宣言しましょう。
array_change_key_case()で属性配列用のキーケースを正規化しましょう。shortcode_atts()を使用して属性を構文解析し、デフォルト値の配列とユーザー$attsを提供しましょう。- 出力を返す前に、出力の安全確保をしましょう。
完全な例
基本的なショートコード構造、自己完結型と囲み型のシナリオ、出力の安全確保、を使用した完全な例です。
ショートコード [wporg] は、タイトルを受け取り、CSS でスタイルを設定できるボックスを表示します。
/**
* The [wporg] shortcode.
*
* Accepts a title and will display a box.
*
* @param array $atts Shortcode attributes. Default empty.
* @param string $content Shortcode content. Default null.
* @param string $tag Shortcode tag (name). Default empty.
* @return string Shortcode output.
*/
function wporg_shortcode( $atts = [], $content = null, $tag = '' ) {
// normalize attribute keys, lowercase
$atts = array_change_key_case( (array) $atts, CASE_LOWER );
// override default attributes with user attributes
$wporg_atts = shortcode_atts(
array(
'title' => 'WordPress.org',
), $atts, $tag
);
// start box
$o = '<div class="wporg-box">';
// title
$o .= '<h2>' . esc_html( $wporg_atts['title'] ) . '</h2>';
// enclosing tags
if ( ! is_null( $content ) ) {
// $content here holds everything in between the opening and the closing tags of your shortcode. eg.g [my-shortcode]content[/my-shortcode].
// Depending on what your shortcode supports, you will parse and append the content to your output in different ways.
// In this example, we just secure output by executing the_content filter hook on $content.
$o .= apply_filters( 'the_content', $content );
}
// end box
$o .= '</div>';
// return output
return $o;
}
/**
* Central location to create all shortcodes.
*/
function wporg_shortcodes_init() {
add_shortcode( 'wporg', 'wporg_shortcode' );
}
add_action( 'init', 'wporg_shortcodes_init' );