From 6dee77ab95c70b1bb94486243faef1061ab2fd6a Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Wed, 26 Feb 2014 22:19:10 +0000 Subject: [PATCH] Improve inline documentation for `WP_Users_List_Table`. Props leewillis77 for the initial patch. Fixes #26564. git-svn-id: https://develop.svn.wordpress.org/trunk@27301 602fd350-edb4-49c9-b593-d223f7449a82 --- .../includes/class-wp-users-list-table.php | 122 ++++++++++++++++-- 1 file changed, 114 insertions(+), 8 deletions(-) diff --git a/src/wp-admin/includes/class-wp-users-list-table.php b/src/wp-admin/includes/class-wp-users-list-table.php index 12a974c048..4074239774 100644 --- a/src/wp-admin/includes/class-wp-users-list-table.php +++ b/src/wp-admin/includes/class-wp-users-list-table.php @@ -2,16 +2,38 @@ /** * Users List Table class. * - * @package WordPress - * @subpackage List_Table * @since 3.1.0 * @access private + * + * @package WordPress + * @subpackage List_Table */ class WP_Users_List_Table extends WP_List_Table { + /** + * Site ID to generate the Users list table for. + * + * @since 3.1.0 + * @access public + * @var int + */ var $site_id; + + /** + * Whether or not the current Users list table is for Multisite. + * + * @since 3.1.0 + * @access public + * @var bool + */ var $is_site_users; + /** + * Constructor. + * + * @since 3.1.0 + * @access public + */ function __construct( $args = array() ) { parent::__construct( array( 'singular' => 'user', @@ -25,6 +47,12 @@ class WP_Users_List_Table extends WP_List_Table { $this->site_id = isset( $_REQUEST['id'] ) ? intval( $_REQUEST['id'] ) : 0; } + /** + * Check the current user's permissions. + * + * @since 3.1.0 + * @access public + */ function ajax_user_can() { if ( $this->is_site_users ) return current_user_can( 'manage_sites' ); @@ -32,6 +60,12 @@ class WP_Users_List_Table extends WP_List_Table { return current_user_can( 'list_users' ); } + /** + * Prepare the users list for display. + * + * @since 3.1.0 + * @access public + */ function prepare_items() { global $role, $usersearch; @@ -75,10 +109,28 @@ class WP_Users_List_Table extends WP_List_Table { ) ); } + /** + * Output 'no users' message. + * + * @since 3.1.0 + * @access public + */ function no_items() { _e( 'No matching users were found.' ); } + /** + * Return an associative array listing all the views that can be used + * with this table. + * + * Provides a list of roles and user count for that role for easy + * filtering of the user table. + * + * @since 3.1.0 + * @access public + * + * @return array An array of HTML links, one for each view. + */ function get_views() { global $wp_roles, $role; @@ -119,6 +171,14 @@ class WP_Users_List_Table extends WP_List_Table { return $role_links; } + /** + * Retrieve an associative array of bulk actions available on this table. + * + * @since 3.1.0 + * @access public + * + * @return array Array of bulk actions. + */ function get_bulk_actions() { $actions = array(); @@ -133,6 +193,15 @@ class WP_Users_List_Table extends WP_List_Table { return $actions; } + /** + * Output the controls to allow user roles to be changed in bulk. + * + * @since 3.1.0 + * @access public + * + * @param string $which Whether this is being invoked above ("top") + * or below the table ("bottom"). + */ function extra_tablenav( $which ) { if ( 'top' != $which ) return; @@ -152,6 +221,17 @@ class WP_Users_List_Table extends WP_List_Table { echo ''; } + /** + * Capture the bulk action required, and return it. + * + * Overridden from the base class implementation to capture + * the role change drop-down. + * + * @since 3.1.0 + * @access public + * + * @return string The bulk action required. + */ function current_action() { if ( isset($_REQUEST['changeit']) && !empty($_REQUEST['new_role']) ) return 'promote'; @@ -159,6 +239,15 @@ class WP_Users_List_Table extends WP_List_Table { return parent::current_action(); } + /** + * Get a list of columns for the list table. + * + * @since 3.1.0 + * @access public + * + * @return array Array in which the key is the ID of the column, + * and the value is the description. + */ function get_columns() { $c = array( 'cb' => '', @@ -175,6 +264,14 @@ class WP_Users_List_Table extends WP_List_Table { return $c; } + /** + * Get a list of sortable columns for the list table. + * + * @since 3.1.0 + * @access public + * + * @return array Array of sortable columns. + */ function get_sortable_columns() { $c = array( 'username' => 'login', @@ -188,6 +285,12 @@ class WP_Users_List_Table extends WP_List_Table { return $c; } + /** + * Generate the list table rows. + * + * @since 3.1.0 + * @access public + */ function display_rows() { // Query the post counts for this page if ( ! $this->is_site_users ) @@ -216,13 +319,16 @@ class WP_Users_List_Table extends WP_List_Table { /** * Generate HTML for a single row on the users.php admin panel. * - * @since 2.1.0 + * @since 3.1.0 + * @access public * - * @param object $user_object - * @param string $style Optional. Attributes added to the TR element. Must be sanitized. - * @param string $role Key for the $wp_roles array. - * @param int $numposts Optional. Post count to display for this user. Defaults to zero, as in, a new user has made zero posts. - * @return string + * @param object $user_object The current user object. + * @param string $style Optional. Style attributes added to the element. + * Must be sanitized. Default empty. + * @param string $role Optional. Key for the $wp_roles array. Default empty. + * @param int $numposts Optional. Post count to display for this user. Defaults + * to zero, as in, a new user has made zero posts. + * @return string Output for a single row. */ function single_row( $user_object, $style = '', $role = '', $numposts = 0 ) { global $wp_roles;