add paging in class walker

[hailin]

Paging is important when there are hundreds or thousands of elements to bedisplayed.
Displaying all of them at once is slow and reduces usability.

wp_list_comments in 2.7 uses walker to achieve hierarchy, and we think it may be a good idea to add paging in walker so that comments can be paged as well.

I’ve investigated the possible options, and found out that paging by absolute number of elements is incredibly hard do right and retrofit into walker class. Current display_element is a robust, elegant functions that handles the task of displaying an element tree (a tree rooted with one top level element) well, it also handles depth well.
If we were to modify it to support paging, it destroys the elegancy, thus may produce unstable code for 2.7.

Let’s step back and think about why we need paging.

We need paging because we don’t want to shovel hundreds or thousands of elements all on one page.
Then we realize that it really doesn’t matter too much if we display 20 elements on one page,
and 21, or 25 on the other, as long as the number is small enough.

Besides, approach used in page_rows has one side effect that users may not like:
the partial tree hierarchy may be continued on a seperate page. In this case,
a few previously displayed comments may be displayed on a new page, and users may
be confused, as he/she is reading it twice.

In light of this philosophy, I have conceived two approaches:

1. Rough paging

First we calculate the total num of elements contained in each element tree,
then we find the rough boundaries, which is used for paging decision.
The drawback is that some element tree may contain large num of elements.

2. page by top level root elements.

First we obtain the number of top level elements, then each page would contain
per_page number of top level elements, plus all of their children.
This is logically the simplest approach. It also does not affect existing logic.

We implemented a similar approach, using paged and threaded plugins,
for a popular blog with hundreds of thousands of daily page views,
and they are happy with it. We also observed that the max nested levels of
comments are about 4. And the max number of elements in a element tree is about 9.
So in that case, per_page is set to 10, in most cases,
the number of comments on a page is about 10, 11, 12,
and the max number of comments on one page is about 25.
Not bad at all, since we have solved the problem of displaying 4000 comments on one page, and users have the added benefit of reading all the comments related to
a top level root comment on one single page.

I can also add a simple function to get the number of top level elements in walker class.

Therefore, I propose we go for approach 2.

[hailin]

patch

[hailin]

Implemented approach number 2.

To use it:
First get the total num of root elements:

$root_num = $walker->get_number_of_root_elements( $elements );

Then, decide on the page_num, per_page, and call paged_walk.

Eg, suppose $root_num = 35, and per_page = 10, so there are 4 pages:

$walker->paged_walk( $elements, $max_depth, 1, 10, other_args_if_any );
$walker->paged_walk( $elements, $max_depth, 2, 10, other_args_if_any );
$walker->paged_walk( $elements, $max_depth, 3, 10, other_args_if_any );
$walker->paged_walk( $elements, $max_depth, 4, 10, other_args_if_any );

[ryan]

(In [8939]) Add paging to Walker class. Props hailin. fixes #7743