• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

クラスリファレンス/Walker

提供: WordPress Codex 日本語版
移動先: 案内検索

概要

WordPress 2.1 で実装された Walker クラスを使用すると HTML レンダリング用にツリー状のデータ構造を走査できます。

ツリー構造

Web 開発における「ツリー構造」とは階層的な配列またはオブジェクトを指します。ツリー構造のデータはルート要素および子のサブツリーによって視覚的に表現されます。

WordPress オブジェクトでのツリー構造のデータの例としては、ナビゲーションメニュー、ページカテゴリー、パンくずリストがあります。

Walker の役割

Walker抽象クラスです。使用にあたってはクラスを拡張し、必要なすべての抽象メソッドを定義する必要があります。詳細については以下の「抽象メソッド」を参照してください。

クラスそのものは単純にオブジェクトや連想配列などツリー内の各ノードを「歩き」、それぞれのノードで抽象関数を実行します。どれか1つのノードでアクションを実行するには、カスタマイズする子クラスの中で該当の抽象メソッドを定義する必要があります。 Walker クラスには多くの使用法がありますが、一般に開発者がもっともよく使用する場面はカスタムメニューの HTML 出力です。メニューは通常、管理画面「外観」>「メニュー」画面で定義されます。

抽象に関する注意: Walker クラスは PHP5 よりも に作成されたため、PHP5 の明示的な抽象キーワードや抽象機能を 使用しません。クラスやそのメソッドは PHP4 と互換な 暗黙的 な抽象であり、PHP5 と互換な 明示的 な抽象では ありません。開発者はクラスのすべてのメソッドを実装せず、必要なメソッドのみを使用またはオーバーライドできます。ある抽象メソッドを拡張しなければ、このメソッドは単純に何も実行しません。

メソッドとプロパティ

プロパティ

注意: Waler クラスのプロパティは拡張クラスによって設定されることを想定しています。また多くの場合、インスタンスの生存期間にわたり値を変えるべきではありません。

$db_fields 
必須。Walker は任意の型のツリーオブジェクトを取るため、Walker クラスがどのオブジェクトプロパティを親 ID、項目 ID として処理するかを指定する必要があります。一般に ID はデータベースフィールドの名前、したがってプロパティ名になります。このプロパティは2つのキー「parent」と「id」の連想配列である必要があります。キーの値はそれぞれ「親 ID」、「項目 ID」をもつオブジェクトプロパティの名前です。
$tree_type 
オプション。Walker クラス自身はこの値を使わず、開発者の便宜のため存在します。内部的には WordPress 自身の拡張 Walker クラスでこのプロパティに値「category」や「ページ」を設定します。
$max_pages 
オプション。paged walker により探索される最大ページ数。

抽象メソッド

以下のメソッドは抽象メソッドです。必要に応じて子クラスで明示的に定義する必要があります。また $output は参照渡しの点に注意してください。メソッド内での変数の変更は自動的に処理されます。戻り値、echo、print は必要ありません。

start_lvl( &$output, $depth = 0, $args = array() ) 
"開始レベル"。start_lvl() メソッドは walker がツリー構造内で新しい「ブランチ(枝)」の開始点に達すると実行されます。一般には $outputコンテナー HTML 要素の開始タグ、たとえば <ol><ul><div> を追加する場合に使用されます。
end_lvl( &$output, $depth = 0, $args = array() ) 
"終了レベル"。end_lvl() メソッドは walker がツリー構造内で「ブランチ」の終了点に達すると実行されます。一般には $outputコンテナー HTML 要素の終了タグ、たとえば </ol></ul></div> を追加する場合に使用されます。
start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 ) 
"開始要素"。一般には $output に単一ツリー項目の開始 HTML タグ、たとえば <li><span><a> を追加する場合に使用されます。
end_el( &$output, $object, $depth = 0, $args = array() ) 
"終了要素"。一般には $output に単一ツリー項目の終了 HTML タグ、たとえば </li></span></a> を追加する場合に使用されます。注意: 要素はすべての子が追加されるまで終了されません。

パブリックメソッド

以下のメソッドは親クラスで定義されます。必要に応じて子クラスのメソッドから呼び出すことができます。

walk($elements, $max_depth) 
Walker クラスを初期化します。親の下で発生順に並んだ子の要素の配列を取ります。$max_depth パラメータは walker がレンダリングするツリー構造の深さを指定する整数です。デフォルトでの $max_depth 引数は 0 を使用し、深さの制限なしですべてのブランチのすべての項目をレンダリングします。-1 が指定されると「フラット」な一次元リストとしてすべてのオブジェクトをレンダリングします。その他の値は Walker の各ブランチでのレンダリングする深さを制限します。このメソッドに渡される任意の 追加 引数は、他のメソッドに変更なしで渡されます。
paged_walk( $elements, $max_depth, $page_num, $per_page ) 
Walker クラスを初期化します。この関数は walk() と同様の動きをしますが、ページ機能を含みます。$page_num はレンダリングする現在のページ番号を指定し、$per_page はページごとに表示する項目数を指定します。このメソッドに渡される任意の 追加 引数は、他のメソッドに変更なしで渡されます。
get_number_of_root_elements( $elements ) 
子や子孫を含まないトップレベル項目の数を数え、その数を返します。
unset_children( $e, &$children_elements ) 
指定されたトップレベル要素のすべての子を削除します。

プライベートメソッド

display_element( $element, &$children_elements, $max_depth, $depth=0, $args, &$output ) 
このメソッドは プライベート として扱ってください。直接には呼び出さず、代わりに walk() を使用してください。

使い方

Walkerクラスには2つの一般的な使用方法があります。

コールバックとしての使用

wp_nav_menu() のように WordPress API や関数の中にはコールバックとしてカスタム Walker クラスを指定できるものがあります。これがもっとも一般的な Walker クラスの使用方法です。

このシナリオではクラスに自動的に要素のツリーが渡されます。カスタム walker の作成では一般に、希望の構造等を作成する際に必要な抽象メソッドを定義するだけで済むでしょう。その他のすべては自動的に処理されます。

独自の使用

カスタマイズした Walker クラスを手動で呼び出すこともできます。この方法はプラグイン開発者にとって特に有用でしょう。

このシナリオでは適切なパラメータを指定して子クラスの walk() メソッドまたは paged_walk() メソッドを呼び出して walker を初期化します。

用例

プロパティを利用する例

この例では固定ページオブジェクトのツリーを処理する Walker の $db_fields プロパティを設定する方法を示します。すべての投稿オブジェクト (これには固定ページも含まれます) の親プロパティ、ID プロパティが分かっているため、これを Walker の $db_fields プロパティを使用して組み合わせれば十分です。

<?php
class Walker_Page extends Walker {
    var $db_fields = array (
        'parent' => 'post_parent', 
        'id'     => 'ID'
    );

    // ここで抽象メソッドを定義
}

一般的なメニューの例

この例はもっとも単純で、かつもっとも一般的な Walker クラスの実装です。ここで Walker は wp_nav_menu() と共にカスタムメニューの生成に使用されます。最初のブロックは Walker の子クラスの定義、2番目のブロックはその使用法を示します。

<?php
class Walker_Quickstart_Menu extends Walker {

    // Walker に親と ID 値をどこから継承するかを伝える
    var $db_fields = array(
        'parent' => 'menu_item_parent', 
        'id'     => 'db_id' 
    );

    /**
     * 各要素の始まりで <li> と <a> タグ構造を出力する。
     * 
     * 注意: メニューオブジェクトには URL とタイトルプロパティが含まれるため、
     * これを使用する。
     */
    function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
        $output .= sprintf( "\n<li><a href='%s'%s>%s</a></li>\n",
            $item->url,
            ( $item->object_id === get_the_ID() ) ? ' class="current"' : '',
            $item->title
        );
    }

}

ヒント: このシナリオでは Walker の代わりに Walker_Nav_Menu /en の拡張も選択できました。その場合、手動で $db_fields を定義する必要はありません。

このカスタム walker クラスを利用するには、一般にテーマファイルの中から wp_nav_menu() を呼び出し、カスタム Walker 子クラスの新しいインスタンスを渡します。

<ul>
    <?php
    wp_nav_menu(array(
        'menu'    => 2, // メニュー ID
        'walker'  => new Walker_Quickstart_Menu() // 作成したカスタム walker を使用する
    ));
    ?>
</ul>

手動での Walker の利用

この例ではカスタム Walker の 手動 での初期化方法を示します。ここでの目標は 上の例 と同じメニューのレンダリングです。上と同じ Walker クラスを使用しますが wp_nav_menu() のコールバック機能は使用しません。

<?php
// 1. メニューを取得。ID は 2 と仮定
$menu = wp_get_nav_menu_object(2);

// 2. 空の $menu_items 配列を作成
$menu_items = array();

// 3. メニューオブジェクトを取得。これがツリー構造
if ( $menu && ! is_wp_error($menu) && !isset($menu_items) ) {
    $menu_items = wp_get_nav_menu_items( $menu );
}

// 4. walker の新しいインスタンスを作成
$walk = new Walker_Quickstart_Menu();

// 5. ツリーを「歩き」、戻り値の出力を1次元配列としてレンダリング
print_r( $walk->walk( $menu_items, -1 ) );

ソースファイル

Walker wp-includes/class-wp-walker.phpにあります。

外部リソース

関連資料

クラス


クラスリファレンス関数リファレンスの各インデックスも参照してください。

最新英語版: WordPress Codex » Class Reference/Walker最新版との差分