[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          $r = wp_parse_args( $args, $defaults );
 177  
 178          $this->pag_arg  = sanitize_key( $r['page_arg'] );
 179          $this->pag_page = bp_sanitize_pagination_arg( $this->pag_arg, $r['page_number'] );
 180          $this->pag_num  = bp_sanitize_pagination_arg( 'num',          $r['per_page']    );
 181          $this->type     = $r['type'];
 182  
 183          if ( ! empty( $_REQUEST['letter'] ) ) {
 184              $this->members = BP_Core_User::get_users_by_letter( $_REQUEST['letter'], $this->pag_num, $this->pag_page, $r['populate_extras'], $r['exclude'] );
 185          } else {
 186              $this->members = bp_core_get_users(
 187                  array(
 188                      'type'                => $this->type,
 189                      'per_page'            => $this->pag_num,
 190                      'page'                => $this->pag_page,
 191                      'user_id'             => $r['user_id'],
 192                      'include'             => $r['include'],
 193                      'search_terms'        => $r['search_terms'],
 194                      'populate_extras'     => $r['populate_extras'],
 195                      'exclude'             => $r['exclude'],
 196                      'user_ids'            => $r['user_ids'],
 197                      'meta_key'            => $r['meta_key'],
 198                      'meta_value'          => $r['meta_value'],
 199                      'member_type'         => $r['member_type'],
 200                      'member_type__in'     => $r['member_type__in'],
 201                      'member_type__not_in' => $r['member_type__not_in'],
 202                      'xprofile_query'      => $r['xprofile_query'],
 203                  )
 204              );
 205          }
 206  
 207          if ( ! $r['max'] || $r['max'] >= (int) $this->members['total'] ) {
 208              $this->total_member_count = (int) $this->members['total'];
 209          } else {
 210              $this->total_member_count = (int) $r['max'];
 211          }
 212  
 213          $this->members = $this->members['users'];
 214  
 215          if ( $r['max'] ) {
 216              if ( $r['max'] >= count( $this->members ) ) {
 217                  $this->member_count = count( $this->members );
 218              } else {
 219                  $this->member_count = (int) $r['max'];
 220              }
 221          } else {
 222              $this->member_count = count( $this->members );
 223          }
 224  
 225          if ( (int) $this->total_member_count && (int) $this->pag_num ) {
 226              $pag_args = array(
 227                  $this->pag_arg => '%#%',
 228              );
 229  
 230              if ( defined( 'DOING_AJAX' ) && true === (bool) DOING_AJAX ) {
 231                  $base = remove_query_arg( 's', wp_get_referer() );
 232              } else {
 233                  $base = '';
 234              }
 235  
 236              /**
 237               * Defaults to an empty array to make sure paginate_links()
 238               * won't add the $page_arg to the links which would break
 239               * pagination in case JavaScript is disabled.
 240               */
 241              $add_args = array();
 242  
 243              if ( ! empty( $r['search_terms'] ) ) {
 244                  $query_arg = bp_core_get_component_search_query_arg( 'members' );
 245                  $add_args[ $query_arg ] = urlencode( $r['search_terms'] );
 246              }
 247  
 248              $this->pag_links = paginate_links( array(
 249                  'base'      => add_query_arg( $pag_args, $base ),
 250                  'format'    => '',
 251                  'total'     => ceil( (int) $this->total_member_count / (int) $this->pag_num ),
 252                  'current'   => (int) $this->pag_page,
 253                  'prev_text' => _x( '&larr;', 'Member pagination previous text', 'buddypress' ),
 254                  'next_text' => _x( '&rarr;', 'Member pagination next text', 'buddypress' ),
 255                  'mid_size'  => 1,
 256                  'add_args'  => $add_args,
 257              ) );
 258          }
 259      }
 260  
 261      /**
 262       * Whether there are members available in the loop.
 263       *
 264       * @since 1.0.0
 265       *
 266       * @see bp_has_members()
 267       *
 268       * @return bool True if there are items in the loop, otherwise false.
 269       */
 270  	function has_members() {
 271          if ( $this->member_count )
 272              return true;
 273  
 274          return false;
 275      }
 276  
 277      /**
 278       * Set up the next member and iterate index.
 279       *
 280       * @since 1.0.0
 281       *
 282       * @return object The next member to iterate over.
 283       */
 284  	function next_member() {
 285          $this->current_member++;
 286          $this->member = $this->members[$this->current_member];
 287  
 288          return $this->member;
 289      }
 290  
 291      /**
 292       * Rewind the members and reset member index.
 293       *
 294       * @since 1.0.0
 295       */
 296  	function rewind_members() {
 297          $this->current_member = -1;
 298          if ( $this->member_count > 0 ) {
 299              $this->member = $this->members[0];
 300          }
 301      }
 302  
 303      /**
 304       * Whether there are members left in the loop to iterate over.
 305       *
 306       * This method is used by {@link bp_members()} as part of the while loop
 307       * that controls iteration inside the members loop, eg:
 308       *     while ( bp_members() ) { ...
 309       *
 310       * @since 1.2.0
 311       *
 312       * @see bp_members()
 313       *
 314       * @return bool True if there are more members to show, otherwise false.
 315       */
 316  	function members() {
 317          if ( $this->current_member + 1 < $this->member_count ) {
 318              return true;
 319          } elseif ( $this->current_member + 1 == $this->member_count ) {
 320  
 321              /**
 322               * Fires right before the rewinding of members listing.
 323               *
 324               * @since 1.5.0
 325               */
 326              do_action('member_loop_end');
 327              // Do some cleaning up after the loop.
 328              $this->rewind_members();
 329          }
 330  
 331          $this->in_the_loop = false;
 332          return false;
 333      }
 334  
 335      /**
 336       * Set up the current member inside the loop.
 337       *
 338       * Used by {@link bp_the_member()} to set up the current member data
 339       * while looping, so that template tags used during that iteration make
 340       * reference to the current member.
 341       *
 342       * @since 1.0.0
 343       *
 344       * @see bp_the_member()
 345       */
 346  	function the_member() {
 347  
 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      }
 363  }