WordPress テーマにウィジェット機能（サイドバー）を追加

WordPress テーマにウィジェット機能を追加

WordPress の作成したテーマでウィジェット機能を追加して利用する方法について。register_sidebar や dynamic_sidebar の使い方など。

更新日：2022年03月13日

作成日：2019年04月03日

ウィジェット

WordPress には予め色々なウィジェットが用意されていて、それらを管理画面で編集して表示できるようなっています。WordPress の既存のウィジェット以外にも、プラグインを追加したりウィジェットを自作して追加することもできます。

但し、デフォルトではこの機能は有効になっていないので、作成したテーマでウィジェットを利用するには register_sidebar() を使って機能を有効化します。

register_sidebar() は「サイドバー」を定義する関数です。

「サイドバー」は元々はテーマの左右のサイドバーで使うことを想定して作られたテーマ機能のためこのような名前になっていると思われますが、「サイドバー」は「ウィジェットを表示するエリア（領域）」のことで、名前とは関係なくフッターでもどこでもテーマで利用することができます。

テーマでウィジェットを有効化していないと以下のように管理画面の「外観」をクリックしてもその下に「ウィジェット」の項目がまだありません。

register_sidebar() を使って機能を有効化すると管理画面の「外観」に「ウィジェット」の項目が追加されます（「メニュー」の項目も追加されます）。

日本語版 Codex：「ウィジェット」「テーマのウィジェット対応」

概要

作成するテーマでウィジェットを利用するためのおおまかな流れは以下のようになります。

実際の運用では 2.と 3.は入れ替わるかも知れませんし、ウィジェットはいつでも変更可能です。

ウィジェットの機能を有効化（ウィジェット機能の有効化）
functions.php で register_sidebar() を使ってサイドバー（ウィジェットを表示するエリア）を定義して登録
```
//functions.php
function my_theme_widgets_init() {
  register_sidebar( array(
    'name' => 'Main Sidebar',
    'id' => 'main-sidebar',
  ) );
}
add_action( 'widgets_init', 'my_theme_widgets_init' );
```
管理画面でウィジェットを追加（ウィジェットの編集）
「外観」→「ウィジェット」で、1. で定義したサイドバーに使用するウィジェットを追加
ウィジェットを表示させる位置を指定（ウィジェットを表示）
テンプレートファイルで 1. で定義したサイドバーを表示する場所に dynamic_sidebar() を記述してウィジェットを出力
```

<?php if ( is_active_sidebar('main-sidebar') ) : ?>
  <ul class="menu">
    <?php dynamic_sidebar('main-sidebar'); ?>
  </ul>
<?php endif; ?>
```

ウィジェット機能の有効化

ウィジェットの機能を有効化及びサイドバーを定義するために、register_sidebar() を使ってサイドバー（ウィジェットを表示するエリア）を定義して登録します。

register_sidebar() のパラメータはオプションですが、パラメータの id や name を指定することでそのサイドバーを出力の際に識別（特定）することができ、その他のオプションで出力するサイドバーのマークアップ（HTML）をカスタマイズすることができます。

また、register_sidebar() は内部で add_theme_support( 'widgets' ) を実行していてウィジェット機能を有効化します。

register_sidebar

この関数はウィジェット機能を利用するサイドバーを１つ定義します。

アクションフックに登録しなくても動作しますが、通常は widgets_init アクションフックのタイミングで実行するようにします。

register_sidebar( $args );

パラメータ

$args（文字列/配列）：（オプション）以下のパラメータを連想配列（キーと値のペア）で指定。

name
id
description
class
before_widget
after_widget
before_title
after_title

初期値：空の配列 array()

戻り値: （文字列）グローバル変数 $wp_registered_sidebars に追加されたサイドバーの ID

register_sidebar() は functions.php に記述します。

以下は id のみを指定してサイドバーを登録する例です。

id はサイドバーを出力する際に、どのサイドバーかを特定するために dynamic_sidebar() のパラメータで指定します。

また、id を指定しない場合、デバッグモードでは E_USER_NOTICE（注意メッセージ）が出力されます。

※ register_sidebar() は widgets_init アクションフックのタイミングで実行するようにします。

//functions.php
function my_theme_widgets_init() {
  register_sidebar( array(
    'id' => 'sidebar-1'
  ) );
}
add_action( 'widgets_init', 'my_theme_widgets_init' );

サイドバーは複数登録することができます。以下はサイドバーを２つ登録する例です。

それぞれのサイドバーには名前（name）と ID（id）を指定しています。

function my_theme_widgets_init() {
  register_sidebar( array(
    'name' => 'Main Sidebar',
    'id' => 'main-sidebar',
  ) );
  
  register_sidebar( array(
    'name' => 'Footer Widgets',
    'id' => 'footer-widgets',
  ) );
}
add_action( 'widgets_init', 'my_theme_widgets_init' );

名前（name）を指定しない場合は、システムが自動的に「サイドバー1」などの名前を付けます。

上記の例では指定していませんが、名前の他に説明（description）も指定しておくとウィジェット編集の際の管理がしやすくなります。

サイドバーの HTML

サイドバーは dynamic_sidebar() を使ってを出力しますが、出力される HTML をカスタマイズするには register_sidebar() のパラメータで指定します。

例えば、前述のサイドバーの登録のように名前と ID だけを指定した場合、dynamic_sidebar() を使ってサイドバーを出力すると以下のような HTML が出力されます。

以下は検索、カテゴリー、固定ページの３つのウィジェットが登録されている例です。

<!-- 検索のウィジェット -->
<li id="search-3" class="widget widget_search"> 
  <form role="search" method="get" class="search-form" action="">
    <input type="search" ... name="s" aria-label="このサイトで検索">
    <input type="submit" class="search-submit" value="検索">
  </form>
</li>
<!-- カテゴリーのウィジェット -->
<li id="categories-11" class="widget widget_categories"> 
  <h2 class="widgettitle">カテゴリー</h2>
  <ul>
    <li class="cat-item cat-item-1"><a href="..." >...</a></li>
    <li class="cat-item cat-item-3"><a href="..." >...</a></li>
    <li class="cat-item cat-item-2"><a href="..." >...</a></li>
  </ul>
</li>
<!-- 固定ページのウィジェット -->
<li id="pages-4" class="widget widget_pages">
  <h2 class="widgettitle">固定ページ</h2>
  <ul>
    <li class="page_item page-item-150"><a href="...">...</a></li>
    <li class="page_item page-item-152"><a href="...">...</a></li>
    <li class="page_item page-item-148"><a href="...">...</a></li>
  </ul>
</li>

上記のようにデフォルトではそれぞれのウィジェットを li 要素で囲んで出力されるので、デフォルトのサイドバーを出力する場合は dynamic_sidebar() を ul 要素で囲んで記述します。

<!-- テンプレートファイル -->
<ul id="sidebar">
  <?php dynamic_sidebar( 'main-sidebar' ); ?>
</ul>;

上記のように記述することで、以下のように ul/li 要素で正しくマークアップされるようになります。

<ul id="sidebar"><!-- テンプレートファイルに記述した ul 開始タグ -->
  <!-- 検索のウィジェット -->
  <li id="search-3" class="widget widget_search">
    <form role="search" method="get" class="search-form" action="">
      <input type="search" ... name="s" aria-label="このサイトで検索">
      <input type="submit" class="search-submit" value="検索">
    </form>
  </li>
  <!-- カテゴリーのウィジェット -->
  <li id="categories-11" class="widget widget_categories">
    <h2 class="widgettitle">カテゴリー</h2>
    <ul>
      <li class="cat-item cat-item-1"><a href="..." >...</a></li>
      <li class="cat-item cat-item-3"><a href="..." >...</a></li>
      <li class="cat-item cat-item-2"><a href="..." >...</a></li>
    </ul>
  </li>
  <!-- 固定ページのウィジェット -->
  <li id="pages-4" class="widget widget_pages">
    <h2 class="widgettitle">固定ページ</h2>
    <ul>
      <li class="page_item page-item-150"><a href="...">...</a></li>
      <li class="page_item page-item-152"><a href="...">...</a></li>
      <li class="page_item page-item-148"><a href="...">...</a></li>
    </ul>
  </li>
</ul><!-- テンプレートファイルに記述した ul 閉じタグ -->

マークアップを変更

パラメータを利用すれば、デフォルトで出力されるマークアップを変更することができます。

ウィジェットを囲む要素やタイトルに使用する要素を変更することができます。

以下は、register_sidebar() でパラメータを指定して、ウィジェットを囲む要素を <section> 要素に変更し、ウィジェットのタイトルを囲む要素を <h3> 要素に変更して独自のクラスを指定する例です。

id 属性は単なる文字列で指定してしまうと、ウィジェットが複数ある場合に重複してしまうので注意が必要です。以下ではシステムが出力する ID（ウィジェット名+番号）を利用していますが、この値はウィジェットを再作成すると番号部分が変わってしまいます。

function my_theme_widgets_init() {
  register_sidebar( array(
    'name' => 'Main Sidebar',
    'id' => 'main-sidebar',
    'before_widget' => '<section id="%1$s" class="my_sidebar">',
    'after_widget' => '</section>',
    'before_title' => '<h3 class="sidebar_title">',
    'after_title'  => '</h3>',
  ) );
}
add_action( 'widgets_init', 'my_theme_widgets_init' );

上記の場合、ウィジェットを囲む要素を <section> 要素に変更しているので、サイドバーを出力する際にテンプレートに <ul> を記述する必要はありません。

<?php dynamic_sidebar('main-sidebar'); ?><!-- サイドバーを出力 -->

以下は上記を記述して出力されるサイドバーの HTML の例です。

<section id="search-3" class="my_sidebar">
  <form role="search" method="get" class="search-form" action="">
    <input type="search" ... name="s" aria-label="このサイトで検索">
    <input type="submit" class="search-submit" value="検索">
  </form>
</section>
<section id="categories-11" class="my_sidebar">
  <h3 class="sidebar_title">カテゴリー</h3>
  <ul>
    <li class="cat-item cat-item-1"><a href="..." >...</a></li>
    <li class="cat-item cat-item-3"><a href="..." >...</a></li>
    <li class="cat-item cat-item-2"><a href="..." >...</a></li>
  </ul>
</section>
<section id="pages-4" class="my_sidebar">
  <h3 class="sidebar_title">固定ページ</h3>
  <ul>
    <li class="page_item page-item-150"><a href="...">...</a></li>
    <li class="page_item page-item-152"><a href="...">...</a></li>
    <li class="page_item page-item-148"><a href="...">...</a></li>
  </ul>
</section>

パラメータ（詳細）

初期値（名前や出力される要素など）はパラメータに値を指定することで変更することができます。

register_sidebar() のパラメータ
キー	値の型	初期値	内容
name	文字列	sprintf( __( 'Sidebar %d' ), $i )　 'Sidebar' を翻訳した文字列と ID の数字（$i）例：サイドバー1	サイドバーの名前
id	文字列	"sidebar-$i"; （$i は登録したサイドバーの連番で最初は1）	サイドバーの ID
description	文字列	''	ウィジェット管理画面に表示されるサイドバーの説明テキスト
class	文字列	''	管理画面のサイドバーに割り当てられる CSS クラス
before_widget	文字列	'<li id="%1$s" class="widget %2$s">' sprintf で変数を置換（%1$s はウィジェットの名前+番号、%2$s は widget_ウィジェットの名前）	ウィジェットの直前に出力する HTML テキスト
after_widget	文字列	"</li>\n"	ウィジェットの直後に出力する HTML テキスト
before_title	文字列	'<h2 class="widgettitle">'	タイトルの直前に出力する HTML テキスト
after_title	文字列	"</h2>\n"	タイトルの直後に出力する HTML テキスト

name

サイドバーの名前を指定します。ウィジェット管理画面に表示され、dynamic_sidebar() のパラメータの値として指定することができます（name または id を指定）。

指定しない場合（デフォルト）は、「サイドバー1」などになります（数値はシステムが割り振る連番）。

サイドバーの ID を指定します。オプションですが、バージョン 4.2 以降デバッグモードで id を指定しない場合は以下のような E_USER_NOTICE（注意メッセージ）が出力さてしまうので、半角英数字の任意の文字列を指定します。

Notice: register_sidebar が誤って呼び出されました。「サイドバー 1」サイドバーの引数の配列で id が設定されませんでした。既定では「sidebar-1」です。id に「sidebar-1」を設定することでこの情報を消して、既存のサイドバーのコンテンツを保つことができます。

また、id は name 同様 dynamic_sidebar() のパラメータの値として指定することができます。

description

ウィジェット管理画面に表示されるサイドバーの説明テキストです。

class

管理画面のサイドバーに割り当てられる CSS クラスです。管理画面のソースコードのみに出力され、テンプレートファイルには出力されません。

管理画面のサイドバーを囲む div 要素のクラスに sidebar-xxxx（xxxx は指定した文字列）のようなクラスが追加されます。

before_widget

ウィジェットの直前に出力する HTML テキストを指定します。デフォルトでは li 要素が出力されるので、デフォルトの場合、dynamic_sidebar() を使ってウィジェットエリアを出力する際に ul 要素で囲む必要があります。

以下はサイドバーにカテゴリーと固定ページのウィジェットを追加した場合にデフォルトで出力される HTML の例です。

<li id="categories-5" class="widget widget_categories"><!-- before_widget  -->
  <!-- カテゴリーウィジェット  -->
  <h2 class="widgettitle">カテゴリー</h2>
  <ul>
    <li class="cat-item cat-item-1"><a href="http://.../news/" >News</a></li>
    <li class="cat-item cat-item-3"><a href="http://../column/" >Column</a></li>
    <li class="cat-item cat-item-2"><a href="http://.../music/" >Music</a></li>
  </ul>
</li><!-- after_widget  -->
<li id="pages-3" class="widget widget_pages"><!-- before_widget  -->
  <!-- 固定ページウィジェット  -->
  <h2 class="widgettitle">固定ページ</h2>
  <ul>
    <li class="page_item page-item-150"><a href="http://.../about/">About</a></li>
    <li class="page_item page-item-152"><a href="http://.../top/">Top</a></li>
    <li class="page_item page-item-148"><a href="http://.../contact/">Contact</a></li>
  </ul>
</li><!-- after_widget  -->

上記の例で before_widget に該当するのは、カテゴリーと固定ページのウィジェットを囲む以下のような li 要素です。id 属性には「ウィジェットの名前+番号」、class 属性には「widget widget_ウィジェットの名前」が付与されています。

<li id="categories-5" class="widget widget_categories">
<li id="pages-3" class="widget widget_pages">
<!-- ソースでは以下のようになっています  -->
<li id="%1$s" class="widget %2$s">

id 属性と class 属性の値には以下のような変数が指定されていて、sprintf で値に変換されます。

id 属性：%1$s （ウィジェットの名前+番号）
class 属性：widget %2$s （widget widget_ウィジェットの名前）

番号はシステムが自動的に付与するそれぞれのウィジェットごとに異なる番号です。例えば、同じウィジェットでも一度削除後に再度追加すると番号（値）は増加します。

after_widget

ウィジェットの直後に出力する HTML テキストで、デフォルトでは </li> です。

before_title

タイトルの直前に出力する HTML テキストで、デフォルトでは以下のような h2 要素です。

<h2 class="widgettitle">

after_title

タイトルの直後に出力する HTML テキストで、デフォルトでは </h2> です。

ウィジェットの編集

register_sidebar() を使ってサイドバーを登録（定義）すると、管理画面の「外観」→「ウィジェット」に登録されたサイドバーが表示されます。

以下は名前を「Main Sidebar」、説明を「メインのウィジェット」としてサイドバーを登録する例です。

function my_theme_widgets_init() {
  register_sidebar( array(
    'name' => 'Main Sidebar',
    'id' => 'main-sidebar',
    'description' => 'メインのウィジェット'
  ) );
}
add_action( 'widgets_init', 'my_theme_widgets_init' );

上記のようにサイドバーを登録した場合、管理画面の「外観」→「ウィジェット」には以下のようなサイドバーが表示されます。

登録したばかりのサイドバーはウィジェットが何も入っていない空の状態です。

サイドバーを複数登録すれば、複数のサイドバーが表示されます。

ウィジェットの追加・削除

ウィジェットの追加は追加したいウィジェットをサイドバーにドラッグ＆ドロップします。

サイドバーに追加されたウィジェットはタイトルやその内容を設定することができます。設定が完了したら「保存」や「完了」をクリックするとその内容が保存されます。「削除」をクリックするとそのウィジェットが削除されます。

それぞれのウィジェットごとに設定できる内容は異なります。

ウィジェットが表示される際の HTML は register_sidebar() を使ってサイドバーを登録（定義）する際にパラメータで指定することができます。

例えばウィジェットのタイトルはデフォルトでは h2 要素でマークアップされ、widgettitle と言うクラスが付与されます。

個々のウィジェット自体はデフォルトでは li 要素でマークアップされ、例えばカテゴリーのウィジェットの場合は categories-n（n は数値）と言う id と widget widget_categories と言うクラスが付与されます。

これらのクラスなどを利用してタイトルやウィジェットのスタイルを設定することができます。

１つのサイドバーに複数のウィジェットを追加することができます。

この画面で表示されている順序でウィジェットはページに表示されます。各ウィジェットはドラッグすることで順序を入れ替えられます。また左側にドラッグすると削除することができます。

各ウィジェットの設定を変更するには、ウィジェットのタイトルの右側のアイコンをクリックします。

ウィジェットを表示

ウィジェットを表示するには、テンプレートファイルで表示したい場所に dynamic_sidebar() を記述してサイドバーを出力します。

その際に、is_active_sidebar() を使用すれば、そのサイドバーが現在有効になっているかを確認することができます。

is_active_sidebar

特定のサイドバーが有効化されているかどうかを調べる関数です。

is_active_sidebar( $index )

パラメータ: $index（string|int）：（必須）register_sidebar() でサイドバーを登録する際に指定したサイドバーの ID または名前。

戻り値: （bool）サイドバーが有効な場合（サイドバーにウィジェットが登録されている場合）は true、それ以外は false。

dynamic_sidebar

サイドバー（ウィジェット表示エリア）を出力する関数です。

dynamic_sidebar( $index )

パラメータ: $index（int|string）：（オプション）register_sidebar() でサイドバーを登録する際に指定したサイドバーの ID または名前。パラメータを指定しない場合は、デフォルトのサイドバーまたは ID が sidebar-1 のサイドバーを表示します。サイドバーが複数ある場合は、必ず ID または名前を指定します。
初期値：1（内部で sidebar-1 に変換される）

戻り値: （bool）サイドバーが呼び出され問題なくウィジェットが表示された場合は true、そうでない場合は false。

以下の例では、サイドバーは以下のように register_sidebar() の ID に 'left-sidebar' を指定して登録してあります。

//functions.php
function my_theme_widgets_init() {
  register_sidebar( array(
    'id' => 'left-sidebar',
  ) );
}
add_action( 'widgets_init', 'my_theme_widgets_init' );

サイドバーの出力は、サイドバーが有効化されているかどうかを確認する関数 is_active_sidebar() を使って以下のように記述します。

それぞれの関数のパラメータにはサイドバーの ID または名前を指定します。

サイドバーはデフォルトではそれぞれのウィジェットを li 要素で囲んで出力されるので、dynamic_sidebar() を ul 要素で囲んで記述します。

このようにすれば、そのサイドバーが有効な場合のみ <ul class="menu"> を含むウィジェットエリア（サイドバー）が出力されます。

<!-- テンプレートファイル -->
<?php if ( is_active_sidebar( 'left-sidebar' ) ) : ?>
  <ul id="sidebar">
    <?php dynamic_sidebar( 'left-sidebar' ); ?>
  </ul>
<?php endif; ?>

サイドバーが有効でウィジェットが登録されている場合は、以下のような HTML が出力されます。

<ul id="sidebar"><!-- テンプレートファイルに記述した ul 開始タグ -->
  <!-- カテゴリーのウィジェット -->
  <li id="categories-11" class="widget widget_categories">
    <h2 class="widgettitle">カテゴリー</h2>
    <ul>
      <li class="cat-item cat-item-1"><a href="..." >...</a></li>
      <li class="cat-item cat-item-3"><a href="..." >...</a></li>
      <li class="cat-item cat-item-2"><a href="..." >...</a></li>
    </ul>
  </li>
  <!-- 固定ページのウィジェット -->
  <li id="pages-4" class="widget widget_pages">
    <h2 class="widgettitle">固定ページ</h2>
    <ul>
      <li class="page_item page-item-150"><a href="...">...</a></li>
      <li class="page_item page-item-152"><a href="...">...</a></li>
      <li class="page_item page-item-148"><a href="...">...</a></li>
    </ul>
  </li>
</ul><!-- テンプレートファイルに記述した ul 閉じタグ -->

register_sidebar() のパラメータでウィジェットを囲む要素を <section> や <div> 要素などに変更している場合は、テンプレートに <ul> を記述する必要はないので以下のように記述することができます。

<?php if ( is_active_sidebar('left-sidebar') ) : ?>
  <?php dynamic_sidebar('left-sidebar'); ?>
<?php endif; ?>

必要に応じてウィジェットエリアを囲むマークアップを追加します。

以下の場合、ID が 'main-sidebar' のサイドバーが有効な場合のみ id="primary-sidebar" の div 要素と登録されているウィジェットが出力されます。

<?php if ( is_active_sidebar( 'left-sidebar' ) ) : ?>
  <div id="primary-sidebar" class="primary-sidebar widget-area" role="complementary">
    <?php dynamic_sidebar( 'left-sidebar' ); ?>
  </div><!-- #primary-sidebar -->
<?php endif; ?>

Web Design Leaves