Changeset 8557

Timestamp:

07/03/2014 08:02:18 PM (12 years ago)

Author:

djpaul

Message:

at-mentions: overhaul the mentions implementation for Private Messages and Groups (admin) components.

Previously, these components had seperate implementations of username auto-suggestions, which weren't
reusable outside of where they'd been built, nor easily extended by developers, or other plugins.
This change creates a central API for auto-suggestions, currently only for usernames, but easily
extensible for other kinds of auto-suggestions in the future (i.e. group names, or #hashtags).

See #3278

Location:

trunk

Files:

• src/bp-core/bp-core-classes.php (modified) (1 diff)
• src/bp-core/bp-core-functions.php (modified) (1 diff)
• src/bp-groups/bp-groups-admin.php (modified) (1 diff)
• src/bp-groups/bp-groups-classes.php (modified) (1 diff)
• src/bp-templates/bp-legacy/buddypress-functions.php (modified) (1 diff)
• tests/phpunit/testcases/apis (added)
• tests/phpunit/testcases/apis/suggestions-nonauth.php (added)
• tests/phpunit/testcases/apis/suggestions.php (added)

trunk/src/bp-core/bp-core-classes.php

@@ -2408 +2408 @@
         }
 }
+
+/**
+ * Base class for the BuddyPress Suggestions API.
+ *
+ * Originally built to power BuddyPress' at-mentions suggestions, it's flexible enough to be used
+ * for similar kinds of future core requirements, or those desired by third-party developers.
+ *
+ * To implement a new suggestions service, create a new class that extends this one, and update
+ * the list of default services in {@link bp_core_get_suggestions()}. If you're building a plugin,
+ * it's recommend that you use the `bp_suggestions_services` filter to do this. :)
+ *
+ * While the implementation of the query logic is left to you, it should be as quick and efficient
+ * as possible. When implementing the abstract methods in this class, pay close attention to the
+ * recommendations provided in the phpDoc blocks, particularly the expected return types.
+ *
+ * @since BuddyPress (2.1.0)
+ */
+abstract class BP_Suggestions {
+
+        /**
+         * Default arguments common to all suggestions services.
+         * 
+         * If your custom service requires further defaults, add them here.
+         *
+         * @since BuddyPress (2.1.0)
+         * @var array
+         */
+        protected $default_args = array(
+                'limit' => 16,
+                'term'  => '',
+                'type'  => '',
+        );
+
+        /**
+         * Holds the arguments for the query (about to made to the suggestions service).
+         *
+         * This includes `$default_args`, as well as the user-supplied values.
+         *
+         * @since BuddyPress (2.1.0)
+         * @var array
+         */
+        protected $args = array(
+        );
+
+
+        /**
+         * Constructor.
+         *
+         * @param array $args Optional. If set, used as the parameters for the suggestions service query.
+         * @since BuddyPress (2.1.0)
+         */
+        public function __construct( array $args = array() ) {
+                if ( ! empty( $args ) ) {
+                        $this->set_query( $args );
+                }
+        }
+
+        /**
+         * Set the parameters for the suggestions service query.
+         *
+         * @param array $args {
+         *     @type int $limit Maximum number of results to display. Optional, default: 16.
+         *     @type string $type The name of the suggestion service to use for the request. Mandatory.
+         *     @type string $term The suggestion service will try to find results that contain this string.
+         *           Mandatory.
+         * }
+         * @since BuddyPress (2.1.0)
+         */
+        public function set_query( array $args = array() ) {
+                $this->args = wp_parse_args( $args, $this->default_args );
+        }
+
+        /**
+         * Validate and sanitise the parameters for the suggestion service query.
+         *
+         * Be sure to call this class' version of this method when implementing it in your own service.
+         * If validation fails, you must return a WP_Error object.
+         *
+         * @return true|WP_Error If validation fails, return a WP_Error object. On success, return true (bool).
+         * @since BuddyPress (2.1.0)
+         */
+        public function validate() {
+                $this->args['limit'] = absint( $this->args['limit'] );
+                $this->args['term']  = trim( sanitize_text_field( $this->args['term'] ) );
+                $this->args          = apply_filters( 'bp_suggestions_args', $this->args, $this );
+
+
+                // Check for invalid or missing mandatory parameters.
+                if ( ! $this->args['limit'] || ! $this->args['term'] ) {
+                        return new WP_Error( 'missing_parameter' );
+                }
+
+                // Check for blocked users (e.g. deleted accounts, or spammers).
+                if ( is_user_logged_in() && ! bp_is_user_active( get_current_user_id() ) ) {
+                        return new WP_Error( 'invalid_user' );
+                }
+
+                return apply_filters( 'bp_suggestions_validate_args', true, $this );
+        }
+
+        /**
+         * Find and return a list of suggestions that match the query.
+         *
+         * The return type is important. If no matches are found, an empty array must be returned.
+         * Matches must be returned as objects in an array.
+         *
+         * The object format for each match must be: { 'ID': string, 'image': string, 'name': string }
+         * For example: { 'ID': 'admin', 'image': 'http://example.com/logo.png', 'name': 'Name Surname' }
+         *
+         * @return array|WP_Error Array of results. If there were problems, returns a WP_Error object.
+         * @since BuddyPress (2.1.0)
+         */
+        abstract public function get_suggestions();
+}
+
+/**
+ * Adds support for user at-mentions to the Suggestions API.
+ *
+ * This class is in the Core component because it's required by a class in the Groups component,
+ * and Groups is loaded before Members (alphabetical order).
+ *
+ * @since BuddyPress (2.1.0)
+ */
+class BP_Members_Suggestions extends BP_Suggestions {
+
+        /**
+         * Default arguments for this suggestions service.
+         *
+         * @since BuddyPress (2.1.0)
+         * @var array $args {
+         *     @type int $limit Maximum number of results to display. Default: 16.
+         *     @type bool $only_friends If true, only match the current user's friends. Default: false.
+         *     @type string $term The suggestion service will try to find results that contain this string.
+         *           Mandatory.
+         * }
+         */
+        protected $default_args = array(
+                'limit'        => 16,
+                'only_friends' => false,
+                'term'         => '',
+                'type'         => '',
+        );
+
+
+        /**
+         * Validate and sanitise the parameters for the suggestion service query.
+         *
+         * @return true|WP_Error If validation fails, return a WP_Error object. On success, return true (bool).
+         * @since BuddyPress (2.1.0)
+         */
+        public function validate() {
+                $this->args['only_friends'] = (bool) $this->args['only_friends'];
+                $this->args                 = apply_filters( 'bp_members_suggestions_args', $this->args, $this );
+
+                // Check for invalid or missing mandatory parameters.
+                if ( $this->args['only_friends'] && ( ! bp_is_active( 'friends' ) || ! is_user_logged_in() ) ) {
+                        return new WP_Error( 'missing_requirement' );
+                }
+
+                return apply_filters( 'bp_members_suggestions_validate_args', parent::validate(), $this );
+        }
+
+        /**
+         * Find and return a list of username suggestions that match the query.
+         *
+         * @return array|WP_Error Array of results. If there were problems, returns a WP_Error object.
+         * @since BuddyPress (2.1.0)
+         */
+        public function get_suggestions() {
+                $user_query = array(
+                        'count_total'     => '',  // Prevents total count
+                        'populate_extras' => false,
+                        'type'            => 'alphabetical',
+
+                        'page'            => 1,
+                        'per_page'        => $this->args['limit'],
+                        'search_terms'    => $this->args['term'],
+                );
+
+                // Only return matches of friends of this user.
+                if ( $this->args['only_friends'] && is_user_logged_in() ) {
+                        $user_query['user_id'] = get_current_user_id();
+                }
+
+                $user_query = apply_filters( 'bp_members_suggestions_query_args', $user_query, $this );
+                if ( is_wp_error( $user_query ) ) {
+                        return $user_query;
+                }
+
+
+                $user_query = new BP_User_Query( $user_query );
+                $results    = array();
+
+                foreach ( $user_query->results as $user ) {
+                        $result        = new stdClass();
+                        $result->ID    = $user->user_nicename;
+                        $result->image = bp_core_fetch_avatar( array( 'html' => false, 'item_id' => $user->ID ) );
+                        $result->name  = bp_core_get_user_displayname( $user->ID );
+
+                        $results[] = $result;
+                }
+
+                return apply_filters( 'bp_members_suggestions_get_suggestions', $results, $this );
+        }
+}

trunk/src/bp-core/bp-core-functions.php

@@ -1922 +1922 @@
         return $nav_item_url;
 }
+
+/** Suggestions***************************************************************/
+
+/**
+ * BuddyPress Suggestions API for types of at-mentions.
+ *
+ * This is used to power BuddyPress' at-mentions suggestions, but it is flexible enough to be used
+ * for similar kinds of future requirements, or those implemented by third-party developers.
+ *
+ * @param array $args
+ * @return array|WP_Error Array of results. If there were any problems, returns a WP_Error object.
+ * @since BuddyPress (2.1.0)
+ */
+function bp_core_get_suggestions( $args ) {
+        $args = wp_parse_args( $args );
+
+        if ( ! $args['type'] ) {
+                return new WP_Error( 'missing_parameter' );
+        }
+
+        // Members @name suggestions.
+        if ( $args['type'] === 'members' ) {
+                $class = 'BP_Members_Suggestions';
+
+                // Members @name suggestions for users in a specific Group.
+                if ( isset( $args['group_id'] ) ) {
+                        $class = 'BP_Groups_Member_Suggestions';
+                }
+
+        } else {
+                // If you've built a custom suggestions service, use this to tell BP the name of your class.
+                $class = apply_filters( 'bp_suggestions_services', '', $args );
+        }
+
+        if ( ! $class || ! class_exists( $class ) ) {
+                return new WP_Error( 'missing_parameter' );
+        }
+
+
+        $suggestions = new $class( $args );
+        $validation  = $suggestions->validate();
+
+        if ( is_wp_error( $validation ) ) {
+                $retval = $validation;
+        } else {
+                $retval = $suggestions->get_suggestions();
+        }
+
+        return apply_filters( 'bp_core_get_suggestions', $retval, $args );
+}

trunk/src/bp-groups/bp-groups-admin.php

@@ -985 +985 @@
 
         // Bail if user user shouldn't be here, or is a large network
-        if ( ! current_user_can( 'bp_moderate' ) || ( is_multisite() && wp_is_large_network( 'users' ) ) )
+        if ( ! current_user_can( 'bp_moderate' ) || ( is_multisite() && wp_is_large_network( 'users' ) ) ) {
                 wp_die( -1 );
-
-        $return = array();
-
-        // Exclude current group members
-        $group_id = isset( $_GET['group_id'] ) ? wp_parse_id_list( $_GET['group_id'] ) : array();
-        $group_member_query = new BP_Group_Member_Query( array(
-                'group_id'        => $group_id,
-                'per_page'        => 0, // show all
-                'group_role'      => array( 'member', 'mod', 'admin', ),
-                'populate_extras' => false,
-                'count_total'     => false,
+        }
+
+        $term     = isset( $_GET['term'] )     ? sanitize_text_field( $_GET['term'] ) : '';
+        $group_id = isset( $_GET['group_id'] ) ? absint( $_GET['group_id'] )          : 0;
+
+        if ( ! $term || ! $group_id ) {
+                wp_die( -1 );
+        }
+
+        $suggestions = bp_core_get_suggestions( array(
+                'group_id' => -$group_id,  // A negative value will exclude this group's members from the suggestions.
+                'limit'    => 10,
+                'term'     => $term,
+                'type'     => 'members',
         ) );
 
-        $group_members = ! empty( $group_member_query->results ) ? wp_list_pluck( $group_member_query->results, 'ID' ) : array();
-
-        $terms = isset( $_GET['term'] ) ? $_GET['term'] : '';
-        $users = bp_core_get_users( array(
-                'type'            => 'alphabetical',
-                'search_terms'    => $terms,
-                'exclude'         => $group_members,
-                'per_page'        => 10,
-                'populate_extras' => false
-        ) );
-
-        foreach ( (array) $users['users'] as $user ) {
-                $return[] = array(
-                        /* translators: 1: user_login, 2: user_email */
-                        'label' => sprintf( __( '%1$s (%2$s)', 'buddypress' ), bp_is_username_compatibility_mode() ? $user->user_login : $user->user_nicename, $user->user_email ),
-                        'value' => $user->user_nicename,
-                );
-        }
-
-        wp_die( json_encode( $return ) );
+        $matches = array();
+
+        if ( $suggestions && ! is_wp_error( $suggestions ) ) {
+                foreach ( $suggestions as $user ) {
+
+                        $matches[] = array(
+                                // translators: 1: user_login, 2: user_email
+                                'label' => sprintf( __( '%1$s (%2$s)', 'buddypress' ), $user->name, $user->ID ),
+                                'value' => $user->ID,
+                        );
+                }
+        }
+
+        wp_die( json_encode( $matches ) );
 }
 add_action( 'wp_ajax_bp_group_admin_member_autocomplete', 'bp_groups_admin_autocomplete_handler' );

trunk/src/bp-groups/bp-groups-classes.php

@@ -4077 +4077 @@
         ' ), 11 );
 }
+
+/**
+ * Adds support for user at-mentions (for users in a specific Group) to the Suggestions API.
+ *
+ * @since BuddyPress (2.1.0)
+ */
+class BP_Groups_Member_Suggestions extends BP_Members_Suggestions {
+
+        /**
+         * Default arguments for this suggestions service.
+         *
+         * @since BuddyPress (2.1.0)
+         * @var array $args {
+         *     @type int $group_id Positive integers will restrict the search to members in that group.
+         *           Negative integers will restrict the search to members in every other group.
+         *     @type int $limit Maximum number of results to display. Default: 16.
+         *     @type bool $only_friends If true, only match the current user's friends. Default: false.
+         *     @type string $term The suggestion service will try to find results that contain this string.
+         *           Mandatory.
+         * }
+         */
+        protected $default_args = array(
+                'group_id'     => 0,
+                'limit'        => 16,
+                'only_friends' => false,
+                'term'         => '',
+                'type'         => '',
+        );
+
+
+        /**
+         * Validate and sanitise the parameters for the suggestion service query.
+         *
+         * @return true|WP_Error If validation fails, return a WP_Error object. On success, return true (bool).
+         * @since BuddyPress (2.1.0)
+         */
+        public function validate() {
+                $this->args['group_id'] = (int) $this->args['group_id'];
+                $this->args             = apply_filters( 'bp_groups_member_suggestions_args', $this->args, $this );
+
+                // Check for invalid or missing mandatory parameters.
+                if ( ! $this->args['group_id'] || ! bp_is_active( 'groups' ) ) {
+                        return new WP_Error( 'missing_requirement' );
+                }
+
+                // Check that the specified group_id exists, and that the current user can access it.
+                $the_group = groups_get_group( array(
+                        'group_id'        => absint( $this->args['group_id'] ),
+                        'populate_extras' => true,
+                ) );
+
+                if ( $the_group->id === 0 || ! $the_group->user_has_access ) {
+                        return new WP_Error( 'access_denied' );
+                }
+
+                return apply_filters( 'bp_groups_member_suggestions_validate_args', parent::validate(), $this );
+        }
+
+        /**
+         * Find and return a list of username suggestions that match the query.
+         *
+         * @return array|WP_Error Array of results. If there were problems, returns a WP_Error object.
+         * @since BuddyPress (2.1.0)
+         */
+        public function get_suggestions() {
+                $user_query = array(
+                        'count_total'     => '',  // Prevents total count
+                        'populate_extras' => false,
+                        'type'            => 'alphabetical',
+
+                        'group_role'      => array( 'admin', 'member', 'mod' ),
+                        'page'            => 1,
+                        'per_page'        => $this->args['limit'],
+                        'search_terms'    => $this->args['term'],
+                );
+
+                // Only return matches of friends of this user.
+                if ( $this->args['only_friends'] && is_user_logged_in() ) {
+                        $user_query['user_id'] = get_current_user_id();
+                }
+
+                // Positive Group IDs will restrict the search to members in that group.
+                if ( $this->args['group_id'] > 0 ) {
+                        $user_query['group_id'] = $this->args['group_id'];
+
+                // Negative Group IDs will restrict the search to members in every other group.
+                } else {
+                        $group_query = array(
+                                'count_total'     => '',  // Prevents total count
+                                'populate_extras' => false,
+                                'type'            => 'alphabetical',
+
+                                'group_id'        => absint( $this->args['group_id'] ),
+                                'group_role'      => array( 'admin', 'member', 'mod' ),
+                                'page'            => 1,
+                        );
+                        $group_users = new BP_Group_Member_Query( $group_query );
+
+                        if ( $group_users->results ) {
+                                $user_query['exclude'] = wp_list_pluck( $group_users->results, 'ID' );
+                        } else {
+                                $user_query['include'] = array( 0 );
+                        }
+                }
+
+                $user_query = apply_filters( 'bp_groups_member_suggestions_query_args', $user_query, $this );
+                if ( is_wp_error( $user_query ) ) {
+                        return $user_query;
+                }
+
+
+                if ( isset( $user_query['group_id'] ) ) {
+                        $user_query = new BP_Group_Member_Query( $user_query );
+                } else {
+                        $user_query = new BP_User_Query( $user_query );
+                }
+
+                $results = array();
+                foreach ( $user_query->results as $user ) {
+                        $result        = new stdClass();
+                        $result->ID    = $user->user_nicename;
+                        $result->image = bp_core_fetch_avatar( array( 'html' => false, 'item_id' => $user->ID ) );
+                        $result->name  = bp_core_get_user_displayname( $user->ID );
+
+                        $results[] = $result;
+                }
+
+                return apply_filters( 'bp_groups_member_suggestions_get_suggestions', $results, $this );
+        }
+}

trunk/src/bp-templates/bp-legacy/buddypress-functions.php

@@ -1384 +1384 @@
  */
 function bp_legacy_theme_ajax_messages_autocomplete_results() {
-
+        $limit = isset( $_GET['limit'] ) ? absint( $_GET['limit'] )          : (int) apply_filters( 'bp_autocomplete_max_results', 10 );
+        $term  = isset( $_GET['q'] )     ? sanitize_text_field( $_GET['q'] ) : '';
+        
         // Include everyone in the autocomplete, or just friends?
-        if ( bp_is_current_component( bp_get_messages_slug() ) )
-                $autocomplete_all = buddypress()->messages->autocomplete_all;
-
-        $pag_page     = 1;
-        $limit        = (int) $_GET['limit'] ? $_GET['limit'] : apply_filters( 'bp_autocomplete_max_results', 10 );
-        $search_terms = isset( $_GET['q'] ) ? $_GET['q'] : '';
-
-        $user_query_args = array(
-                'search_terms' => $search_terms,
-                'page'         => intval( $pag_page ),
-                'per_page'     => intval( $limit ),
-        );
-
-        // If only matching against friends, get an $include param for
-        // BP_User_Query
-        if ( ! $autocomplete_all && bp_is_active( 'friends' ) ) {
-                $include = BP_Friends_Friendship::get_friend_user_ids( bp_loggedin_user_id() );
-
-                // Ensure zero matches if no friends are found
-                if ( empty( $include ) ) {
-                        $include = array( 0 );
-                }
-
-                $user_query_args['include'] = $include;
-        }
-
-        $user_query = new BP_User_Query( $user_query_args );
-
-        // Backward compatibility - if a plugin is expecting a legacy
-        // filter, pass the IDs through the filter and requery (groan)
-        if ( has_filter( 'bp_core_autocomplete_ids' ) || has_filter( 'bp_friends_autocomplete_ids' ) ) {
-                $found_user_ids = wp_list_pluck( $user_query->results, 'ID' );
-
-                if ( $autocomplete_all ) {
-                        $found_user_ids = apply_filters( 'bp_core_autocomplete_ids', $found_user_ids );
-                } else {
-                        $found_user_ids = apply_filters( 'bp_friends_autocomplete_ids', $found_user_ids );
-                }
-
-                if ( empty( $found_user_ids ) ) {
-                        $found_user_ids = array( 0 );
-                }
-
-                // Repopulate the $user_query variable
-                $user_query = new BP_User_Query( array(
-                        'include' => $found_user_ids,
-                ) );
-        }
-
-        if ( ! empty( $user_query->results ) ) {
-                foreach ( $user_query->results as $user ) {
-                        if ( bp_is_username_compatibility_mode() ) {
-                                // Sanitize for spaces. Use urlencode() rather
-                                // than rawurlencode() because %20 breaks JS
-                                $username = urlencode( $user->user_login );
-                        } else {
-                                $username = $user->user_nicename;
-                        }
+        if ( bp_is_current_component( bp_get_messages_slug() ) ) {
+                $only_friends = ( buddypress()->messages->autocomplete_all === false );
+        } else {
+                $only_friends = true;
+        }
+
+        $suggestions = bp_core_get_suggestions( array(
+                'limit'        => $limit,
+                'only_friends' => $only_friends,
+                'term'         => $term,
+                'type'         => 'members',
+        ) );
+
+        if ( $suggestions && ! is_wp_error( $suggestions ) ) {
+                foreach ( $suggestions as $user ) {
 
                         // Note that the final line break acts as a delimiter for the
                         // autocomplete javascript and thus should not be removed
-                        echo '<span id="link-' . esc_attr( $username ) . '" href="' . bp_core_get_user_domain( $user->ID ) . '"></span>' . bp_core_fetch_avatar( array( 'item_id' => $user->ID, 'type' => 'thumb', 'width' => 15, 'height' => 15, 'alt' => $user->display_name ) ) . ' &nbsp;' . bp_core_get_user_displayname( $user->ID ) . ' (' . esc_html( $username ) . ')' . "\n";
-                }
-        }
-
-        exit;
-}
+                        printf( '<span id="%s" href="#"></span><img src="%s" style="width: 15px"> &nbsp; %s (%s)' . "\n",
+                                esc_attr( 'link-' . $user->ID ),
+                                esc_url( $user->image ),
+                                esc_html( $user->name ),
+                                esc_html( $user->ID )
+                        );
+                }
+        }
+
+        exit;
+}