Changeset 8557 for trunk/src/bp-core/bp-core-classes.php

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

File:

• trunk/src/bp-core/bp-core-classes.php (modified) (1 diff)

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 );
+    }
+}