Make WordPress Core

Ticket #23406: 23406-walker.diff

File 23406-walker.diff, 9.7 KB (added by DrewAPicture, 11 years ago)

Walker

  • src/wp-includes/class-wp-walker.php

     
    22/**
    33 * A class for displaying various tree-like structures.
    44 *
    5  * Extend the Walker class to use it, see examples at the below. Child classes
     5 * Extend the Walker class to use it, see examples below. Child classes
    66 * do not need to implement all of the abstract methods in the class. The child
    7  * only needs to implement the methods that are needed. Also, the methods are
    8  * not strictly abstract in that the parameter definition needs to be followed.
    9  * The child classes can have additional parameters.
     7 * only needs to implement the methods that are needed.
    108 *
     9 * @since 2.1.0
     10 *
    1111 * @package WordPress
    12  * @since 2.1.0
    1312 * @abstract
    1413 */
    1514class Walker {
     
    4342        /**
    4443         * Starts the list before the elements are added.
    4544         *
    46          * Additional parameters are used in child classes. The args parameter holds
    47          * additional values that may be used with the child class methods. This
    48          * method is called at the start of the output list.
     45         * The $args parameter holds additional values that may be used with the child
     46         * class methods. This method is called at the start of the output list.
    4947         *
    5048         * @since 2.1.0
    5149         * @abstract
    5250         *
    5351         * @param string $output Passed by reference. Used to append additional content.
     52         * @param int    $depth  Depth of the item.
     53         * @param array  $args   An array of additional arguments.
    5454         */
    5555        function start_lvl( &$output, $depth = 0, $args = array() ) {}
    5656
    5757        /**
    5858         * Ends the list of after the elements are added.
    5959         *
    60          * Additional parameters are used in child classes. The args parameter holds
    61          * additional values that may be used with the child class methods. This
    62          * method finishes the list at the end of output of the elements.
     60         * The $args parameter holds additional values that may be used with the child
     61         * class methods. This method finishes the list at the end of output of the elements.
    6362         *
    6463         * @since 2.1.0
    6564         * @abstract
    6665         *
    6766         * @param string $output Passed by reference. Used to append additional content.
     67         * @param int    $depth  Depth of the item.
     68         * @param array  $args   An array of additional arguments.
    6869         */
    69         function end_lvl( &$output, $depth = 0, $args = array() )   {}
     70        function end_lvl( &$output, $depth = 0, $args = array() ) {}
    7071
    7172        /**
    7273         * Start the element output.
    7374         *
    74          * Additional parameters are used in child classes. The args parameter holds
    75          * additional values that may be used with the child class methods. Includes
    76          * the element output also.
     75         * The $args parameter holds additional values that may be used with the child
     76         * class methods. Includes the element output also.
    7777         *
    7878         * @since 2.1.0
    7979         * @abstract
    8080         *
    81          * @param string $output Passed by reference. Used to append additional content.
     81         * @param string $output            Passed by reference. Used to append additional content.
     82         * @param object $object            The data object.
     83         * @param int    $depth             Depth of the item.
     84         * @param array  $args              An array of additional arguments.
     85         * @param int    $current_object_id ID of the current item.
    8286         */
    83         function start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 )  {}
     87        function start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 ) {}
    8488
    8589        /**
    8690         * Ends the element output, if needed.
    8791         *
    88          * Additional parameters are used in child classes. The args parameter holds
    89          * additional values that may be used with the child class methods.
     92         * The $args parameter holds additional values that may be used with the child class methods.
    9093         *
    9194         * @since 2.1.0
    9295         * @abstract
    9396         *
    9497         * @param string $output Passed by reference. Used to append additional content.
     98         * @param object $object The data object.
     99         * @param int    $depth  Depth of the item.
     100         * @param array  $args   An array of additional arguments.
    95101         */
    96         function end_el( &$output, $object, $depth = 0, $args = array() )    {}
     102        function end_el( &$output, $object, $depth = 0, $args = array() ) {}
    97103
    98104        /**
    99105         * Traverse elements to create list from elements.
     
    103109         * depth and no ignore elements under that depth. It is possible to set the
    104110         * max depth to include all depths, see walk() method.
    105111         *
    106          * This method shouldn't be called directly, use the walk() method instead.
     112         * This method should not be called directly, use the walk() method instead.
    107113         *
    108114         * @since 2.5.0
    109115         *
    110          * @param object $element Data object
    111          * @param array $children_elements List of elements to continue traversing.
    112          * @param int $max_depth Max depth to traverse.
    113          * @param int $depth Depth of current element.
    114          * @param array $args
    115          * @param string $output Passed by reference. Used to append additional content.
     116         * @param object $element           Data object.
     117         * @param array  $children_elements List of elements to continue traversing.
     118         * @param int    $max_depth        Max depth to traverse.
     119         * @param int    $depth            Depth of current element.
     120         * @param array  $args              An array of arguments.
     121         * @param string $output            Passed by reference. Used to append additional content.
    116122         * @return null Null on failure with no changes to parameters.
    117123         */
    118124        function display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output ) {
     
    160166        /**
    161167         * Display array of elements hierarchically.
    162168         *
    163          * It is a generic function which does not assume any existing order of
    164          * elements. max_depth = -1 means flatly display every element. max_depth =
    165          * 0 means display all levels. max_depth > 0  specifies the number of
    166          * display levels.
     169         * Does not assume any existing order of elements.
    167170         *
     171         * $max_depth = -1 means flatly display every element.
     172         * $max_depth = 0 means display all levels.
     173         * $max_depth > 0 specifies the number of display levels.
     174         *
    168175         * @since 2.1.0
    169176         *
    170          * @param array $elements
    171          * @param int $max_depth
    172          * @return string
     177         * @param array $elements  An array of elements.
     178         * @param int   $max_depth The maximum hierarchical depth.
     179         * @return string The hierarchical item output.
    173180         */
    174181        function walk( $elements, $max_depth) {
    175182
     
    194201                }
    195202
    196203                /*
    197                  * need to display in hierarchical order
    198                  * separate elements into two buckets: top level and children elements
    199                  * children_elements is two dimensional array, eg.
    200                  * children_elements[10][] contains all sub-elements whose parent is 10.
     204                 * Need to display in hierarchical order.
     205                 * Separate elements into two buckets: top level and children elements.
     206                 * Children_elements is two dimensional array, eg.
     207                 * Children_elements[10][] contains all sub-elements whose parent is 10.
    201208                 */
    202209                $top_level_elements = array();
    203210                $children_elements  = array();
     
    209216                }
    210217
    211218                /*
    212                  * when none of the elements is top level
    213                  * assume the first one must be root of the sub elements
     219                 * When none of the elements is top level.
     220                 * Assume the first one must be root of the sub elements.
    214221                 */
    215222                if ( empty($top_level_elements) ) {
    216223
     
    231238                        $this->display_element( $e, $children_elements, $max_depth, 0, $args, $output );
    232239
    233240                /*
    234                  * if we are displaying all levels, and remaining children_elements is not empty,
    235                  * then we got orphans, which should be displayed regardless
     241                 * If we are displaying all levels, and remaining children_elements is not empty,
     242                 * then we got orphans, which should be displayed regardless.
    236243                 */
    237244                if ( ( $max_depth == 0 ) && count( $children_elements ) > 0 ) {
    238245                        $empty_array = array();
     
    251258         * and number of elements per page, this function first determines all top level root elements
    252259         * belonging to that page, then lists them and all of their children in hierarchical order.
    253260         *
    254          * @package WordPress
    255          * @since 2.7
    256          * @param int $max_depth = 0 means display all levels; $max_depth > 0 specifies the number of display levels.
    257          * @param int $page_num the specific page number, beginning with 1.
    258          * @return XHTML of the specified page of elements
     261         * $max_depth = 0 means display all levels.
     262         * $max_depth > 0 specifies the number of display levels.
     263         *
     264         * @since 2.7.0
     265         *
     266         * @param int $max_depth The maximum hierarchical depth.
     267         * @param int $page_num  The specific page number, beginning with 1.
     268         * @return string XHTML of the specified page of elements
    259269         */
    260270        function paged_walk( $elements, $max_depth, $page_num, $per_page ) {
    261271
     
    309319                }
    310320
    311321                /*
    312                  * separate elements into two buckets: top level and children elements
    313                  * children_elements is two dimensional array, eg.
    314                  * children_elements[10][] contains all sub-elements whose parent is 10.
     322                 * Separate elements into two buckets: top level and children elements.
     323                 * Children_elements is two dimensional array, e.g.
     324                 * $children_elements[10][] contains all sub-elements whose parent is 10.
    315325                 */
    316326                $top_level_elements = array();
    317327                $children_elements  = array();
     
    342352                foreach ( $top_level_elements as $e ) {
    343353                        $count++;
    344354
    345                         //for the last page, need to unset earlier children in order to keep track of orphans
     355                        // For the last page, need to unset earlier children in order to keep track of orphans.
    346356                        if ( $end >= $total_top && $count < $start )
    347357                                        $this->unset_children( $e, $children_elements );
    348358
     
    377387                return $num;
    378388        }
    379389
    380         // unset all the children for a given top level element
     390        // Unset all the children for a given top level element.
    381391        function unset_children( $e, &$children_elements ){
    382392
    383393                if ( !$e || !$children_elements )
     
    394404                        unset( $children_elements[$id] );
    395405
    396406        }
    397 }
     407
     408} // Walker