[wp-trac] [WordPress Trac] #64601: Document WP_List_Table behavior change in WordPress 6.9 - bottom tablenav skipped when empty

[WordPress Trac]

#64601: Document WP_List_Table behavior change in WordPress 6.9 - bottom tablenav
skipped when empty
----------------------------+-----------------------------
 Reporter:  nithi22         |      Owner:  (none)
     Type:  enhancement     |     Status:  new
 Priority:  normal          |  Milestone:  Awaiting Review
Component:  Administration  |    Version:  6.9
 Severity:  normal          |   Keywords:
  Focuses:                  |
----------------------------+-----------------------------
 = Summary =

 WordPress 6.9 introduced a behavior change in
 `WP_List_Table::display_tablenav()` that affects plugins using the
 `manage_posts_extra_tablenav` hook.

 = The Change =

 In WP 6.9, the following code was added to `display_tablenav()`:

 {{{
 if ( 'bottom' === $which && ! $this->has_items() ) {
     return;
 }
 }}}

 This optimization skips rendering the bottom tablenav entirely when there
 are no items in the list table.

 = Impact on Plugins =

 Plugins that hook into `manage_posts_extra_tablenav` with `$which ===
 'bottom'` to display custom empty states or notices will find their code
 no longer executes when the list is empty.

 Example affected code:
 {{{
 add_action( 'manage_posts_extra_tablenav', 'my_empty_state' );

 function my_empty_state( $which ) {
     global $post_type;

     if ( $post_type === 'my_cpt' && $which === 'bottom' ) {
         if ( empty_list_condition() ) {
             // This never fires in WP 6.9 when list is empty
             display_empty_state();
         }
     }
 }
 }}}

 = Request =

 This should be documented in:
 1. **WordPress 6.9 Developer Notes / Field Guide**
 2. **Hook documentation for `manage_posts_extra_tablenav`**
 3. **WP_List_Table class documentation**

 = Suggested Documentation =

 For the `manage_posts_extra_tablenav` hook documentation:

 "Note: As of WordPress 6.9, this action will not fire for `$which ===
 'bottom'` when the list table has no items (`has_items()` returns false).
 If you need to display content when the list is empty, hook for `$which
 === 'top'` instead, or use an alternative hook such as `in_admin_header`
 or `admin_notices`."

 = Workaround for Plugin Developers =

 Change the condition from `$which === 'bottom'` to `$which === 'top'`:

 {{{
 if ( $post_type === 'my_cpt' && $which === 'top' ) {
     // This works in both WP 6.8 and 6.9
 }
 }}}

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64601>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform