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

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

クラスリファレンス/Walker

提供: WordPress Codex 日本語版
< クラスリファレンス
2016年2月19日 (金) 16:13時点におけるMayuko (トーク | 投稿記録)による版

移動先: 案内検索

このページ「クラスリファレンス/Walker」は未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

このページ「クラスリファレンス/Walker」はまだ書きかけで、情報が不足しています。続きを書いて WordPress を手助けしましょう.


概要

Walker クラスはHTMLをレンダリングする目的でツリー状のデータ構造を走査する手段として開発者に提供するためにWordPress 2.1 にて実装されました。

ツリー構造

Web 開発の面では、ツリー構造は階層的な配列またはオブジェクトです - ルート要素と子のサブツリーが視覚的に現れるような。

WordPress オブジェクトの「木のような」方法で構築されたデータの例には、ナビゲーションメニュー、ページカテゴリーとパンくずリストがあります。

Walker の役割

Walker抽象クラスです。 使いやすくするために、クラスは拡張可能かつ必要などんな抽象的なメソッドでも定義されなければなりません。( 詳しくは下の「抽象的メソッド」を見てください。 )

クラスそのものはシンプルにツリー内の各ノードを「歩き」、(例: オブジェクトまたは連想配列)そしてそれぞれのノードで抽象的な関数を実行します。ノードのうちの1つにおいて1つのアクションをするために、開発者はこれらの抽象的メソッドをカスタマイズした子クラスのなかに定義しなければなりません。

Walker クラスにはたくさんの使いみちがありますが、開発者に最も一般的に使われているのはカスタムメニューの HTML アウトプットです。(通常 WordPress 管理画面の外観→メニューで設定するもの)

Abstraction Note: The Walker class was created prior to PHP5 and so does not make use of PHP5's explicit abstraction keywords or features. In this case, the class and its methods are implicitly abstract (PHP4 compatible) and not explicitly abstract (PHP5 compatible). Developers are not required to implement any methods of the class, and may use or override only those methods that are needed. If you chose not to extend a specific abstract method, that method will simply do nothing.

Methods & Properties

Properties

Note that the properties of the Walker class are intended to be set by the extending class and probably should not vary over the lifetime of an instance.

$db_fields 
必須. Because Walker can take any type of tree object, you need to specify what object properties the Walker class should treat as parent id and item id (usually these are the names of database fields, hence the property name). This property must be an associative array with two keys: 'parent' and 'id'. The value of each key should be the names of the object properties that hold the parent id and item id, respectively.
$tree_type 
Optional. The Walker class itself makes no use of this value, although it may be useful to developers. Internally, WordPress's own extended Walker classes will set this to values like 'category' or 'page'.
$max_pages 
Optional. The maximum number of pages walked by the paged walker.

抽象メソッド

These methods are abstract and should be explicitly defined in the child class, as needed. Also note that $output is passed by reference, so any changes made to the variable within the following methods are automatically handled (no return, echo, or print needed).

start_lvl( &$output, $depth = 0, $args = array() ) 
"Start Level". The start_lvl() method is run when the walker reaches the start of a new "branch" in the tree structure. Generally, this method is used to add the opening tag of a container HTML element (such as <ol>, <ul>, or <div>) to $output.
end_lvl( &$output, $depth = 0, $args = array() ) 
"End Level". This method is run when the walker reaches the end of a "branch" in the tree structure. Generally, this method is used to add the closing tag of a container HTML element (such as </ol>, </ul>, or </div>) to $output.
start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 ) 
"Start Element". Generally, this method is used to add the opening HTML tag for a single tree item (such as <li>, <span>, or <a>) to $output.
end_el( &$output, $object, $depth = 0, $args = array() ) 
"End Element". Generally, this method is used to add any closing HTML tag for a single tree item (such as </li>, </span>, or </a>) to $output. Note that elements are not ended until after all of their children have been added.

Public Methods

These methods are defined by the parent class and may be called from within child methods as needed.

walk($elements, $max_depth) 
This method can be used to initialize the Walker class. It takes an array of elements ordered so that children occur below their parents. The $max_depth parameter is an integer that specifies how deep into the tree structure the walker should render. By default, the $max_depth argument uses 0, which will render every item in every branch, with no depth limit. You can also specify -1 to render all objects as a "flattened" single-dimensional list. Any other number will limit the depth that Walker will render in any branch. Any additional arguments passed to this method will be passed unchanged to the other methods.
paged_walk( $elements, $max_depth, $page_num, $per_page ) 
This method can be used to initialize the Walker class. This function works like walk() but allows for pagination. $page_num specifies the current page to render while $per_page specifies the number of items to show per page. Any additional arguments passed to this method will be passed unchanged to the other methods.
get_number_of_root_elements( $elements ) 
Counts the number of top-level items (no children or descendants) in the provided array, and returns that count.
unset_children( $e, &$children_elements ) 
Removes all the children for a specified top-level element.

Private Methods

display_element( $element, &$children_elements, $max_depth, $depth=0, $args, &$output ) 
This method should be considered private and should not be called directly. Use walk() instead.

使い方

There are two general use-cases for the Walker class.

Usage as a Callback

Some WordPress APIs and functions ( such as wp_nav_menu() ) allow developers to specify a custom Walker class as a callback. This is the most common usage of the Walker class by developers.

In this scenario, the class is automatically passed a tree of elements. When creating a custom walker for this scenario, you will generally only need to define the abstract methods needed to create the kind of structure you want. Everything else is handled automatically for you.

Custom Usage

It is also possible to call your custom Walker classes manually. This is particularly useful for plugin developers.

In this scenario, you can initiate the walker by calling either the walk() or paged_walk() method of your child class, with the appropriate parameters.

用例

Property Usage Example

This example would shows how you might set up the Walker's $db_fields property for handling a tree of page objects. Since we know the parent and id properties for all post objects (pages included), we just need to match those up using the Walker's $db_fields property. Like so...

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

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

General Menu Example

This example shows one of the simplest (and most common) implementations of the walker class. In this case, the Walker will be used to generate a custom menu in combination with wp_nav_menu(). The first block shows the example Walker child class, the second block demonstrates how this class is utilized.

<?php
class Walker_Quickstart_Menu extends Walker {

    // Tell Walker where to inherit it's parent and id values
    var $db_fields = array(
        'parent' => 'menu_item_parent', 
        'id'     => 'db_id' 
    );

    /**
     * At the start of each element, output a <li> and <a> tag structure.
     * 
     * Note: Menu objects include url and title properties, so we will use those.
     */
    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
        );
    }

}

Tip: In this case, you could choose to extend Walker_Nav_Menu /en instead of Walker, and then you wouldn't need to define $db_fields manually.

In order to utilize this custom walker class, you would call wp_nav_menu() (likely from within a theme file) and pass it a new instance of the custom Walker child class.

<ul>
    <?php
    wp_nav_menu(array(
        'menu'    => 2, //menu id
        'walker'  => new Walker_Custom_Menu() //use our custom walker
    ));
    ?>
</ul>

Using Walker Manually

This example will cover how to initialize a custom Walker manually. In this example, our goal is to render the same menu as in the previous example ( General Menu Example ). We will use the same Walker class as above, but without using the callback feature of wp_nav_menu().

<?php
// 1. Fetch the menu (we'll assume it has an id of 2)...
$menu = wp_get_nav_menu_object(2);

// 2. Create an empty $menu_items array
$menu_items = array();

// 3. Get menu objects (this is our tree structure)
if ( $menu && ! is_wp_error($menu) && !isset($menu_items) ) {
    $menu_items = wp_get_nav_menu_items( $menu );
}

// 4. Create a new instance of our walker...
$walk = new Walker_Custom_Menu();

// 5. Walk the tree and render the returned output as a one-dimensional array
print_r( $walk->walk( $menu_items, -1 ) );

ソースファイル

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

External Resources

関連資料

Classes


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

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