[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * BuddyPress Member Template loop class.
   4   *
   5   * @package BuddyPress
   6   * @subpackage Members
   7   */
   8  
   9  // Exit if accessed directly.
  10  defined( 'ABSPATH' ) || exit;
  11  
  12  /**
  13   * The main member template loop class.
  14   *
  15   * Responsible for loading a group of members into a loop for display.
  16   *
  17   * @since 1.0.0
  18   */
  19  class BP_Core_Members_Template {
  20  
  21      /**
  22       * The loop iterator.
  23       *
  24       * @since 1.0.0
  25       * @var int
  26       */
  27      public $current_member = -1;
  28  
  29      /**
  30       * The number of members returned by the paged query.
  31       *
  32       * @since 1.0.0
  33       * @var int
  34       */
  35      public $member_count;
  36  
  37      /**
  38       * Array of members located by the query.
  39       *
  40       * @since 1.0.0
  41       * @var array
  42       */
  43      public $members;
  44  
  45      /**
  46       * The member object currently being iterated on.
  47       *
  48       * @since 1.0.0
  49       * @var object
  50       */
  51      public $member;
  52  
  53      /**
  54       * A flag for whether the loop is currently being iterated.
  55       *
  56       * @since 1.0.0
  57       * @var bool
  58       */
  59      public $in_the_loop;
  60  
  61      /**
  62       * The type of member being requested. Used for ordering results.
  63       *
  64       * @since 2.3.0
  65       * @var string
  66       */
  67      public $type;
  68  
  69      /**
  70       * The unique string used for pagination queries.
  71       *
  72       * @since 2.2.0
  73       * @var string
  74       */
  75      public $pag_arg;
  76  
  77      /**
  78       * The page number being requested.
  79       *
  80       * @since 1.0.0
  81       * @var string
  82       */
  83      public $pag_page;
  84  
  85      /**
  86       * The number of items being requested per page.
  87       *
  88       * @since 1.0.0
  89       * @var string
  90       */
  91      public $pag_num;
  92  
  93      /**
  94       * An HTML string containing pagination links.
  95       *
  96       * @since 1.0.0
  97       * @var string
  98       */
  99      public $pag_links;
 100  
 101      /**
 102       * The total number of members matching the query parameters.
 103       *
 104       * @since 1.0.0
 105       * @var int
 106       */
 107      public $total_member_count;
 108  
 109      /**
 110       * Constructor method.
 111       *
 112       * @since 1.5.0
 113       * @since 7.0.0 Added `$xprofile_query` parameter. Added `$user_ids` parameter.
 114       *
 115       * @see BP_User_Query for an in-depth description of parameters.
 116       *
 117       * @param array ...$args {
 118       *     Array of arguments. Supports all arguments of BP_User_Query. Additional
 119       *     arguments, or those with different defaults, are described below.
 120       *
 121       *     @type int    $page_number Page of results. Accepted for legacy reasons. Use 'page' instead.
 122       *     @type int    $max         Max number of results to return.
 123       *     @type string $page_arg    Optional. The string used as a query parameter in pagination links.
 124       * }
 125       */
 126  	public function __construct( ...$args ) {
 127          // Backward compatibility with old method of passing arguments.
 128          if ( ! is_array( $args[0] ) || count( $args ) > 1 ) {
 129              _deprecated_argument( __METHOD__, '7.0.0', sprintf( __( 'Arguments passed to %1$s should be in an associative array. See the inline documentation at %2$s for more details.', 'buddypress' ), __METHOD__, __FILE__ ) );
 130  
 131              $old_args_keys = array(
 132                  0  => 'type',
 133                  1  => 'page_number',
 134                  2  => 'per_page',
 135                  3  => 'max',
 136                  4  => 'user_id',
 137                  5  => 'search_terms',
 138                  6  => 'include',
 139                  7  => 'populate_extras',
 140                  8  => 'exclude',
 141                  9  => 'meta_key',
 142                  10 => 'meta_value',
 143                  11 => 'page_arg',
 144                  12 => 'member_type',
 145                  13 => 'member_type__in',
 146                  14 => 'member_type__not_in'
 147              );
 148  
 149              $args = bp_core_parse_args_array( $old_args_keys, $args );
 150          } else {
 151              $args = reset( $args );
 152          }
 153  
 154          // Support both 'page_number' and 'page' for backward compatibility.
 155          $args['page_number'] = isset( $args['page_number'] ) ? $args['page_number'] : $args['page'];
 156  
 157          $defaults = array(
 158              'type'                => 'active',
 159              'page_number'         => 1,
 160              'per_page'            => 20,
 161              'max'                 => false,
 162              'user_id'             => false,
 163              'search_terms'        => null,
 164              'include'             => false,
 165              'populate_extras'     => true,
 166              'exclude'             => false,
 167              'user_ids'            => false,
 168              'meta_key'            => false,
 169              'meta_value'          => false,
 170              'page_arg'            => 'upage',
 171              'member_type'         => '',
 172              'member_type__in'     => '',
 173              'member_type__not_in' => '',
 174              'xprofile_query'      => false,
 175          );
 176  
 177          $r = bp_parse_args(
 178              $args,
 179              $defaults
 180          );
 181  
 182          $this->pag_arg  = sanitize_key( $r['page_arg'] );
 183          $this->pag_page = bp_sanitize_pagination_arg( $this->pag_arg, $r['page_number'] );
 184          $this->pag_num  = bp_sanitize_pagination_arg( 'num',          $r['per_page']    );
 185          $this->type     = $r['type'];
 186  
 187          if ( ! empty( $_REQUEST['letter'] ) ) {
 188              $this->members = BP_Core_User::get_users_by_letter( $_REQUEST['letter'], $this->pag_num, $this->pag_page, $r['populate_extras'], $r['exclude'] );
 189          } else {
 190              $this->members = bp_core_get_users(
 191                  array(
 192                      'type'                => $this->type,
 193                      'per_page'            => $this->pag_num,
 194                      'page'                => $this->pag_page,
 195                      'user_id'             => $r['user_id'],
 196                      'include'             => $r['include'],
 197                      'search_terms'        => $r['search_terms'],
 198                      'populate_extras'     => $r['populate_extras'],
 199                      'exclude'             => $r['exclude'],
 200                      'user_ids'            => $r['user_ids'],
 201                      'meta_key'            => $r['meta_key'],
 202                      'meta_value'          => $r['meta_value'],
 203                      'member_type'         => $r['member_type'],
 204                      'member_type__in'     => $r['member_type__in'],
 205                      'member_type__not_in' => $r['member_type__not_in'],
 206                      'xprofile_query'      => $r['xprofile_query'],
 207                  )
 208              );
 209          }
 210  
 211          if ( ! $r['max'] || $r['max'] >= (int) $this->members['total'] ) {
 212              $this->total_member_count = (int) $this->members['total'];
 213          } else {
 214              $this->total_member_count = (int) $r['max'];
 215          }
 216  
 217          $this->members = $this->members['users'];
 218  
 219          if ( $r['max'] ) {
 220              if ( $r['max'] >= count( $this->members ) ) {
 221                  $this->member_count = count( $this->members );
 222              } else {
 223                  $this->member_count = (int) $r['max'];
 224              }
 225          } else {
 226              $this->member_count = count( $this->members );
 227          }
 228  
 229          if ( (int) $this->total_member_count && (int) $this->pag_num ) {
 230              $pag_args = array(
 231                  $this->pag_arg => '%#%',
 232              );
 233  
 234              if ( defined( 'DOING_AJAX' ) && true === (bool) DOING_AJAX ) {
 235                  $base = remove_query_arg( 's', wp_get_referer() );
 236              } else {
 237                  $base = '';
 238              }
 239  
 240              /**
 241               * Defaults to an empty array to make sure paginate_links()
 242               * won't add the $page_arg to the links which would break
 243               * pagination in case JavaScript is disabled.
 244               */
 245              $add_args = array();
 246  
 247              if ( ! empty( $r['search_terms'] ) ) {
 248                  $query_arg = bp_core_get_component_search_query_arg( 'members' );
 249                  $add_args[ $query_arg ] = urlencode( $r['search_terms'] );
 250              }
 251  
 252              $this->pag_links = paginate_links( array(
 253                  'base'      => add_query_arg( $pag_args, $base ),
 254                  'format'    => '',
 255                  'total'     => ceil( (int) $this->total_member_count / (int) $this->pag_num ),
 256                  'current'   => (int) $this->pag_page,
 257                  'prev_text' => _x( '&larr;', 'Member pagination previous text', 'buddypress' ),
 258                  'next_text' => _x( '&rarr;', 'Member pagination next text', 'buddypress' ),
 259                  'mid_size'  => 1,
 260                  'add_args'  => $add_args,
 261              ) );
 262          }
 263      }
 264  
 265      /**
 266       * Whether there are members available in the loop.
 267       *
 268       * @since 1.0.0
 269       *
 270       * @see bp_has_members()
 271       *
 272       * @return bool True if there are items in the loop, otherwise false.
 273       */
 274  	public function has_members() {
 275          return ! empty( $this->member_count );
 276      }
 277  
 278      /**
 279       * Set up the next member and iterate index.
 280       *
 281       * @since 1.0.0
 282       *
 283       * @return object The next member to iterate over.
 284       */
 285  	public function next_member() {
 286          $this->current_member++;
 287          $this->member = $this->members[ $this->current_member ];
 288  
 289          return $this->member;
 290      }
 291  
 292      /**
 293       * Rewind the members and reset member index.
 294       *
 295       * @since 1.0.0
 296       */
 297  	public function rewind_members() {
 298          $this->current_member = -1;
 299          if ( $this->member_count > 0 ) {
 300              $this->member = $this->members[0];
 301          }
 302      }
 303  
 304      /**
 305       * Whether there are members left in the loop to iterate over.
 306       *
 307       * This method is used by {@link bp_members()} as part of the while loop
 308       * that controls iteration inside the members loop, eg:
 309       *     while ( bp_members() ) { ...
 310       *
 311       * @since 1.2.0
 312       *
 313       * @see bp_members()
 314       *
 315       * @return bool True if there are more members to show, otherwise false.
 316       */
 317  	public function members() {
 318          if ( $this->current_member + 1 < $this->member_count ) {
 319              return true;
 320          } elseif ( $this->current_member + 1 === $this->member_count ) {
 321  
 322              /**
 323               * Fires right before the rewinding of members listing.
 324               *
 325               * @since 1.5.0
 326               */
 327              do_action('member_loop_end');
 328              // Do some cleaning up after the loop.
 329              $this->rewind_members();
 330          }
 331  
 332          $this->in_the_loop = false;
 333          return false;
 334      }
 335  
 336      /**
 337       * Set up the current member inside the loop.
 338       *
 339       * Used by {@link bp_the_member()} to set up the current member data
 340       * while looping, so that template tags used during that iteration make
 341       * reference to the current member.
 342       *
 343       * @since 1.0.0
 344       *
 345       * @see bp_the_member()
 346       */
 347  	public function the_member() {
 348          $this->in_the_loop = true;
 349          $this->member      = $this->next_member();
 350  
 351          // Loop has just started.
 352          if ( 0 === $this->current_member ) {
 353  
 354              /**
 355               * Fires if the current member is the first in the loop.
 356               *
 357               * @since 1.5.0
 358               */
 359              do_action( 'member_loop_start' );
 360          }
 361      }
 362  }