Skip to:
Content

BuddyPress.org

Changeset 8335


Ignore:
Timestamp:
05/01/2014 01:58:27 AM (10 years ago)
Author:
boonebgorges
Message:

Improved documentation in Members component. See #5022

Location:
trunk/bp-members
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-members/bp-members-screens.php

    r8119 r8335  
    44 * BuddyPress Member Screens
    55 *
    6  * Handlers for member screens that aren't handled elsewhere
     6 * Handlers for member screens that aren't handled elsewhere.
    77 *
    88 * @package BuddyPress
    … …  
    1414
    1515/**
    16  * Handles the display of the profile page by loading the correct template file.
    17  *
    18  * @package BuddyPress Members
    19  * @uses bp_core_load_template() Looks for and loads a template file within the current member theme (folder/filename)
     16 * Handle the display of the profile page by loading the correct template file.
    2017 */
    2118function bp_members_screen_display_profile() {
    … …  
    2522
    2623/**
    27  * Handles the display of the members directory index
    28  *
    29  * @global object $bp
    30  *
    31  * @uses bp_is_user()
    32  * @uses bp_is_current_component()
    33  * @uses do_action()
    34  * @uses bp_core_load_template()
    35  * @uses apply_filters()
     24 * Handle the display of the members directory index.
    3625 */
    3726function bp_members_screen_index() {
    … …  
    4635add_action( 'bp_screens', 'bp_members_screen_index' );
    4736
    48 
     37/**
     38 * Handle the loading of the signup screen.
     39 */
    4940function bp_core_screen_signup() {
    5041    global $bp;
    … …  
    221212add_action( 'bp_screens', 'bp_core_screen_signup' );
    222213
     214/**
     215 * Handle the loading of the Activate screen.
     216 */
    223217function bp_core_screen_activation() {
    224218    global $bp;
    … …  
    268262add_action( 'bp_screens', 'bp_core_screen_activation' );
    269263
    270 /** Theme Compatability *******************************************************/
     264/** Theme Compatibility *******************************************************/
    271265
    272266/**
    273267 * The main theme compat class for BuddyPress Members.
    274268 *
    275  * This class sets up the necessary theme compatability actions to safely output
     269 * This class sets up the necessary theme compatibility actions to safely output
    276270 * member template parts to the_title and the_content areas of a theme.
    277271 *
    278  * @since BuddyPress (1.7)
     272 * @since BuddyPress (1.7.0)
    279273 */
    280274class BP_Members_Theme_Compat {
    281275
    282276    /**
    283      * Setup the members component theme compatibility
    284      *
    285      * @since BuddyPress (1.7)
     277     * Set up the members component theme compatibility.
     278     *
     279     * @since BuddyPress (1.7.0)
    286280     */
    287281    public function __construct() {
    … …  
    290284
    291285    /**
    292      * Are we looking at something that needs members theme compatability?
    293      *
    294      * @since BuddyPress (1.7)
     286     * Are we looking at something that needs members theme compatibility?
     287     *
     288     * @since BuddyPress (1.7.0)
    295289     */
    296290    public function is_members() {
    … …  
    331325     * Add template hierarchy to theme compat for the members directory page.
    332326     *
    333      * This is to mirror how WordPress has {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
    334      *
    335      * @since BuddyPress (1.8)
    336      *
    337      * @param string $templates The templates from bp_get_theme_compat_templates()
     327     * This is to mirror how WordPress has
     328     * {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
     329     *
     330     * @since BuddyPress (1.8.0)
     331     *
     332     * @param string $templates The templates from bp_get_theme_compat_templates().
    338333     * @return array $templates Array of custom templates to look for.
    339334     */
    … …  
    353348
    354349    /**
    355      * Update the global $post with directory data
    356      *
    357      * @since BuddyPress (1.7)
     350     * Update the global $post with directory data.
     351     *
     352     * @since BuddyPress (1.7.0)
    358353     */
    359354    public function directory_dummy_post() {
    … …  
    372367
    373368    /**
    374      * Filter the_content with the members index template part
    375      *
    376      * @since BuddyPress (1.7)
     369     * Filter the_content with the members index template part.
     370     *
     371     * @since BuddyPress (1.7.0)
    377372     */
    378373    public function directory_content() {
    … …  
    385380     * Add custom template hierarchy to theme compat for member pages.
    386381     *
    387      * This is to mirror how WordPress has {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
    388      *
    389      * @since BuddyPress (1.8)
    390      *
    391      * @param string $templates The templates from bp_get_theme_compat_templates()
     382     * This is to mirror how WordPress has
     383     * {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
     384     *
     385     * @since BuddyPress (1.8.0)
     386     *
     387     * @param string $templates The templates from
     388     *        bp_get_theme_compat_templates().
    392389     * @return array $templates Array of custom templates to look for.
    393390     */
    … …  
    413410
    414411    /**
    415      * Update the global $post with the displayed user's data
    416      *
    417      * @since BuddyPress (1.7)
     412     * Update the global $post with the displayed user's data.
     413     *
     414     * @since BuddyPress (1.7.0)
    418415     */
    419416    public function single_dummy_post() {
    … …  
    432429
    433430    /**
    434      * Filter the_content with the members' single home template part
    435      *
    436      * @since BuddyPress (1.7)
     431     * Filter the_content with the members' single home template part.
     432     *
     433     * @since BuddyPress (1.7.0)
    437434     */
    438435    public function single_dummy_content() {
    … …  
    448445 * registration template parts to the_title and the_content areas of a theme.
    449446 *
    450  * @since BuddyPress (1.7)
     447 * @since BuddyPress (1.7.0)
    451448 */
    452449class BP_Registration_Theme_Compat {
    … …  
    455452     * Setup the groups component theme compatibility
    456453     *
    457      * @since BuddyPress (1.7)
     454     * @since BuddyPress (1.7.0)
    458455     */
    459456    public function __construct() {
    … …  
    464461     * Are we looking at either the registration or activation pages?
    465462     *
    466      * @since BuddyPress (1.7)
     463     * @since BuddyPress (1.7.0)
    467464     */
    468465    public function is_registration() {
    … …  
    485482
    486483    /**
    487      * Add template hierarchy to theme compat for registration / activation pages.
    488      *
    489      * This is to mirror how WordPress has {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
    490      *
    491      * @since BuddyPress (1.8)
    492      *
    493      * @param string $templates The templates from bp_get_theme_compat_templates()
     484     * Add template hierarchy to theme compat for registration/activation pages.
     485     *
     486     * This is to mirror how WordPress has
     487     * {@link https://codex.wordpress.org/Template_Hierarchy template hierarchy}.
     488     *
     489     * @since BuddyPress (1.8.0)
     490     *
     491     * @param string $templates The templates from bp_get_theme_compat_templates().
    494492     * @return array $templates Array of custom templates to look for.
    495493     */
    … …  
    510508
    511509    /**
    512      * Update the global $post with dummy data
    513      *
    514      * @since BuddyPress (1.7)
     510     * Update the global $post with dummy data.
     511     *
     512     * @since BuddyPress (1.7.0)
    515513     */
    516514    public function dummy_post() {
    … …  
    550548     * Filter the_content with either the register or activate templates.
    551549     *
    552      * @since BuddyPress (1.7)
     550     * @since BuddyPress (1.7.0)
    553551     */
    554552    public function dummy_content() {

  • trunk/bp-members/bp-members-template.php

    r8142 r8335  
    44 * BuddyPress Member Template Tags
    55 *
    6  * Functions that are safe to use inside your template files and themes
     6 * Functions that are safe to use inside your template files and themes.
    77 *
    88 * @package BuddyPress
    … …  
    1414
    1515/**
    16  * Output the members component slug
    17  *
    18  * @package BuddyPress
    19  * @subpackage Members Template
    20  * @since BuddyPress (1.5)
     16 * Output the members component slug.
     17 *
     18 * @since BuddyPress (1.5.0)
    2119 *
    2220 * @uses bp_get_members_slug()
    … …  
    2624}
    2725    /**
    28      * Return the members component slug
    29      *
    30      * @package BuddyPress
    31      * @subpackage Members Template
    32      * @since BuddyPress (1.5)
     26     * Return the members component slug.
     27     *
     28     * @since BuddyPress (1.5.0)
     29     *
     30     * @return string
    3331     */
    3432    function bp_get_members_slug() {
    … …  
    3735
    3836/**
    39  * Output the members component root slug
    40  *
    41  * @package BuddyPress
    42  * @subpackage Members Template
    43  * @since BuddyPress (1.5)
     37 * Output the members component root slug.
     38 *
     39 * @since BuddyPress (1.5.0)
    4440 *
    4541 * @uses bp_get_members_root_slug()
    … …  
    4945}
    5046    /**
    51      * Return the members component root slug
    52      *
    53      * @package BuddyPress
    54      * @subpackage Members Template
    55      * @since BuddyPress (1.5)
     47     * Return the members component root slug.
     48     *
     49     * @since BuddyPress (1.5.0)
     50     *
     51     * @return string
    5652     */
    5753    function bp_get_members_root_slug() {
    … …  
    6056
    6157/**
    62  * Output member directory permalink
    63  *
    64  * @package BuddyPress
    65  * @subpackage Members Template
    66  * @since BuddyPress (1.5)
     58 * Output member directory permalink.
     59 *
     60 * @since BuddyPress (1.5.0)
     61 *
    6762 * @uses bp_get_members_directory_permalink()
    6863 */
    … …  
    7166}
    7267    /**
    73      * Return member directory permalink
    74      *
    75      * @package BuddyPress
    76      * @subpackage Members Template
    77      * @since BuddyPress (1.5)
    78      * @uses apply_filters()
    79      * @uses traisingslashit()
    80      * @uses bp_get_root_domain()
    81      * @uses bp_get_members_root_slug()
     68     * Return member directory permalink.
     69     *
     70     * @since BuddyPress (1.5.0)
     71     *
    8272     * @return string
    8373     */
    … …  
    8777
    8878/**
    89  * Output the sign-up slug
    90  *
    91  * @package BuddyPress
    92  * @subpackage Members Template
    93  * @since BuddyPress (1.5)
     79 * Output the sign-up slug.
     80 *
     81 * @since BuddyPress (1.5.0)
    9482 *
    9583 * @uses bp_get_signup_slug()
    … …  
    9987}
    10088    /**
    101      * Return the sign-up slug
    102      *
    103      * @package BuddyPress
    104      * @subpackage Members Template
    105      * @since BuddyPress (1.5)
     89     * Return the sign-up slug.
     90     *
     91     * @since BuddyPress (1.5.0)
     92     *
     93     * @return string
    10694     */
    10795    function bp_get_signup_slug() {
    … …  
    120108
    121109/**
    122  * Output the activation slug
    123  *
    124  * @package BuddyPress
    125  * @subpackage Members Template
    126  * @since BuddyPress (1.5)
     110 * Output the activation slug.
     111 *
     112 * @since BuddyPress (1.5.0)
    127113 *
    128114 * @uses bp_get_activate_slug()
    … …  
    132118}
    133119    /**
    134      * Return the activation slug
    135      *
    136      * @package BuddyPress
    137      * @subpackage Members Template
    138      * @since BuddyPress (1.5)
     120     * Return the activation slug.
     121     *
     122     * @since BuddyPress (1.5.0)
     123     *
     124     * @return string
    139125     */
    140126    function bp_get_activate_slug() {
    … …  
    152138    }
    153139
    154 /***
    155  * Members template loop that will allow you to loop all members or friends of a member
    156  * if you pass a user_id.
    157  */
    158 
     140/**
     141 * The main member template loop class.
     142 *
     143 * Responsible for loading a group of members into a loop for display.
     144 */
    159145class BP_Core_Members_Template {
     146
     147    /**
     148     * The loop iterator.
     149     *
     150     * @access public
     151     * @var int
     152     */
    160153    var $current_member = -1;
     154
     155    /**
     156     * The number of members returned by the paged query.
     157     *
     158     * @access public
     159     * @var int
     160     */
    161161    var $member_count;
     162
     163    /**
     164     * Array of members located by the query.
     165     *
     166     * @access public
     167     * @var array
     168     */
    162169    var $members;
     170
     171    /**
     172     * The member object currently being iterated on.
     173     *
     174     * @access public
     175     * @var object
     176     */
    163177    var $member;
    164178
     179    /**
     180     * A flag for whether the loop is currently being iterated.
     181     *
     182     * @access public
     183     * @var bool
     184     */
    165185    var $in_the_loop;
    166186
     187    /**
     188     * The page number being requested.
     189     *
     190     * @access public
     191     * @var public
     192     */
    167193    var $pag_page;
     194
     195    /**
     196     * The number of items being requested per page.
     197     *
     198     * @access public
     199     * @var public
     200     */
    168201    var $pag_num;
     202
     203    /**
     204     * An HTML string containing pagination links.
     205     *
     206     * @access public
     207     * @var string
     208     */
    169209    var $pag_links;
     210
     211    /**
     212     * The total number of members matching the query parameters.
     213     *
     214     * @access public
     215     * @var int
     216     */
    170217    var $total_member_count;
    171218
     219    /**
     220     * Constructor method.
     221     *
     222     * @see BP_User_Query for an in-depth description of parameters.
     223     *
     224     * @param string $type Sort order.
     225     * @param int $page_number Page of results.
     226     * @param int $per_page Number of results per page.
     227     * @param int $max Max number of results to return.
     228     * @param int $user_id Limit to friends of a user.
     229     * @param string $search_terms Limit to users matching search terms.
     230     * @param array $include Limit results by these user IDs.
     231     * @param bool $populate_extras Fetch optional extras.
     232     * @param array $exclude Exclude these IDs from results.
     233     * @param array $meta_key Limit to users with a meta_key.
     234     * @param array $meta_value Limit to users with a meta_value (with meta_key).
     235     * @param array $page_arg Optional. The string used as a query
     236     *        parameter in pagination links. Default: 'upage'.
     237     */
    172238    function __construct( $type, $page_number, $per_page, $max, $user_id, $search_terms, $include, $populate_extras, $exclude, $meta_key, $meta_value, $page_arg = 'upage' ) {
    173239
    … …  
    211277    }
    212278
     279    /**
     280     * Whether there are members available in the loop.
     281     *
     282     * @see bp_has_members()
     283     *
     284     * @return bool True if there are items in the loop, otherwise false.
     285     */
    213286    function has_members() {
    214287        if ( $this->member_count )
    … …  
    218291    }
    219292
     293    /**
     294     * Set up the next member and iterate index.
     295     *
     296     * @return object The next member to iterate over.
     297     */
    220298    function next_member() {
    221299        $this->current_member++;
    … …  
    225303    }
    226304
     305    /**
     306     * Rewind the members and reset member index.
     307     */
    227308    function rewind_members() {
    228309        $this->current_member = -1;
    … …  
    232313    }
    233314
     315    /**
     316     * Whether there are members left in the loop to iterate over.
     317     *
     318     * This method is used by {@link bp_members()} as part of the while loop
     319     * that controls iteration inside the members loop, eg:
     320     *     while ( bp_members() ) { ...
     321     *
     322     * @see bp_members()
     323     *
     324     * @return bool True if there are more members to show, otherwise false.
     325     */
    234326    function members() {
    235327        if ( $this->current_member + 1 < $this->member_count ) {
    … …  
    245337    }
    246338
     339    /**
     340     * Set up the current member inside the loop.
     341     *
     342     * Used by {@link bp_the_member()} to set up the current member data
     343     * while looping, so that template tags used during that iteration make
     344     * reference to the current member.
     345     *
     346     * @see bp_the_member()
     347     */
    247348    function the_member() {
    248349
    … …  
    256357}
    257358
     359/**
     360 * Rewind the members and reset member index.
     361 */
    258362function bp_rewind_members() {
    259363    global $members_template;
    … …  
    262366}
    263367
     368/**
     369 * Initialize the members loop.
     370 *
     371 * Based on the $args passed, bp_has_members() populates the $members_template
     372 * global, enabling the use of BuddyPress templates and template functions to
     373 * display a list of members.
     374 *
     375 * @global object $members_template {@link BP_Members_Template}
     376 *
     377 * @param array $args {
     378 *     Arguments for limiting the contents of the members loop. Most arguments
     379 *     are in the same format as {@link BP_User_Query}. However, because
     380 *     the format of the arguments accepted here differs in a number of ways,
     381 *     and because bp_has_members() determines some default arguments in a
     382 *     dynamic fashion, we list all accepted arguments here as well.
     383 *
     384 *     Arguments can be passed as an associative array, or as a URL query
     385 *     string (eg, 'user_id=4&per_page=3').
     386 *
     387 *     @type int $type Sort order. 'active', 'random', 'newest', 'popular',
     388 *           'online', 'alphabetical'. Default: 'active'.
     389 *     @type int|bool $page Page of results to display. Default: 1.
     390 *     @type int|bool $per_page Number of results per page. Default: 20.
     391 *     @type int|bool $max Maximum number of results to return.
     392 *           Default: false (unlimited).
     393 *     @type string $page_arg The string used as a query parameter in
     394 *           pagination links. Default: 'bpage'.
     395 *     @type array|int|string|bool $include Limit results by a list of user
     396 *           IDs. Accepts an array, a single integer, a comma-separated list of
     397 *           IDs, or false (to disable this limiting). Default: false.
     398 *       'active', 'alphabetical', 'newest', or 'random'.
     399 *     @type array|int|string|bool $exclude Exclude users from results by ID.
     400 *           Accepts an array, a single integer, a comma-separated list of
     401 *           IDs, or false (to disable this limiting). Default: false.
     402 *     @type int $user_id If provided, results are limited to the friends of
     403 *           the specified user. When on a user's Friends page, defaults to
     404 *           the ID of the displayed user. Otherwise defaults to 0.
     405 *     @type string $search_terms Limit results by a search term. Default: null.
     406 *     @type string $meta_key Limit results by the presence of a usermeta key.
     407 *           Default: false.
     408 *     @type mixed $meta_value When used with meta_key, limits results by the
     409 *           a matching usermeta value. Default: false.
     410 *     @type bool $populate_extras Whether to fetch optional data, such as
     411 *           friend counts. Default: true.
     412 * }
     413 * @return bool Returns true when blogs are found, otherwise false.
     414 */
    264415function bp_has_members( $args = '' ) {
    265416    global $members_template;
    … …  
    320471}
    321472
     473/**
     474 * Set up the current member inside the loop.
     475 *
     476 * @return object
     477 */
    322478function bp_the_member() {
    323479    global $members_template;
    … …  
    325481}
    326482
     483/**
     484 * Check whether there are more members to iterate over.
     485 *
     486 * @return bool
     487 */
    327488function bp_members() {
    328489    global $members_template;
    … …  
    330491}
    331492
     493/**
     494 * Output the members pagination count.
     495 */
    332496function bp_members_pagination_count() {
    333497    echo bp_get_members_pagination_count();
    334498}
     499    /**
     500     * Generate the members pagination count.
     501     *
     502     * @return string
     503     */
    335504    function bp_get_members_pagination_count() {
    336505        global $members_template;
    … …  
    356525    }
    357526
     527/**
     528 * Output the members pagination links.
     529 */
    358530function bp_members_pagination_links() {
    359531    echo bp_get_members_pagination_links();
    360532}
     533    /**
     534     * Fetch the members pagination links.
     535     *
     536     * @return string
     537     */
    361538    function bp_get_members_pagination_links() {
    362539        global $members_template;
    … …  
    366543
    367544/**
    368  * bp_member_user_id()
    369  *
    370  * Echo id from bp_get_member_user_id()
     545 * Output the ID of the current member in the loop.
    371546 *
    372547 * @uses bp_get_member_user_id()
    … …  
    376551}
    377552    /**
    378      * bp_get_member_user_id()
    379      *
    380      * Get the id of the user in a members loop
    381      *
    382      * @global object $members_template
    383      * @return string Members id
     553     * Get the ID of the current member in the loop.
     554     *
     555     * @return string Member ID.
    384556     */
    385557    function bp_get_member_user_id() {
    … …  
    390562
    391563/**
    392  * Output the row class of a member
    393  *
    394  * @since BuddyPress (1.7)
     564 * Output the row class of the current member in the loop.
     565 *
     566 * @since BuddyPress (1.7.0)
    395567 */
    396568function bp_member_class() {
    … …  
    398570}
    399571    /**
    400      * Return the row class of a member
    401      *
    402      * @global BP_Core_Members_Template $members_template
    403      * @return string Row class of the member
    404      * @since BuddyPress (1.7)
     572     * Return the row class of the current member in the loop.
     573     *
     574     * @since BuddyPress (1.7.0)
     575     *
     576     * @return string Row class of the member.
    405577     */
    406578    function bp_get_member_class() {
    … …  
    431603
    432604/**
    433  * bp_member_user_nicename()
    434  *
    435  * Echo nicename from bp_get_member_user_nicename()
    436  *
    437  * @uses bp_get_member_user_nicename()
     605 * Output nicename of current member in the loop.
    438606 */
    439607function bp_member_user_nicename() {
    … …  
    441609}
    442610    /**
    443      * bp_get_member_user_nicename()
    444      *
    445      * Get the nicename of the user in a members loop
    446      *
    447      * @global object $members_template
    448      * @return string Members nicename
     611     * Get the nicename of the current member in the loop.
     612     *
     613     * @return string Members nicename.
    449614     */
    450615    function bp_get_member_user_nicename() {
    … …  
    454619
    455620/**
    456  * bp_member_user_login()
    457  *
    458  * Echo login from bp_get_member_user_login()
    459  *
    460  * @uses bp_get_member_user_login()
     621 * Output login for current member in the loop.
    461622 */
    462623function bp_member_user_login() {
    … …  
    464625}
    465626    /**
    466      * bp_get_member_user_login()
    467      *
    468      * Get the login of the user in a members loop
    469      *
    470      * @global object $members_template
    471      * @return string Members login
     627     * Get the login of the current member in the loop.
     628     *
     629     * @return string Member's login.
    472630     */
    473631    function bp_get_member_user_login() {
    … …  
    477635
    478636/**
    479  * bp_member_user_email()
    480  *
    481  * Echo email address from bp_get_member_user_email()
    482  *
    483  * @uses bp_get_member_user_email()
     637 * Output the email address for the current member in the loop.
    484638 */
    485639function bp_member_user_email() {
    … …  
    487641}
    488642    /**
    489      * bp_get_member_user_email()
    490      *
    491      * Get the email address of the user in a members loop
    492      *
    493      * @global object $members_template
    494      * @return string Members email address
     643     * Get the email address of the current member in the loop.
     644     *
     645     * @return string Member's email address.
    495646     */
    496647    function bp_get_member_user_email() {
    … …  
    499650    }
    500651
     652/**
     653 * Check whether the current member in the loop is the logged-in user.
     654 *
     655 * @return bool
     656 */
    501657function bp_member_is_loggedin_user() {
    502658    global $members_template;
    … …  
    504660}
    505661
     662/**
     663 * Output a member's avatar.
     664 *
     665 * @see bp_get_member_avatar() for description of arguments.
     666 *
     667 * @param array $args See {@link bp_get_member_avatar()}.
     668 */
    506669function bp_member_avatar( $args = '' ) {
    507670    echo apply_filters( 'bp_member_avatar', bp_get_member_avatar( $args ) );
    508671}
     672    /**
     673     * Get a member's avatar.
     674     *
     675     * @see bp_core_fetch_avatar() For a description of arguments and
     676     *      return values.
     677     *
     678     * @param array $args  {
     679     *     Arguments are listed here with an explanation of their defaults.
     680     *     For more information about the arguments, see
     681     *     {@link bp_core_fetch_avatar()}.
     682     *     @type string $alt Default: 'Profile picture of [user name]'.
     683     *     @type string $class Default: 'avatar'.
     684     *     @type string $type Default: 'thumb'.
     685     *     @type int|bool $width Default: false.
     686     *     @type int|bool $height Default: false.
     687     *     @type bool $id Currently unused.
     688     *     @type bool $no_grav Default: false.
     689     * }
     690     * @return string User avatar string.
     691     */
    509692    function bp_get_member_avatar( $args = '' ) {
    510693        global $members_template;
    … …  
    527710    }
    528711
     712/**
     713 * Output the permalink for the current member in the loop.
     714 */
    529715function bp_member_permalink() {
    530716    echo bp_get_member_permalink();
    531717}
     718    /**
     719     * Get the permalink for the current member in the loop.
     720     *
     721     * @return string
     722     */
    532723    function bp_get_member_permalink() {
    533724        global $members_template;
    … …  
    535726        return apply_filters( 'bp_get_member_permalink', bp_core_get_user_domain( $members_template->member->id, $members_template->member->user_nicename, $members_template->member->user_login ) );
    536727    }
     728
     729    /**
     730     * Alias of {@link bp_member_permalink()}.
     731     */
    537732    function bp_member_link() { echo bp_get_member_permalink(); }
     733
     734    /**
     735     * Alias of {@link bp_get_member_permalink()}.
     736     */
    538737    function bp_get_member_link() { return bp_get_member_permalink(); }
    539738
    540739/**
    541  * Echoes bp_get_member_name()
    542  *
    543  * @package BuddyPress
     740 * Output display name of current member in the loop.
    544741 */
    545742function bp_member_name() {
    … …  
    547744}
    548745    /**
    549      * Used inside a bp_has_members() loop, this function returns a user's full name
    550      *
    551      * Full name is, by default, pulled from xprofile's Full Name field. When this field is
    552      * empty, we try to get an alternative name from the WP users table, in the following order
    553      * of preference: display_name, user_nicename, user_login.
    554      *
    555      * @package BuddyPress
    556      *
    557      * @uses apply_filters() Filter bp_get_the_member_name() to alter the function's output
    558      * @return string The user's fullname for display
     746     * Get the display name of the current member in the loop.
     747     *
     748     * Full name is, by default, pulled from xprofile's Full Name field.
     749     * When this field is empty, we try to get an alternative name from the
     750     * WP users table, in the following order of preference: display_name,
     751     * user_nicename, user_login.
     752     *
     753     * @return string The user's fullname for display.
    559754     */
    560755    function bp_get_member_name() {
    … …  
    625820    }
    626821
     822/**
     823 * Output the latest update of the current member in the loop.
     824 */
    627825function bp_member_latest_update( $args = '' ) {
    628826    echo bp_get_member_latest_update( $args );
    629827}
     828    /**
     829     * Get the latest update from the current member in the loop.
     830     *
     831     * @param array $args {
     832     *     Array of optional arguments.
     833     *     @type int $length Truncation length. Default: 225.
     834     *     @type bool $view_link Whether to provide a 'View' link for
     835     *           truncated entries. Default: false.
     836     * }
     837     * @return string
     838     */
    630839    function bp_get_member_latest_update( $args = '' ) {
    631840        global $members_template;
    … …  
    730939    }
    731940
     941/**
     942 * Output the 'registered [x days ago]' string for the current member.
     943 */
    732944function bp_member_registered() {
    733945    echo bp_get_member_registered();
    734946}
     947    /**
     948     * Get the 'registered [x days ago]' string for the current member.
     949     *
     950     * @return string
     951     */
    735952    function bp_get_member_registered() {
    736953        global $members_template;
    … …  
    741958    }
    742959
     960/**
     961 * Output a random piece of profile data for the current member in the loop.
     962 */
    743963function bp_member_random_profile_data() {
    744964    global $members_template;
    … …  
    751971}
    752972
     973/**
     974 * Output hidden input for preserving member search params on form submit.
     975 */
    753976function bp_member_hidden_fields() {
    754977    if ( isset( $_REQUEST['s'] ) )
    … …  
    762985}
    763986
     987/**
     988 * Output the Members directory search form.
     989 */
    764990function bp_directory_members_search_form() {
    765991
    … …  
    7751001}
    7761002
     1003/**
     1004 * Output the total member count.
     1005 */
    7771006function bp_total_site_member_count() {
    7781007    echo bp_get_total_site_member_count();
    7791008}
     1009    /**
     1010     * Get the total site member count.
     1011     *
     1012     * @return int
     1013     */
    7801014    function bp_get_total_site_member_count() {
    7811015        return apply_filters( 'bp_get_total_site_member_count', bp_core_number_format( bp_core_get_total_member_count() ) );
    7821016    }
    7831017
    784 /** Navigation and other misc template tags **/
    785 
    786 /**
    787  * Uses the $bp->bp_nav global to render out the navigation within a BuddyPress install.
    788  * Each component adds to this navigation array within its own [component_name]setup_nav() function.
     1018/** Navigation and other misc template tags ***********************************/
     1019
     1020/**
     1021 * Render the navigation markup for the logged-in user.
     1022 *
     1023 * Each component adds to this navigation array within its own
     1024 * [component_name]setup_nav() function.
    7891025 *
    7901026 * This navigation array is the top level navigation, so it contains items such as:
    7911027 *      [Blog, Profile, Messages, Groups, Friends] ...
    7921028 *
    793  * The function will also analyze the current component the user is in, to determine whether
    794  * or not to highlight a particular nav item.
    795  *
    796  * @package BuddyPress Core
     1029 * The function will also analyze the current component the user is in, to
     1030 * determine whether or not to highlight a particular nav item.
     1031 *
    7971032 * @todo Move to a back-compat file?
    798  * @deprecated Does not seem to be called anywhere in the core
    799  * @global BuddyPress $bp The one true BuddyPress instance
     1033 * @deprecated Does not seem to be called anywhere in BP core.
    8001034 */
    8011035function bp_get_loggedin_user_nav() {
    … …  
    8391073
    8401074/**
    841  * Uses the $bp->bp_nav global to render out the user navigation when viewing another user other than
    842  * yourself.
    843  *
    844  * @package BuddyPress Core
    845  * @global BuddyPress $bp The one true BuddyPress instance
     1075 * Render the navigation markup for the displayed user.
    8461076 */
    8471077function bp_get_displayed_user_nav() {
    … …  
    8691099/** Avatars *******************************************************************/
    8701100
     1101/**
     1102 * Output the logged-in user's avatar.
     1103 *
     1104 * @see bp_get_loggedin_user_avatar() for a description of params.
     1105 */
    8711106function bp_loggedin_user_avatar( $args = '' ) {
    8721107    echo bp_get_loggedin_user_avatar( $args );
    8731108}
     1109    /**
     1110     * Get the logged-in user's avatar.
     1111     *
     1112     * @see bp_core_fetch_avatar() For a description of arguments and
     1113     *      return values.
     1114     *
     1115     * @param array $args  {
     1116     *     Arguments are listed here with an explanation of their defaults.
     1117     *     For more information about the arguments, see
     1118     *     {@link bp_core_fetch_avatar()}.
     1119     *     @type string $alt Default: 'Profile picture of [user name]'.
     1120     *     @type bool $html Default: true.
     1121     *     @type string $type Default: 'thumb'.
     1122     *     @type int|bool $width Default: false.
     1123     *     @type int|bool $height Default: false.
     1124     * }
     1125     * @return string User avatar string.
     1126     */
    8741127    function bp_get_loggedin_user_avatar( $args = '' ) {
    8751128
    … …  
    8881141    }
    8891142
     1143/**
     1144 * Output the displayed user's avatar.
     1145 *
     1146 * @see bp_get_displayed_user_avatar() for a description of params.
     1147 */
    8901148function bp_displayed_user_avatar( $args = '' ) {
    8911149    echo bp_get_displayed_user_avatar( $args );
    8921150}
     1151    /**
     1152     * Get the displayed user's avatar.
     1153     *
     1154     * @see bp_core_fetch_avatar() For a description of arguments and
     1155     *      return values.
     1156     *
     1157     * @param array $args  {
     1158     *     Arguments are listed here with an explanation of their defaults.
     1159     *     For more information about the arguments, see
     1160     *     {@link bp_core_fetch_avatar()}.
     1161     *     @type string $alt Default: 'Profile picture of [user name]'.
     1162     *     @type bool $html Default: true.
     1163     *     @type string $type Default: 'thumb'.
     1164     *     @type int|bool $width Default: false.
     1165     *     @type int|bool $height Default: false.
     1166     * }
     1167     * @return string User avatar string.
     1168     */
    8931169    function bp_get_displayed_user_avatar( $args = '' ) {
    8941170
    … …  
    9071183    }
    9081184
     1185/**
     1186 * Output the email address of the displayed user.
     1187 */
    9091188function bp_displayed_user_email() {
    9101189    echo bp_get_displayed_user_email();
    9111190}
     1191    /**
     1192     * Get the email address of the displayed user.
     1193     *
     1194     * @return string
     1195     */
    9121196    function bp_get_displayed_user_email() {
    9131197        global $bp;
    … …  
    9221206    }
    9231207
     1208/**
     1209 * Output the "active [x days ago]" string for a user.
     1210 *
     1211 * @see bp_get_last_activity() for a description of parameters.
     1212 *
     1213 * @param int $user_id See {@link bp_get_last_activity()}.
     1214 */
    9241215function bp_last_activity( $user_id = 0 ) {
    9251216    echo apply_filters( 'bp_last_activity', bp_get_last_activity( $user_id ) );
    9261217}
     1218    /**
     1219     * Get the "active [x days ago]" string for a user.
     1220     *
     1221     * @param int $user_id ID of the user. Default: displayed user ID.
     1222     * @return string
     1223     */
    9271224    function bp_get_last_activity( $user_id = 0 ) {
    9281225
    … …  
    9351232    }
    9361233
     1234/**
     1235 * Output the calculated first name of the displayed or logged-in user.
     1236 */
    9371237function bp_user_firstname() {
    9381238    echo bp_get_user_firstname();
    9391239}
     1240    /**
     1241     * Output the first name of a user.
     1242     *
     1243     * Simply takes all the characters before the first space in a name.
     1244     *
     1245     * @param string $name Full name to use when generating first name.
     1246     *        Defaults to displayed user's first name, or to logged-in
     1247     *        user's first name if it's unavailable.
     1248     * @return string
     1249     */
    9401250    function bp_get_user_firstname( $name = false ) {
    9411251
    … …  
    9531263    }
    9541264
     1265/**
     1266 * Output the link for the logged-in user's profile.
     1267 */
    9551268function bp_loggedin_user_link() {
    9561269    echo bp_get_loggedin_user_link();
    9571270}
     1271    /**
     1272     * Get the link for the logged-in user's profile.
     1273     *
     1274     * @return string
     1275     */
    9581276    function bp_get_loggedin_user_link() {
    9591277        return apply_filters( 'bp_get_loggedin_user_link', bp_loggedin_user_domain() );
    9601278    }
    9611279
     1280/**
     1281 * Output the link for the displayed user's profile.
     1282 */
    9621283function bp_displayed_user_link() {
    9631284    echo bp_get_displayed_user_link();
    9641285}
     1286    /**
     1287     * Get the link for the displayed user's profile.
     1288     *
     1289     * @return string
     1290     */
    9651291    function bp_get_displayed_user_link() {
    9661292        return apply_filters( 'bp_get_displayed_user_link', bp_displayed_user_domain() );
    9671293    }
    968     function bp_user_link() { bp_displayed_user_domain(); } // Deprecated.
    969 
     1294
     1295    /**
     1296     * Alias of {@link bp_displayed_user_domain()}.
     1297     *
     1298     * @deprecated
     1299     */
     1300    function bp_user_link() { bp_displayed_user_domain(); }
     1301
     1302/**
     1303 * Alias of {@link bp_displayed_user_id()}.
     1304 */
    9701305function bp_current_user_id() { return bp_displayed_user_id(); }
    9711306
     1307/**
     1308 * Generate the link for the displayed user's profile.
     1309 *
     1310 * @return string
     1311 */
    9721312function bp_displayed_user_domain() {
    9731313    global $bp;
    … …  
    9751315}
    9761316
     1317/**
     1318 * Generate the link for the logged-in user's profile.
     1319 *
     1320 * @return string
     1321 */
    9771322function bp_loggedin_user_domain() {
    9781323    global $bp;
    … …  
    9801325}
    9811326
     1327/**
     1328 * Output the displayed user's display name.
     1329 */
    9821330function bp_displayed_user_fullname() {
    9831331    echo bp_get_displayed_user_fullname();
    9841332}
     1333    /**
     1334     * Get the displayed user's display name.
     1335     *
     1336     * @return string
     1337     */
    9851338    function bp_get_displayed_user_fullname() {
    9861339        global $bp;
    9871340        return apply_filters( 'bp_displayed_user_fullname', isset( $bp->displayed_user->fullname ) ? $bp->displayed_user->fullname : '' );
    9881341    }
     1342
     1343    /**
     1344     * Alias of {@link bp_get_displayed_user_fullname()}.
     1345     */
    9891346    function bp_user_fullname() { echo bp_get_displayed_user_fullname(); }
    9901347
    9911348
     1349/**
     1350 * Output the logged-in user's display name.
     1351 */
    9921352function bp_loggedin_user_fullname() {
    9931353    echo bp_get_loggedin_user_fullname();
    9941354}
     1355    /**
     1356     * Get the logged-in user's display name.
     1357     *
     1358     * @return string
     1359     */
    9951360    function bp_get_loggedin_user_fullname() {
    9961361        global $bp;
    … …  
    9981363    }
    9991364
     1365/**
     1366 * Output the username of the displayed user.
     1367 */
    10001368function bp_displayed_user_username() {
    10011369    echo bp_get_displayed_user_username();
    10021370}
     1371    /**
     1372     * Get the username of the displayed user.
     1373     *
     1374     * @return string
     1375     */
    10031376    function bp_get_displayed_user_username() {
    10041377        global $bp;
    … …  
    10131386    }
    10141387
     1388/**
     1389 * Output the username of the logged-in user.
     1390 */
    10151391function bp_loggedin_user_username() {
    10161392    echo bp_get_loggedin_user_username();
    10171393}
     1394    /**
     1395     * Get the username of the logged-in user.
     1396     *
     1397     * @return string
     1398     */
    10181399    function bp_get_loggedin_user_username() {
    10191400        global $bp;
    … …  
    10331414 * Do we have a working custom sign up page?
    10341415 *
    1035  * @since BuddyPress (1.5)
    1036  *
    1037  * @uses bp_get_signup_slug() To make sure there is a slug assigned to the page
    1038  * @uses bp_locate_template() To make sure a template exists to provide output
    1039  * @return boolean True if page and template exist, false if not
     1416 * @since BuddyPress (1.5.0)
     1417 *
     1418 * @uses bp_get_signup_slug() To make sure there is a slug assigned to the page.
     1419 * @uses bp_locate_template() To make sure a template exists to provide output.
     1420 * @return bool True if page and template exist, false if not.
    10401421 */
    10411422function bp_has_custom_signup_page() {
    … …  
    10491430
    10501431/**
    1051  * Echoes the URL to the signup page
     1432 * Output the URL to the signup page.
    10521433 */
    10531434function bp_signup_page() {
    … …  
    10551436}
    10561437    /**
    1057      * Returns the URL to the signup page
     1438     * Get the URL to the signup page.
    10581439     *
    10591440     * @return string
    … …  
    10721453 * Do we have a working custom activation page?
    10731454 *
    1074  * @since BuddyPress (1.5)
    1075  *
    1076  * @uses bp_get_activate_slug() To make sure there is a slug assigned to the page
    1077  * @uses bp_locate_template() To make sure a template exists to provide output
    1078  * @return boolean True if page and template exist, false if not
     1455 * @since BuddyPress (1.5.0)
     1456 *
     1457 * @uses bp_get_activate_slug() To make sure there is a slug assigned to the page.
     1458 * @uses bp_locate_template() To make sure a template exists to provide output.
     1459 * @return boolean True if page and template exist, false if not.
    10791460 */
    10801461function bp_has_custom_activation_page() {
    … …  
    10871468}
    10881469
     1470/**
     1471 * Output the URL of the actvitation page.
     1472 */
    10891473function bp_activation_page() {
    10901474    echo bp_get_activation_page();
    10911475}
     1476    /**
     1477     * Get the URL of the activation page.
     1478     *
     1479     * @return string
     1480     */
    10921481    function bp_get_activation_page() {
    10931482        if ( bp_has_custom_activation_page() ) {
    … …  
    11001489    }
    11011490
     1491/**
     1492 * Output the username submitted during signup.
     1493 */
    11021494function bp_signup_username_value() {
    11031495    echo bp_get_signup_username_value();
    11041496}
     1497    /**
     1498     * Get the username submitted during signup.
     1499     *
     1500     * @todo This should be properly escaped.
     1501     *
     1502     * @return string
     1503     */
    11051504    function bp_get_signup_username_value() {
    11061505        $value = '';
    … …  
    11111510    }
    11121511
     1512/**
     1513 * Output the user email address submitted during signup.
     1514 */
    11131515function bp_signup_email_value() {
    11141516    echo bp_get_signup_email_value();
    11151517}
     1518    /**
     1519     * Get the email address submitted during signup.
     1520     *
     1521     * @todo This should be properly escaped.
     1522     *
     1523     * @return string
     1524     */
    11161525    function bp_get_signup_email_value() {
    11171526        $value = '';
    … …  
    11221531    }
    11231532
     1533/**
     1534 * Output the 'signup_with_blog' value submitted during signup.
     1535 */
    11241536function bp_signup_with_blog_value() {
    11251537    echo bp_get_signup_with_blog_value();
    11261538}
     1539    /**
     1540     * Get the 'signup_with_blog' value submitted during signup.
     1541     *
     1542     * @return string
     1543     */
    11271544    function bp_get_signup_with_blog_value() {
    11281545        $value = '';
    … …  
    11331550    }
    11341551
     1552/**
     1553 * Output the 'signup_blog_url' value submitted at signup.
     1554 */
    11351555function bp_signup_blog_url_value() {
    11361556    echo bp_get_signup_blog_url_value();
    11371557}
     1558    /**
     1559     * Get the 'signup_blog_url' value submitted at signup.
     1560     *
     1561     * @todo Should be properly escaped.
     1562     *
     1563     * @return string
     1564     */
    11381565    function bp_get_signup_blog_url_value() {
    11391566        $value = '';
    … …  
    11441571    }
    11451572
     1573/**
     1574 * Output the 'signup_blog_titl' value submitted at signup.
     1575 */
    11461576function bp_signup_blog_title_value() {
    11471577    echo bp_get_signup_blog_title_value();
    11481578}
     1579    /**
     1580     * Get the 'signup_blog_title' value submitted at signup.
     1581     *
     1582     * @todo Should be properly escaped.
     1583     *
     1584     * @return string
     1585     */
    11491586    function bp_get_signup_blog_title_value() {
    11501587        $value = '';
    … …  
    11551592    }
    11561593
     1594/**
     1595 * Output the 'signup_blog_privacy' value submitted at signup.
     1596 */
    11571597function bp_signup_blog_privacy_value() {
    11581598    echo bp_get_signup_blog_privacy_value();
    11591599}
     1600    /**
     1601     * Get the 'signup_blog_privacy' value submitted at signup.
     1602     *
     1603     * @todo Should be properly escaped.
     1604     *
     1605     * @return string
     1606     */
    11601607    function bp_get_signup_blog_privacy_value() {
    11611608        $value = '';
    … …  
    11661613    }
    11671614
     1615/**
     1616 * Output the avatar dir used during signup.
     1617 */
    11681618function bp_signup_avatar_dir_value() {
    11691619    echo bp_get_signup_avatar_dir_value();
    11701620}
     1621    /**
     1622     * Get the avatar dir used during signup.
     1623     *
     1624     * @return string
     1625     */
    11711626    function bp_get_signup_avatar_dir_value() {
    11721627        global $bp;
    … …  
    11871642    }
    11881643
     1644/**
     1645 * Output the current signup step.
     1646 */
    11891647function bp_current_signup_step() {
    11901648    echo bp_get_current_signup_step();
    11911649}
     1650    /**
     1651     * Get the current signup step.
     1652     *
     1653     * @return string
     1654     */
    11921655    function bp_get_current_signup_step() {
    11931656        global $bp;
    … …  
    11961659    }
    11971660
     1661/**
     1662 * Output the user avatar during signup.
     1663 *
     1664 * @see bp_get_signup_avatar() for description of arguments.
     1665 *
     1666 * @param array $args See {@link bp_get_signup_avatar(}.
     1667 */
    11981668function bp_signup_avatar( $args = '' ) {
    11991669    echo bp_get_signup_avatar( $args );
    12001670}
     1671    /**
     1672     * Get the user avatar during signup.
     1673     *
     1674     * @see bp_core_fetch_avatar() for description of arguments.
     1675     *
     1676     * @param array $args {
     1677     *     Array of optional arguments.
     1678     *     @type int $size Height/weight in pixels. Default: value of
     1679     *           bp_core_avatar_full_width().
     1680     *     @type string $class CSS class. Default: 'avatar'.
     1681     *     @type string $alt HTML 'alt' attribute. Default: 'Your Avatar'.
     1682     * }
     1683     * @return string
     1684     */
    12011685    function bp_get_signup_avatar( $args = '' ) {
    12021686        $bp = buddypress();
    … …  
    12441728    }
    12451729
     1730/**
     1731 * Output whether signup is allowed.
     1732 *
     1733 * @todo Remove this function. Echoing a bool is pointless.
     1734 */
    12461735function bp_signup_allowed() {
    12471736    echo bp_get_signup_allowed();
    12481737}
     1738    /**
     1739     * Is user signup allowed?
     1740     *
     1741     * @return bool
     1742     */
    12491743    function bp_get_signup_allowed() {
    12501744        global $bp;
    … …  
    12671761
    12681762/**
    1269  * Hook member activity feed to <head>
    1270  *
    1271  * @since BuddyPress (1.5)
     1763 * Hook member activity feed to <head>.
     1764 *
     1765 * @since BuddyPress (1.5.0)
    12721766 */
    12731767function bp_members_activity_feed() {
    … …  
    12811775add_action( 'bp_head', 'bp_members_activity_feed' );
    12821776
    1283 
     1777/**
     1778 * Output a link to a members component subpage.
     1779 *
     1780 * @see bp_get_members_component_link() for description of parameters.
     1781 *
     1782 * @param string $component See {@bp_get_members_component_link()}.
     1783 * @param string $action See {@bp_get_members_component_link()}.
     1784 * @param string $query_args See {@bp_get_members_component_link()}.
     1785 * @param string $nonce See {@bp_get_members_component_link()}.
     1786 */
    12841787function bp_members_component_link( $component, $action = '', $query_args = '', $nonce = false ) {
    12851788    echo bp_get_members_component_link( $component, $action, $query_args, $nonce );
    12861789}
     1790    /**
     1791     * Generate a link to a members component subpage.
     1792     *
     1793     * @param string $component ID of the component (eg 'friends').
     1794     * @param string $action Optional. 'action' slug (eg 'invites').
     1795     * @param array $query_args Optional. Array of URL params to add to the
     1796     *        URL. See {@link add_query_arg()} for format.
     1797     * @param array $nonce Optional. If provided, the URL will be passed
     1798     *        through wp_nonce_url() with $nonce as the action string.
     1799     * @return string
     1800     */
    12871801    function bp_get_members_component_link( $component, $action = '', $query_args = '', $nonce = false ) {
    12881802        global $bp;
Note: See TracChangeset for help on using the changeset viewer.