enmi-conf.org: comparison wp/wp-admin/includes/class-wp-list-table.php

equal deleted inserted replaced

-:34716fd837a4
+:be944660c56a
 	/**
 	 * The current screen.
 	 *
 	 * @since 3.1.0
-	 * @var object
+	 * @var WP_Screen
 	 */
 	protected $screen;
 	/**
 	 * Cached bulk actions.
 		$views = $this->get_views();
 		/**
 		 * Filters the list of available list table views.
 		 *
 		 * 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
 		 *
 		 * @param string[] $views An array of available list table views.
 		 */
 		echo implode( " |</li>\n", $views ) . "</li>\n";
 		echo '</ul>';
 	}
 	/**
-	 * Gets the list of bulk actions available on this table.
+	 * Retrieves the list of bulk actions available for this table.
 	 *
-	 * The format is an associative array:
+	 * The format is an associative array where each element represents either a top level option value and label, or
-	 * - `'option_name' => 'option_title'`
+	 * an array representing an optgroup and its options.
 	 *
-	 * @since 3.1.0
+	 * 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
 	 */
 	protected function get_bulk_actions() {
 		return array();
 	protected function bulk_actions( $which = '' ) {
 		if ( is_null( $this->_actions ) ) {
 			$this->_actions = $this->get_bulk_actions();
 			/**
-			 * 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
 			$two = '';
 		} else {
 		echo '<label for="bulk-action-selector-' . esc_attr( $which ) . '" class="screen-reader-text">' . __( 'Select bulk action' ) . '</label>';
 		echo '<select name="action' . $two . '" id="bulk-action-selector-' . esc_attr( $which ) . "\">\n";
 		echo '<option value="-1">' . __( 'Bulk actions' ) . "</option>\n";
-		foreach ( $this->_actions as $name => $title ) {
+		foreach ( $this->_actions as $key => $value ) {
-			$class = 'edit' === $name ? ' class="hide-if-no-js"' : '';
+			if ( is_array( $value ) ) {
+				echo "\t" . '<optgroup label="' . esc_attr( $key ) . '">' . "\n";
-			echo "\t" . '<option value="' . $name . '"' . $class . '>' . $title . "</option>\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";
+			}
 		}
 		echo "</select>\n";
 		submit_button( __( 'Apply' ), 'action', '', false, array( 'id' => "doaction$two" ) );
 			return false;
 		}
 		if ( isset( $_REQUEST['action'] ) && -1 != $_REQUEST['action'] ) {
 			return $_REQUEST['action'];
-		}
-		if ( isset( $_REQUEST['action2'] ) && -1 != $_REQUEST['action2'] ) {
-			return $_REQUEST['action2'];
 		}
 		return false;
 	}
 		 */
 		if ( apply_filters( 'disable_months_dropdown', false, $post_type ) ) {
 			return;
 		}
-		$extra_checks = "AND post_status != 'auto-draft'";
+		/**
-		if ( ! isset( $_GET['post_status'] ) || 'trash' !== $_GET['post_status'] ) {
+		 * Filters to short-circuit performing the months dropdown query.
-			$extra_checks .= " AND post_status != 'trash'";
+		 *
-		} elseif ( isset( $_GET['post_status'] ) ) {
+		 * @since 5.7.0
-			$extra_checks = $wpdb->prepare( ' AND post_status = %s', $_GET['post_status'] );
+		 *
-		}
+		 * @param object[]|false $months   'Months' drop-down results. Default false.
+		 * @param string         $post_type The post type.
-		$months = $wpdb->get_results(
+		 */
-			$wpdb->prepare(
+		$months = apply_filters( 'pre_months_dropdown_query', false, $post_type );
-				"
-			SELECT DISTINCT YEAR( post_date ) AS year, MONTH( post_date ) AS month
+		if ( ! is_array( $months ) ) {
-			FROM $wpdb->posts
+			$extra_checks = "AND post_status != 'auto-draft'";
-			WHERE post_type = %s
+			if ( ! isset( $_GET['post_status'] ) || 'trash' !== $_GET['post_status'] ) {
-			$extra_checks
+				$extra_checks .= " AND post_status != 'trash'";
-			ORDER BY post_date DESC
+			} elseif ( isset( $_GET['post_status'] ) ) {
-		",
+				$extra_checks = $wpdb->prepare( ' AND post_status = %s', $_GET['post_status'] );
-				$post_type
+			}
-			)
-		);
+			$months = $wpdb->get_results(
+				$wpdb->prepare(
+					"
+				SELECT DISTINCT YEAR( post_date ) AS year, MONTH( post_date ) AS month
+				FROM $wpdb->posts
+				WHERE post_type = %s
+				$extra_checks
+				ORDER BY post_date DESC
+			",
+					$post_type
+				)
+			);
+		}
 		/**
 		 * Filters the 'Months' drop-down results.
 		 *
 		 * @since 3.7.0
 			return;
 		}
 		$m = isset( $_GET['m'] ) ? (int) $_GET['m'] : 0;
 		?>
-		<label for="filter-by-date" class="screen-reader-text"><?php _e( 'Filter by date' ); ?></label>
+		<label for="filter-by-date" class="screen-reader-text"><?php echo get_post_type_object( $post_type )->labels->filter_by_date; ?></label>
 		<select name="m" id="filter-by-date">
 			<option<?php selected( $m, 0 ); ?> value="0"><?php _e( 'All dates' ); ?></option>
 		<?php
 		foreach ( $months as $arc_row ) {
 			if ( 0 == $arc_row->year ) {
 		$pagination_links_class = 'pagination-links';
 		if ( ! empty( $infinite_scroll ) ) {
 			$pagination_links_class .= ' hide-if-js';
 		}
-		$output .= "\n<span class='$pagination_links_class'>" . join( "\n", $page_links ) . '</span>';
+		$output .= "\n<span class='$pagination_links_class'>" . implode( "\n", $page_links ) . '</span>';
 		if ( $total_pages ) {
 			$page_class = $total_pages < 2 ? ' one-page' : '';
 		} else {
 			$page_class = ' no-pages';
 		$default = $this->get_default_primary_column_name();
 		// If the primary column doesn't exist,
 		// fall back to the first non-checkbox column.
 		if ( ! isset( $columns[ $default ] ) ) {
-			$default = WP_List_Table::get_default_primary_column_name();
+			$default = self::get_default_primary_column_name();
 		}
 		/**
 		 * Filters the name of the primary column for the current list table.
 		 *
 		return $column;
 	}
 	/**
-	 * Gets a list of all, hidden and sortable columns, with filter applied.
+	 * Gets a list of all, hidden, and sortable columns, with filter applied.
 	 *
 	 * @since 3.1.0
 	 *
 	 * @return array
 	 */
 	protected function get_column_info() {
 		// $_column_headers is already set / cached.
 		if ( isset( $this->_column_headers ) && is_array( $this->_column_headers ) ) {
-			// Back-compat for list tables that have been manually setting $_column_headers for horse reasons.
+			/*
-			// In 4.3, we added a fourth argument for primary column.
+			 * Backward compatibility for `$_column_headers` format prior to WordPress 4.3.
+			 *
+			 * In WordPress 4.3 the primary column name was added as a fourth item in the
+			 * column headers property. This ensures the primary column name is included
+			 * in plugins setting the property directly in the three item format.
+			 */
 			$column_headers = array( array(), array(), array(), $this->get_primary_column_name() );
 			foreach ( $this->_column_headers as $key => $value ) {
 				$column_headers[ $key ] = $value;
 			}
 		$sortable_columns = $this->get_sortable_columns();
 		/**
 		 * Filters the list table sortable columns for a specific screen.
 		 *
 		 * 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
 		 *
 		 * @param array $sortable_columns An array of sortable columns.
 		 */
 			$tag   = ( 'cb' === $column_key ) ? 'td' : 'th';
 			$scope = ( 'th' === $tag ) ? 'scope="col"' : '';
 			$id    = $with_id ? "id='$column_key'" : '';
 			if ( ! empty( $class ) ) {
-				$class = "class='" . join( ' ', $class ) . "'";
+				$class = "class='" . implode( ' ', $class ) . "'";
 			}
 			echo "<$tag $scope $id $class>$column_display_name</$tag>";
 		}
 	}
 	/**
 	 * Generates content for a single row of the table.
 	 *
 	 * @since 3.1.0
 	 *
-	 * @param object $item The current item
+	 * @param object|array $item The current item
 	 */
 	public function single_row( $item ) {
 		echo '<tr>';
 		$this->single_row_columns( $item );
 		echo '</tr>';
 	}
 	/**
-	 * @param object $item
+	 * @param object|array $item
 	 * @param string $column_name
 	 */
 	protected function column_default( $item, $column_name ) {}
 	/**
-	 * @param object $item
+	 * @param object|array $item
 	 */
 	protected function column_cb( $item ) {}
 	/**
 	 * Generates the columns for a single row of the table.
 	 *
 	 * @since 3.1.0
 	 *
-	 * @param object $item The current item.
+	 * @param object|array $item The current item.
 	 */
 	protected function single_row_columns( $item ) {
 		list( $columns, $hidden, $sortable, $primary ) = $this->get_column_info();
 		foreach ( $columns as $column_name => $column_display_name ) {
 			if ( in_array( $column_name, $hidden, true ) ) {
 				$classes .= ' hidden';
 			}
 			// Comments column uses HTML in the display name with screen reader text.
-			// Instead of using esc_attr(), we strip tags to get closer to a user-friendly string.
+			// Strip tags to get closer to a user-friendly string.
-			$data = 'data-colname="' . wp_strip_all_tags( $column_display_name ) . '"';
+			$data = 'data-colname="' . esc_attr( wp_strip_all_tags( $column_display_name ) ) . '"';
 			$attributes = "class='$classes' $data";
 			if ( 'cb' === $column_name ) {
 				echo '<th scope="row" class="check-column">';
 	/**
 	 * Generates and display row actions links for the list table.
 	 *
 	 * @since 4.3.0
 	 *
-	 * @param object $item        The item being acted upon.
+	 * @param object|array $item        The item being acted upon.
-	 * @param string $column_name Current column name.
+	 * @param string       $column_name Current column name.
-	 * @param string $primary     Primary column name.
+	 * @param string       $primary     Primary column name.
 	 * @return string The row actions HTML, or an empty string
 	 *                if the current column is not the primary column.
 	 */
 	protected function handle_row_actions( $item, $column_name, $primary ) {
 		return $column_name === $primary ? '<button type="button" class="toggle-row"><span class="screen-reader-text">' . __( 'Show more details' ) . '</span></button>' : '';

changeset 18	be944660c56a
parent 16	a86126ab1dd4
child 19	3d72ae0968f4