Changeset 49190

Timestamp:

10/18/2020 04:20:07 PM (4 years ago)

Author:

johnbillion

Message:

Administration: Allow WP_List_Table::get_bulk_items() to receive a nested array in order to output optgroups.

The allowed format for bulk actions is now an associative array where each element represents either a top level option value and label, or an array representing an optgroup and its options.

For a standard option, the array element key is the field value and the array element value is the field label.

For an optgroup, the array element key is the label and the array element value is an associative array of options as above.

Props goldenapples, mattkeys, valentinbora, davidbaumwald

Fixes #19278

Location:

trunk

Files:

• src/wp-admin/includes/class-wp-list-table.php (modified) (3 diffs)
• src/wp-admin/includes/class-wp-privacy-requests-table.php (modified) (1 diff)
• src/wp-admin/includes/class-wp-users-list-table.php (modified) (1 diff)
• tests/phpunit/tests/admin/includesListTable.php (modified) (1 diff)

trunk/src/wp-admin/includes/class-wp-list-table.php

@@ -420 +420 @@
 
     /**
-     * Gets the list of bulk actions available on this table.
-     *
-     * The format is an associative array:
-     * - `'option_name' => 'option_title'`
-     *
-     * @since 3.1.0
+     * Retrieves the list of bulk actions available for this table.
+     *
+     * The format is an associative array where each element represents either a top level option value and label, or
+     * an array representing an optgroup and its options.
+     *
+     * For a standard option, the array element key is the field value and the array element value is the field label.
+     *
+     * For an optgroup, the array element key is the label and the array element value is an associative array of
+     * options as above.
+     *
+     * Example:
+     *
+     *     [
+     *         'edit'         => 'Edit',
+     *         'delete'       => 'Delete',
+     *         'Change State' => [
+     *             'feature' => 'Featured',
+     *             'sale'    => 'On Sale',
+     *         ]
+     *     ]
+     *
+     * @since 3.1.0
+     * @since 5.6.0 A bulk action can now contain an array of options in order to create an optgroup.
      *
      * @return array
@@ -446 +463 @@
 
             /**
-             * Filters the list table bulk actions drop-down.
+             * Filters the items in the bulk actions menu of the list table.
              *
              * The dynamic portion of the hook name, `$this->screen->id`, refers
-             * to the ID of the current screen, usually a string.
+             * to the ID of the current screen.
              *
              * @since 3.1.0
+             * @since 5.6.0 A bulk action can now contain an array of options in order to create an optgroup.
              *
-             * @param string[] $actions An array of the available bulk actions.
+             * @param array $actions An array of the available bulk actions.
              */
             $this->_actions = apply_filters( "bulk_actions-{$this->screen->id}", $this->_actions ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores
@@ -470 +488 @@
         echo '<option value="-1">' . __( 'Bulk actions' ) . "</option>\n";
 
-        foreach ( $this->_actions as $name => $title ) {
-            $class = 'edit' === $name ? ' class="hide-if-no-js"' : '';
-
-            echo "\t" . '<option value="' . $name . '"' . $class . '>' . $title . "</option>\n";
+        foreach ( $this->_actions as $key => $value ) {
+            if ( is_array( $value ) ) {
+                echo "\t" . '<optgroup label="' . esc_attr( $key ) . '">' . "\n";
+
+                foreach ( $value as $name => $title ) {
+                    $class = ( 'edit' === $name ) ? ' class="hide-if-no-js"' : '';
+
+                    echo "\t\t" . '<option value="' . esc_attr( $name ) . '"' . $class . '>' . $title . "</option>\n";
+                }
+                echo "\t" . "</optgroup>\n";
+            } else {
+                $class = ( 'edit' === $key ) ? ' class="hide-if-no-js"' : '';
+
+                echo "\t" . '<option value="' . esc_attr( $key ) . '"' . $class . '>' . $value . "</option>\n";
+            }
         }
 

trunk/src/wp-admin/includes/class-wp-privacy-requests-table.php

@@ -207 +207 @@
      * @since 4.9.6
      *
-     * @return string[] Array of bulk action labels keyed by their action.
+     * @return array Array of bulk action labels keyed by their action.
      */
     protected function get_bulk_actions() {

trunk/src/wp-admin/includes/class-wp-users-list-table.php

@@ -260 +260 @@
      * @since 3.1.0
      *
-     * @return string[] Array of bulk action labels keyed by their action.
+     * @return array Array of bulk action labels keyed by their action.
      */
     protected function get_bulk_actions() {

trunk/tests/phpunit/tests/admin/includesListTable.php

@@ -354 +354 @@
 
     /**
+     * @ticket 19278
+     */
+    public function test_bulk_action_menu_supports_options_and_optgroups() {
+        $table = _get_list_table( 'WP_Comments_List_Table', array( 'screen' => 'edit-comments' ) );
+
+        add_filter(
+            'bulk_actions-edit-comments',
+            function() {
+                return array(
+                    'delete'       => 'Delete',
+                    'Change State' => array(
+                        'feature' => 'Featured',
+                        'sale'    => 'On Sale',
+                    ),
+                );
+            }
+        );
+
+        ob_start();
+        $table->bulk_actions();
+        $output = ob_get_clean();
+
+        $this->assertContains(
+            <<<'OPTIONS'
+<option value="delete">Delete</option>
+    <optgroup label="Change State">
+        <option value="feature">Featured</option>
+        <option value="sale">On Sale</option>
+    </optgroup>
+OPTIONS
+            ,
+            $output
+        );
+    }
+
+    /**
      * @ticket 45089
      */