Skip to:
Content

BuddyPress.org

Changeset 7645


Ignore:
Timestamp:
12/04/2013 02:07:20 AM (13 years ago)
Author:
boonebgorges
Message:

Improve documentation in the Groups component. See #5022

Location:
trunk/bp-groups
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-groups/bp-groups-buddybar.php

    r7228 r7645  
    1212
    1313/**
    14  * Adds menu items to the BuddyBar
     14 * Add menu items to the BuddyBar.
    1515 *
    16  * @since BuddyPress (1.0)
     16 * @since BuddyPress (1.0.0)
     17 *
    1718 * @global BuddyPress $bp
    1819 */

  • trunk/bp-groups/bp-groups-cache.php

    r7183 r7645  
    1515
    1616/**
    17  * Slurps up groupmeta
     17 * Slurp up metadata for a set of groups.
    1818 *
    1919 * This function is called in two places in the BP_Groups_Group class:
    … …  
    2121 *   - in the get() method, when multiple groups are queried
    2222 *
    23  * It grabs all groupmeta associated with all of the groups passed in $group_ids and adds it to
    24  * the WP cache. This improves efficiency when using groupmeta inline
     23 * It grabs all groupmeta associated with all of the groups passed in
     24 * $group_ids and adds it to WP cache. This improves efficiency when using
     25 * groupmeta within a loop context.
    2526 *
    26  * @param int|str|array $group_ids Accepts a single group_id, or a comma-separated list or array of
    27  *    group ids
     27 * @param int|str|array $group_ids Accepts a single group_id, or a
     28 *        comma-separated list or array of group ids.
    2829 */
    2930function bp_groups_update_meta_cache( $group_ids = false ) {
    … …  
    4142}
    4243
     44/**
     45 * Clear the cached group count.
     46 *
     47 * @param $group_id Not used.
     48 */
    4349function groups_clear_group_object_cache( $group_id ) {
    4450        wp_cache_delete( 'bp_total_group_count', 'bp' );
    … …  
    5157
    5258/**
    53  * Bust group caches when editing or deleting
     59 * Bust group caches when editing or deleting.
    5460 *
    55  * @since BuddyPress (1.7)
    56  * @param int $group_id The group being edited
     61 * @since BuddyPress (1.7.0)
     62 *
     63 * @param int $group_id The group being edited.
    5764 */
    5865function bp_groups_delete_group_cache( $group_id = 0 ) {
    … …  
    6673
    6774/**
    68  * Clears caches for the group creator when a group is created
     75 * Clear caches for the group creator when a group is created.
    6976 *
    70  * @param int $group_id
    71  * @param BP_Groups_Group $group_obj
    72  * @since BuddyPress (1.6)
     77 * @since BuddyPress (1.6.0)
     78 *
     79 * @param int $group_id ID of the group.
     80 * @param BP_Groups_Group $group_obj Group object.
    7381 */
    7482function bp_groups_clear_group_creator_cache( $group_id, $group_obj ) {
    … …  
    8189 * Clears caches for all members in a group when a group is deleted
    8290 *
    83  * @param BP_Groups_Group $group_obj
    84  * @param array User IDs who were in this group
    85  * @since BuddyPress (1.6)
     91 * @since BuddyPress (1.6.0)
     92 *
     93 * @param BP_Groups_Group $group_obj Group object.
     94 * @param array User IDs who were in this group.
    8695 */
    8796function bp_groups_clear_group_members_caches( $group_obj, $user_ids ) {
    … …  
    92101add_action( 'bp_groups_delete_group', 'bp_groups_clear_group_members_caches', 10, 2 );
    93102
     103/**
     104 * Clear a user's cached group count.
     105 *
     106 * @param int $group_id ID of the group. Not used in this function.
     107 * @param int $user_id ID of the user whose group count is being changed.
     108 */
    94109function groups_clear_group_user_object_cache( $group_id, $user_id ) {
    95110        wp_cache_delete( 'bp_total_groups_for_user_' . $user_id, 'bp' );

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

    r7616 r7645  
    1111if ( !defined( 'ABSPATH' ) ) exit;
    1212
     13/**
     14 * BuddyPress Group object.
     15 */
    1316class BP_Groups_Group {
     17
     18        /**
     19         * ID of the group.
     20         *
     21         * @access public
     22         * @var int
     23         */
    1424        public $id;
     25
     26        /**
     27         * User ID of the group's creator.
     28         *
     29         * @access public
     30         * @var int
     31         */
    1532        public $creator_id;
     33
     34        /**
     35         * Name of the group.
     36         *
     37         * @access public
     38         * @var string
     39         */
    1640        public $name;
     41
     42        /**
     43         * Group slug.
     44         *
     45         * @access public
     46         * @var string
     47         */
    1748        public $slug;
     49
     50        /**
     51         * Group description.
     52         *
     53         * @access public
     54         * @var string
     55         */
    1856        public $description;
     57
     58        /**
     59         * Group status.
     60         *
     61         * Core statuses are 'public', 'private', and 'hidden'.
     62         *
     63         * @access public
     64         * @var string
     65         */
    1966        public $status;
     67
     68        /**
     69         * Should (legacy) bbPress forums be enabled for this group?
     70         *
     71         * @access public
     72         * @var int
     73         */
    2074        public $enable_forum;
     75
     76        /**
     77         * Date the group was created.
     78         *
     79         * @access public
     80         * @var string
     81         */
    2182        public $date_created;
    2283
     84        /**
     85         * Data about the group's admins.
     86         *
     87         * @access public
     88         * @var array
     89         */
    2390        public $admins;
     91
     92        /**
     93         * Data about the group's moderators.
     94         *
     95         * @access public
     96         * @var array
     97         */
    2498        public $mods;
     99
     100        /**
     101         * Total count of group members.
     102         *
     103         * @access public
     104         * @var int
     105         */
    25106        public $total_member_count;
    26107
    … …  
    28109         * Is the current user a member of this group?
    29110         *
    30          * @since BuddyPress (1.2)
     111         * @since BuddyPress (1.2.0)
    31112         * @var bool
    32113         */
    … …  
    52133         * Timestamp of the last activity that happened in this group.
    53134         *
    54          * @since BuddyPress (1.2)
     135         * @since BuddyPress (1.2.0)
    55136         * @var string
    56137         */
    … …  
    60141         * If this is a private or hidden group, does the current user have access?
    61142         *
    62          * @since BuddyPress (1.6)
     143         * @since BuddyPress (1.6.0)
    63144         * @var bool
    64145         */
    65146        public $user_has_access;
    66147
     148        /**
     149         * Constructor method.
     150         *
     151         * @param int $id Optional. If the ID of an existing group is provided,
     152         *        the object will be pre-populated with info about that group.
     153         */
    67154        public function __construct( $id = null ) {
    68155                if ( !empty( $id ) ) {
    … …  
    72159        }
    73160
     161        /**
     162         * Set up data about the current group.
     163         */
    74164        public function populate() {
    75165                global $wpdb, $bp;
    … …  
    115205        }
    116206
     207        /**
     208         * Save the current group to the database.
     209         *
     210         * @return bool True on success, false on failure.
     211         */
    117212        public function save() {
    118213                global $wpdb, $bp;
    … …  
    186281        }
    187282
     283        /**
     284         * Delete the current group.
     285         *
     286         * @return bool True on success, false on failure.
     287         */
    188288        public function delete() {
    189289                global $wpdb, $bp;
    … …  
    213313        }
    214314
    215         /** Static Methods ********************************************************/
    216 
     315        /** Static Methods ****************************************************/
     316
     317        /**
     318         * Get whether a group exists for a given slug.
     319         *
     320         * @param string $slug Slug to check.
     321         * @param string $table_name Optional. Name of the table to check
     322         *        against. Default: $bp->groups->table_name.
     323         * @return string|null ID of the group, if one is found, else null.
     324         */
    217325        public static function group_exists( $slug, $table_name = false ) {
    218326                global $wpdb, $bp;
    … …  
    227335        }
    228336
     337        /**
     338         * Get the ID of a group by the group's slug.
     339         *
     340         * Alias of {@link BP_Groups_Group::group_exists()}.
     341         *
     342         * @param string $slug See {@link BP_Groups_Group::group_exists()}.
     343         * @return string|null See {@link BP_Groups_Group::group_exists()}.
     344         */
    229345        public static function get_id_from_slug( $slug ) {
    230346                return BP_Groups_Group::group_exists( $slug );
    231347        }
    232348
     349        /**
     350         * Get IDs of users with outstanding invites to a given group from a specified user.
     351         *
     352         * @param int $user_id ID of the inviting user.
     353         * @param int $group_id ID of the group.
     354         * @return array IDs of users who have been invited to the group by the
     355         *         user but have not yet accepted.
     356         */
    233357        public static function get_invites( $user_id, $group_id ) {
    234358                global $wpdb, $bp;
    … …  
    236360        }
    237361
     362        /**
     363         * Get a list of a user's groups, filtered by a search string.
     364         *
     365         * @param string $filter Search term. Matches against 'name' and
     366         *        'description' fields.
     367         * @param int $user_id ID of the user whose groups are being searched.
     368         *        Default: the displayed user.
     369         * @param mixed $order Not used.
     370         * @param int $limit Optional. The max number of results to return.
     371         *        Default: null (no limit).
     372         * @param int $page Optional. The page offset of results to return.
     373         *        Default: null (no limit).
     374         * @return array {
     375         *     @type array $groups Array of matched and paginated group objects.
     376         *     @type int $total Total count of groups matching the query.
     377         * }
     378         */
    238379        public static function filter_user_groups( $filter, $user_id = 0, $order = false, $limit = null, $page = null ) {
    239380                global $wpdb, $bp;
    … …  
    264405
    265406        /**
    266          * @todo Deprecate in favor of get()
     407         * Get a list of groups, filtered by a search string.
     408         *
     409         * @param string $filter Search term. Matches against 'name' and
     410         *        'description' fields.
     411         * @param int $limit Optional. The max number of results to return.
     412         *        Default: null (no limit).
     413         * @param int $page Optional. The page offset of results to return.
     414         *        Default: null (no limit).
     415         * @param string $sort_by Column to sort by. Default: false (default
     416         *        sort).
     417         * @param string $order ASC or DESC. Default: false (default sort).
     418         * @return array {
     419         *     @type array $groups Array of matched and paginated group objects.
     420         *     @type int $total Total count of groups matching the query.
     421         * }
    267422         */
    268423        public static function search_groups( $filter, $limit = null, $page = null, $sort_by = false, $order = false ) {
    … …  
    291446        }
    292447
     448        /**
     449         * Check for the existence of a slug.
     450         *
     451         * @param string $slug Slug to check.
     452         * @return string|null The slug, if found. Otherwise null.
     453         */
    293454        public static function check_slug( $slug ) {
    294455                global $wpdb, $bp;
    … …  
    297458        }
    298459
     460        /**
     461         * Get the slug for a given group ID.
     462         *
     463         * @param int $group_id ID of the group.
     464         * @return string|null The slug, if found. Otherwise null.
     465         */
    299466        public static function get_slug( $group_id ) {
    300467                global $wpdb, $bp;
    … …  
    303470        }
    304471
     472        /**
     473         * Check whether a given group has any members.
     474         *
     475         * @param int $group_id ID of the group.
     476         * @return bool True if the group has members, otherwise false.
     477         */
    305478        public static function has_members( $group_id ) {
    306479                global $wpdb, $bp;
    … …  
    314487        }
    315488
     489        /**
     490         * Check whether a group has outstanding membership requests.
     491         *
     492         * @param int $group_id ID of the group.
     493         * @return int|null The number of outstanding requests, or null if
     494         *         none are found.
     495         */
    316496        public static function has_membership_requests( $group_id ) {
    317497                global $wpdb, $bp;
    … …  
    320500        }
    321501
     502        /**
     503         * Get outstanding membership requests for a group.
     504         *
     505         * @param int $group_id ID of the group.
     506         * @param int $limit Optional. Max number of results to return.
     507         *        Default: null (no limit).
     508         * @param int $page Optional. Page offset of results returned. Default:
     509         *        null (no limit).
     510         * @return array {
     511         *     @type array $requests The requested page of located requests.
     512         *     @type int $total Total number of requests outstanding for the
     513         *           group.
     514         * }
     515         */
    322516        public static function get_membership_requests( $group_id, $limit = null, $page = null ) {
    323517                global $wpdb, $bp;
    … …  
    333527        }
    334528
     529        /**
     530         * Query for groups.
     531         *
     532         * @see WP_Meta_Query::queries for a description of the 'meta_query'
     533         *      parameter format.
     534         *
     535         * @param array {
     536         *     Array of parameters. All items are optional.
     537         *     @type string $type Optional. Shorthand for certain orderby/
     538         *           order combinations. 'newest', 'active', 'popular',
     539         *           'alphabetical', 'random'. When present, will override
     540         *           orderby and order params. Default: null.
     541         *     @type string $orderby Optional. Property to sort by.
     542         *           'date_created', 'last_activity', 'total_member_count',
     543         *           'name', 'random'. Default: 'date_created'.
     544         *     @type string $order Optional. Sort order. 'ASC' or 'DESC'.
     545         *           Default: 'DESC'.
     546         *     @type int $per_page Optional. Number of items to return per page
     547         *           of results. Default: null (no limit).
     548         *     @type int $page Optional. Page offset of results to return.
     549         *           Default: null (no limit).
     550         *     @type int $user_id Optional. If provided, results will be limited
     551         *           to groups of which the specified user is a member. Default:
     552         *           null.
     553         *     @type string $search_terms Optional. If provided, only groups
     554         *           whose names or descriptions match the search terms will be
     555         *           returned. Default: false.
     556         *     @type array $meta_query Optional. An array of meta_query
     557         *           conditions. See {@link WP_Meta_Query::queries} for
     558         *           description.
     559         *     @type array|string Optional. Array or comma-separated list of
     560         *           group IDs. Results will be limited to groups within the
     561         *           list. Default: false.
     562         *     @type bool $populate_extras Whether to fetch additional
     563         *           information (such as member count) about groups. Default:
     564         *           true.
     565         *     @type array|string Optional. Array or comma-separated list of
     566         *           group IDs. Results will exclude the listed groups.
     567         *           Default: false.
     568         *     @type bool $show_hidden Whether to include hidden groups in
     569         *           results. Default: false.
     570         * }
     571         * @return array {
     572         *     @type array $groups Array of group objects returned by the
     573         *           paginated query.
     574         *     @type int $total Total count of all groups matching non-
     575         *           paginated query params.
     576         * }
     577         */
    335578        public static function get( $args = array() ) {
    336579                global $wpdb, $bp;
    … …  
    547790         * AND keyword from the 'where' clause).
    548791         *
    549          * @since BuddyPress (1.8)
     792         * @since BuddyPress (1.8.0)
    550793         * @access protected
    551794         *
    552795         * @param array $meta_query An array of meta_query filters. See the
    553          *   documentation for WP_Meta_Query for details.
    554          * @return array $sql_array 'join' and 'where' clauses
     796         *        documentation for {@link WP_Meta_Query} for details.
     797         * @return array $sql_array 'join' and 'where' clauses.
    555798         */
    556799        protected static function get_meta_query_sql( $meta_query = array() ) {
    … …  
    599842
    600843        /**
    601          * Convert the 'type' parameter to 'order' and 'orderby'
    602          *
    603          * @since BuddyPress (1.8)
     844         * Convert the 'type' parameter to 'order' and 'orderby'.
     845         *
     846         * @since BuddyPress (1.8.0)
    604847         * @access protected
    605          * @param string $type The 'type' shorthand param
    606          * @return array 'order' and 'orderby'
     848         *
     849         * @param string $type The 'type' shorthand param.
     850         * @return array {
     851         *      @type string $order SQL-friendly order string.
     852         *      @type string $orderby SQL-friendly orderby column name.
     853         * }
    607854         */
    608855        protected static function convert_type_to_order_orderby( $type = '' ) {
    … …  
    640887
    641888        /**
    642          * Convert the 'orderby' param into a proper SQL term/column
    643          *
    644          * @since BuddyPress (1.8)
     889         * Convert the 'orderby' param into a proper SQL term/column.
     890         *
     891         * @since BuddyPress (1.8.0)
    645892         * @access protected
    646          * @param string $orderby
    647          * @return string $order_by_term
     893         *
     894         * @param string $orderby Orderby term as passed to get().
     895         * @return string $order_by_term SQL-friendly orderby term.
    648896         */
    649897        protected static function convert_orderby_to_order_by_term( $orderby ) {
Note: See TracChangeset for help on using the changeset viewer.