Changeset 8557

Timestamp:

07/03/2014 08:02:18 PM (10 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;
+}