[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       * @since 10.0.0 Added `$date_query` parameter.
 115       *
 116       * @see BP_User_Query for an in-depth description of parameters.
 117       *
 118       * @param array ...$args {
 119       *     Array of arguments. Supports all arguments of BP_User_Query. Additional
 120       *     arguments, or those with different defaults, are described below.
 121       *
 122       *     @type int    $page_number Page of results. Accepted for legacy reasons. Use 'page' instead.
 123       *     @type int    $max         Max number of results to return.
 124       *     @type string $page_arg    Optional. The string used as a query parameter in pagination links.
 125       * }
 126       */
 127  	public function __construct( ...$args ) {
 128          // Backward compatibility with old method of passing arguments.
 129          if ( ! is_array( $args[0] ) || count( $args ) > 1 ) {
 130              _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__ ) );
 131  
 132              $old_args_keys = array(
 133                  0  => 'type',
 134                  1  => 'page_number',
 135                  2  => 'per_page',
 136                  3  => 'max',
 137                  4  => 'user_id',
 138                  5  => 'search_terms',
 139                  6  => 'include',
 140                  7  => 'populate_extras',
 141                  8  => 'exclude',
 142                  9  => 'meta_key',
 143                  10 => 'meta_value',
 144                  11 => 'page_arg',
 145                  12 => 'member_type',
 146                  13 => 'member_type__in',
 147                  14 => 'member_type__not_in'
 148              );
 149  
 150              $args = bp_core_parse_args_array( $old_args_keys, $args );
 151          } else {
 152              $args = reset( $args );
 153          }
 154  
 155          // Support both 'page_number' and 'page' for backward compatibility.
 156          $args['page_number'] = isset( $args['page_number'] ) ? $args['page_number'] : $args['page'];
 157  
 158          $defaults = array(
 159              'type'                => 'active',
 160              'page_number'         => 1,
 161              'per_page'            => 20,
 162              'max'                 => false,
 163              'user_id'             => false,
 164              'search_terms'        => null,
 165              'include'             => false,
 166              'populate_extras'     => true,
 167              'exclude'             => false,
 168              'user_ids'            => false,
 169              'meta_key'            => false,
 170              'meta_value'          => false,
 171              'page_arg'            => 'upage',
 172              'member_type'         => '',
 173              'member_type__in'     => '',
 174              'member_type__not_in' => '',
 175              'xprofile_query'      => false,
 176              'date_query'          => false,
 177          );
 178  
 179          $r = bp_parse_args(
 180              $args,
 181              $defaults
 182          );
 183  
 184          $this->pag_arg  = sanitize_key( $r['page_arg'] );
 185          $this->pag_page = bp_sanitize_pagination_arg( $this->pag_arg, $r['page_number'] );
 186          $this->pag_num  = bp_sanitize_pagination_arg( 'num',          $r['per_page']    );
 187          $this->type     = $r['type'];
 188  
 189          if ( ! empty( $_REQUEST['letter'] ) ) {
 190              $this->members = BP_Core_User::get_users_by_letter( $_REQUEST['letter'], $this->pag_num, $this->pag_page, $r['populate_extras'], $r['exclude'] );
 191          } else {
 192              $this->members = bp_core_get_users(
 193                  array(
 194                      'type'                => $this->type,
 195                      'per_page'            => $this->pag_num,
 196                      'page'                => $this->pag_page,
 197                      'user_id'             => $r['user_id'],
 198                      'include'             => $r['include'],
 199                      'search_terms'        => $r['search_terms'],
 200                      'populate_extras'     => $r['populate_extras'],
 201                      'exclude'             => $r['exclude'],
 202                      'user_ids'            => $r['user_ids'],
 203                      'meta_key'            => $r['meta_key'],
 204                      'meta_value'          => $r['meta_value'],
 205                      'member_type'         => $r['member_type'],
 206                      'member_type__in'     => $r['member_type__in'],
 207                      'member_type__not_in' => $r['member_type__not_in'],
 208                      'xprofile_query'      => $r['xprofile_query'],
 209                      'date_query'          => $r['date_query'],
 210                  )
 211              );
 212          }
 213  
 214          if ( ! $r['max'] || $r['max'] >= (int) $this->members['total'] ) {
 215              $this->total_member_count = (int) $this->members['total'];
 216          } else {
 217              $this->total_member_count = (int) $r['max'];
 218          }
 219  
 220          $this->members = $this->members['users'];
 221  
 222          if ( $r['max'] ) {
 223              if ( $r['max'] >= count( $this->members ) ) {
 224                  $this->member_count = count( $this->members );
 225              } else {
 226                  $this->member_count = (int) $r['max'];
 227              }
 228          } else {
 229              $this->member_count = count( $this->members );
 230          }
 231  
 232          if ( (int) $this->total_member_count && (int) $this->pag_num ) {
 233              $pag_args = array(
 234                  $this->pag_arg => '%#%',
 235              );
 236  
 237              if ( defined( 'DOING_AJAX' ) && true === (bool) DOING_AJAX ) {
 238                  $base = remove_query_arg( 's', wp_get_referer() );
 239              } else {
 240                  $base = '';
 241              }
 242  
 243              /**
 244               * Defaults to an empty array to make sure paginate_links()
 245               * won't add the $page_arg to the links which would break
 246               * pagination in case JavaScript is disabled.
 247               */
 248              $add_args = array();
 249  
 250              if ( ! empty( $r['search_terms'] ) ) {
 251                  $query_arg = bp_core_get_component_search_query_arg( 'members' );
 252                  $add_args[ $query_arg ] = urlencode( $r['search_terms'] );
 253              }
 254  
 255              $this->pag_links = paginate_links( array(
 256                  'base'      => add_query_arg( $pag_args, $base ),
 257                  'format'    => '',
 258                  'total'     => ceil( (int) $this->total_member_count / (int) $this->pag_num ),
 259                  'current'   => (int) $this->pag_page,
 260                  'prev_text' => _x( '&larr;', 'Member pagination previous text', 'buddypress' ),
 261                  'next_text' => _x( '&rarr;', 'Member pagination next text', 'buddypress' ),
 262                  'mid_size'  => 1,
 263                  'add_args'  => $add_args,
 264              ) );
 265          }
 266      }
 267  
 268      /**
 269       * Whether there are members available in the loop.
 270       *
 271       * @since 1.0.0
 272       *
 273       * @see bp_has_members()
 274       *
 275       * @return bool True if there are items in the loop, otherwise false.
 276       */
 277  	public function has_members() {
 278          return ! empty( $this->member_count );
 279      }
 280  
 281      /**
 282       * Set up the next member and iterate index.
 283       *
 284       * @since 1.0.0
 285       *
 286       * @return object The next member to iterate over.
 287       */
 288  	public function next_member() {
 289          $this->current_member++;
 290          $this->member = $this->members[ $this->current_member ];
 291  
 292          return $this->member;
 293      }
 294  
 295      /**
 296       * Rewind the members and reset member index.
 297       *
 298       * @since 1.0.0
 299       */
 300  	public function rewind_members() {
 301          $this->current_member = -1;
 302          if ( $this->member_count > 0 ) {
 303              $this->member = $this->members[0];
 304          }
 305      }
 306  
 307      /**
 308       * Whether there are members left in the loop to iterate over.
 309       *
 310       * This method is used by {@link bp_members()} as part of the while loop
 311       * that controls iteration inside the members loop, eg:
 312       *     while ( bp_members() ) { ...
 313       *
 314       * @since 1.2.0
 315       *
 316       * @see bp_members()
 317       *
 318       * @return bool True if there are more members to show, otherwise false.
 319       */
 320  	public function members() {
 321          if ( $this->current_member + 1 < $this->member_count ) {
 322              return true;
 323          } elseif ( $this->current_member + 1 === $this->member_count ) {
 324  
 325              /**
 326               * Fires right before the rewinding of members listing.
 327               *
 328               * @since 1.5.0
 329               */
 330              do_action('member_loop_end');
 331              // Do some cleaning up after the loop.
 332              $this->rewind_members();
 333          }
 334  
 335          $this->in_the_loop = false;
 336          return false;
 337      }
 338  
 339      /**
 340       * Set up the current member inside the loop.
 341       *
 342       * Used by {@link bp_the_member()} to set up the current member data
 343       * while looping, so that template tags used during that iteration make
 344       * reference to the current member.
 345       *
 346       * @since 1.0.0
 347       *
 348       * @see bp_the_member()
 349       */
 350  	public function the_member() {
 351          $this->in_the_loop = true;
 352          $this->member      = $this->next_member();
 353  
 354          // Loop has just started.
 355          if ( 0 === $this->current_member ) {
 356  
 357              /**
 358               * Fires if the current member is the first in the loop.
 359               *
 360               * @since 1.5.0
 361               */
 362              do_action( 'member_loop_start' );
 363          }
 364      }
 365  }