属性の解析

ユーザーにとって、ショートコードは投稿コンテンツ内の角括弧を含む単なる文字列です。ユーザーはどの属性が利用可能で、裏で何が起こっているのか全く分かりません。

プラグイン開発者にとって、属性の使用に関するポリシーを強制する方法はありません。ユーザーは1つの属性、2つの属性、または全く属性を含めないこともあります。

ショートコードの使用方法を制御するために:

  • ハンドラ関数のデフォルトパラメータを宣言する
  • array_change_key_case()を使用して属性配列のキーのケースを正規化する
  • デフォルト値の配列とユーザー $atts を提供してshortcode_atts()を使用して属性を解析する
  • 戻す前に出力を保護する

完全な例

基本的なショートコード構造を使用した完全な例で、自己閉じおよび囲みシナリオに対処し、出力を保護します。

タイトルを受け入れ、CSSでスタイルを設定できるボックスを表示する[wporg]ショートコードです。 

  1. /**
  2.  * The [wporg] shortcode.
  3.  *
  4.  * Accepts a title and will display a box.
  5.  *
  6.  * @param array  $atts    Shortcode attributes. Default empty.
  7.  * @param string $content Shortcode content. Default null.
  8.  * @param string $tag     Shortcode tag (name). Default empty.
  9.  * @return string Shortcode output.
  10.  */
  11. function wporg_shortcode( $atts = [], $content = null, $tag = '' ) {
  12.     // normalize attribute keys, lowercase
  13.     $atts = array_change_key_case( (array) $atts, CASE_LOWER );
  15.     // override default attributes with user attributes
  16.     $wporg_atts = shortcode_atts(
  17.         array(
  18.             'title' => 'WordPress.org',
  19.         ), $atts, $tag
  20.     );
  22.     // start box
  23.     $o = '<div class="wporg-box">';
  25.     // title
  26.     $o .= '<h2>' . esc_html( $wporg_atts['title'] ) . '</h2>';
  28.     // enclosing tags
  29.     if ( ! is_null( $content ) ) {
  30.         // $content here holds everything in between the opening and the closing tags of your shortcode. eg.g [my-shortcode]content[/my-shortcode].
  31.    // Depending on what your shortcode supports, you will parse and append the content to your output in different ways.
  32.         // In this example, we just secure output by executing the_content filter hook on $content.
  33.         $o .= apply_filters( 'the_content', $content );
  34.     }
  36.     // end box
  37.     $o .= '</div>';
  39.     // return output
  40.     return $o;
  41. }
  43. /**
  44.  * Central location to create all shortcodes.
  45.  */
  46. function wporg_shortcodes_init() {
  47.     add_shortcode( 'wporg', 'wporg_shortcode' );
  48. }
  50. add_action( 'init', 'wporg_shortcodes_init' );