Walker::paged_walk( array $elements, int $max_depth, int $page_num, int $per_page, mixed $args ): string

Produces a page of nested elements.

Description

Given an array of hierarchical elements, the maximum depth, a specific page number, and number of elements per page, this function first determines all top level root elements belonging to that page, then lists them and all of their children in hierarchical order.

$max_depth = 0 means display all levels.
$max_depth > 0 specifies the number of display levels.

Parameters

$elementsarrayrequired
An array of elements.
$max_depthintrequired
The maximum hierarchical depth.
$page_numintrequired
The specific page number, beginning with 1.
$per_pageintrequired
Number of elements per page.
$argsmixedoptional
Optional additional arguments.

Return

string XHTML of the specified page of elements.

More Information

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.

Source

public function paged_walk( $elements, $max_depth, $page_num, $per_page, ...$args ) {
	if ( empty( $elements ) || $max_depth < -1 ) {
		return '';
	}

	$output = '';

	$parent_field = $this->db_fields['parent'];

	$count = -1;
	if ( -1 == $max_depth ) {
		$total_top = count( $elements );
	}
	if ( $page_num < 1 || $per_page < 0 ) {
		// No paging.
		$paging = false;
		$start  = 0;
		if ( -1 == $max_depth ) {
			$end = $total_top;
		}
		$this->max_pages = 1;
	} else {
		$paging = true;
		$start  = ( (int) $page_num - 1 ) * (int) $per_page;
		$end    = $start + $per_page;
		if ( -1 == $max_depth ) {
			$this->max_pages = ceil( $total_top / $per_page );
		}
	}

	// Flat display.
	if ( -1 == $max_depth ) {
		if ( ! empty( $args[0]['reverse_top_level'] ) ) {
			$elements = array_reverse( $elements );
			$oldstart = $start;
			$start    = $total_top - $end;
			$end      = $total_top - $oldstart;
		}

		$empty_array = array();
		foreach ( $elements as $e ) {
			++$count;
			if ( $count < $start ) {
				continue;
			}
			if ( $count >= $end ) {
				break;
			}
			$this->display_element( $e, $empty_array, 1, 0, $args, $output );
		}
		return $output;
	}

	/*
	 * Separate elements into two buckets: top level and children elements.
	 * Children_elements is two dimensional array, e.g.
	 * $children_elements[10][] contains all sub-elements whose parent is 10.
	 */
	$top_level_elements = array();
	$children_elements  = array();
	foreach ( $elements as $e ) {
		if ( empty( $e->$parent_field ) ) {
			$top_level_elements[] = $e;
		} else {
			$children_elements[ $e->$parent_field ][] = $e;
		}
	}

	$total_top = count( $top_level_elements );
	if ( $paging ) {
		$this->max_pages = ceil( $total_top / $per_page );
	} else {
		$end = $total_top;
	}

	if ( ! empty( $args[0]['reverse_top_level'] ) ) {
		$top_level_elements = array_reverse( $top_level_elements );
		$oldstart           = $start;
		$start              = $total_top - $end;
		$end                = $total_top - $oldstart;
	}
	if ( ! empty( $args[0]['reverse_children'] ) ) {
		foreach ( $children_elements as $parent => $children ) {
			$children_elements[ $parent ] = array_reverse( $children );
		}
	}

	foreach ( $top_level_elements as $e ) {
		++$count;

		// For the last page, need to unset earlier children in order to keep track of orphans.
		if ( $end >= $total_top && $count < $start ) {
				$this->unset_children( $e, $children_elements );
		}

		if ( $count < $start ) {
			continue;
		}

		if ( $count >= $end ) {
			break;
		}

		$this->display_element( $e, $children_elements, $max_depth, 0, $args, $output );
	}

	if ( $end >= $total_top && count( $children_elements ) > 0 ) {
		$empty_array = array();
		foreach ( $children_elements as $orphans ) {
			foreach ( $orphans as $op ) {
				$this->display_element( $op, $empty_array, 1, 0, $args, $output );
			}
		}
	}

	return $output;
}

Changelog

VersionDescription
5.3.0Formalized the existing ...$args parameter by adding it to the function signature.
2.7.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.