add_shortcode()のcallbackはechoせず表示HTMLをreturnする

add_shortcode()へ登録するcallbackは、表示するHTMLを文字列としてreturnします。callbackの中でechoしても、その値はshortcodeを書いた位置へ差し込まれません。本文を組み立てる途中で出力されるため、表示位置がずれる原因になります。

先に決めるのは、shortcodeが受け取る属性と、返すHTMLです。tagを登録すること、入力を整理すること、出力を安全な文字列にすることを分ければ、短いcallbackでも保守できます。

callbackの戻り値がshortcodeの位置へ入る

WordPress 4.2.2のShortcode APIでは、add_shortcode()がtag名とcallbackを対応付けて保存します。本文内でtagが見つかると、do_shortcode_tag()がcallbackを呼び、その戻り値を元のshortcodeと置き換えます。

処理の関係は次のとおりです。

1. add_shortcode()でtag名とcallbackを登録する
2. 本文内のshortcodeから属性を取り出す
3. callbackへ属性を渡す
4. callbackが返した文字列をshortcodeの位置へ入れる

echoは四番目の戻り値を作りません。HTMLを組み立て、最後に一回だけreturnしてください。

shortcode_atts()で受け付ける属性を限定する

説明用の仮例として、次のshortcodeでお知らせを表示します。

[satolab_notice text="休業日のお知らせ"]

plugin側のcallbackは次のように書けます。

function satolab_notice_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'text' => 'お知らせ',
        ),
        $atts
    );

    return '<p class="notice">' . esc_html( $atts['text'] ) . '</p>';
}

add_shortcode( 'satolab_notice', 'satolab_notice_shortcode' );

shortcode_atts()の第一引数には、受け付ける属性と初期値を置きます。この例で受け付けるのはtextだけです。投稿者がtextを省けば「お知らせ」を使い、定義していない属性は返される配列へ入れません。

属性値をHTMLへ入れる直前には、その出力先に合わせて処理します。例では段落内の文字として表示するため、esc_html()を使っています。URL、HTML属性、許可するHTMLを含む本文では、必要な処理が異なります。すべての値へ同じ関数を機械的に使わず、値を置く場所を先に決めます。

tag名はほかのpluginと衝突しない名前にする

add_shortcode()は、tag名をkeyとしてcallbackを保存します。同じtag名がもう一度登録されると、同じkeyのcallbackが置き換わります。

noticeやboxのような短い一般名は、ほかのpluginやthemeと重なる可能性があります。サイトまたはpluginを識別できる接頭辞を付け、satolab_noticeのように用途まで分かる名前にしてください。

関数名にも同じ考え方を使います。tag名だけ固有にしても、PHPの関数名が重なれば別の問題が起こります。配布元、tag名、callback名を一組で記録します。

shortcodeを消す前に投稿本文を検索する

shortcodeは、投稿本文へtagを保存し、表示時に登録済みcallbackへ置き換える仕組みです。callbackを持つpluginを停止または削除すると、本文に書かれたtagがそのまま表示される場合があります。

pluginを外す前に、使っているtag名で投稿本文を検索してください。置換先を通常のHTMLへするのか、別のshortcodeへするのか、表示自体を削るのかを決めます。pluginの停止作業と、投稿本文の移行作業は別です。

制作を外部へ依頼する場合は、次の情報を受け取ります。

• 登録したtag名
• callbackを置いたplugin file
• 利用できる属性と初期値
• shortcodeを使っている投稿
• pluginを外すときの置換方法

実装を依頼しても、本文に残るtagとpluginの保守責任はサイト所有者に残ります。最初の一手は、一つのcallbackを開き、echoではなく文字列をreturnしているかを確認することです。