Skip to:
Content

BuddyPress.org

Changeset 7452


Ignore:
Timestamp:
10/22/2013 01:55:08 AM (11 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-core. See #5022

Location:
trunk/bp-core
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-core/bp-core-template-loader.php

    r7432 r7452  
    22
    33/**
    4  * BuddyPress Template Functions
     4 * BuddyPress Template Functions.
    55 *
    66 * This file contains functions necessary to mirror the WordPress core template
    … …  
    1616
    1717/**
    18  * Adds BuddyPress theme support to any active WordPress theme
    19  *
    20  * @since BuddyPress (1.7)
    21  *
    22  * @param string $slug
    23  * @param string $name Optional. Default null
     18 * Get a BuddyPress template part for display in a theme.
     19 *
     20 * @since BuddyPress (1.7.0)
     21 *
    2422 * @uses bp_locate_template()
    2523 * @uses load_template()
    2624 * @uses get_template_part()
     25 *
     26 * @param string $slug Template part slug. Used to generate filenames, eg
     27 *        'friends' for 'friends.php'.
     28 * @param string $name Optional. Template part name. Used to generate
     29 *        secondary filenames, eg 'personal' for 'activity-personal.php'.
     30 * @return string Path to located template. See {@link bp_locate_template()}.
    2731 */
    2832function bp_get_template_part( $slug, $name = null ) {
    … …  
    5155 * not found in either of those, it looks in the theme-compat folder last.
    5256 *
    53  * @since BuddyPress (1.7)
     57 * @since BuddyPress (1.7.0)
    5458 *
    5559 * @param string|array $template_names Template file(s) to search for, in order.
    56  * @param bool $load If true the template file will be loaded if it is found.
    57  * @param bool $require_once Whether to require_once or require. Default true.
    58  *                            Has no effect if $load is false.
     60 * @param bool $load Optional. If true, the template file will be loaded when
     61 *        found. If false, the path will be returned. Default: false.
     62 * @param bool $require_once Optional. Whether to require_once or require. Has
     63 *        no effect if $load is false. Default: true.
    5964 * @return string The template filename if one is located.
    6065 */
    … …  
    98103
    99104/**
    100  * This is really cool. This function registers a new template stack location,
    101  * using WordPress's built in filters API.
     105 * Register a new template stack location.
    102106 *
    103107 * This allows for templates to live in places beyond just the parent/child
    … …  
    105109 * with bp_locate_template(), this allows for easy template overrides.
    106110 *
    107  * @since BuddyPress (1.7)
    108  *
    109  * @param string $location Callback function that returns the stack location
    110  * @param int $priority
     111 * @since BuddyPress (1.7.0)
     112 *
     113 * @todo Make 'callable' instead of 'function'.
     114 *
     115 * @param string $location Callback function that returns the stack location.
     116 * @param int $priority Optional. The priority parameter as passed to
     117 *        add_filter(). Default: 10.
     118 * @return bool See {@link add_filter()}.
    111119 */
    112120function bp_register_template_stack( $location_callback = '', $priority = 10 ) {
    … …  
    121129
    122130/**
    123  * Deregisters a previously registered template stack location.
    124  *
    125  * @since BuddyPress (1.7)
    126  *
    127  * @param string $location Callback function that returns the stack location
    128  * @param int $priority
     131 * Deregister a previously registered template stack location.
     132 *
     133 * @since BuddyPress (1.7.0)
     134 *
    129135 * @see bp_register_template_stack()
     136 *
     137 * @param string $location Callback function that returns the stack location.
     138 * @param int $priority Optional. The priority parameter passed to
     139 *        {@link bp_register_template_stack()}. Default: 10.
     140 * @return bool See {@link remove_filter()}.
    130141 */
    131142function bp_deregister_template_stack( $location_callback = '', $priority = 10 ) {
    … …  
    140151
    141152/**
    142  * Call the functions added to the 'bp_template_stack' filter hook, and return
     153 * Get the "template stack", a list of registered directories where templates can be found.
     154 *
     155 * Calls the functions added to the 'bp_template_stack' filter hook, and return
    143156 * an array of the template locations.
    144157 *
    145158 * @see bp_register_template_stack()
    146159 *
    147  * @since BuddyPress (1.7)
    148  *
    149  * @global array $wp_filter Stores all of the filters
    150  * @global array $merged_filters Merges the filter hooks using this function.
    151  * @global array $wp_current_filter stores the list of current filters with the current one last
    152  *
     160 * @since BuddyPress (1.7.0)
     161 *
     162 * @global array $wp_filter Stores all of the filters.
     163 * @global array $merged_filters Merges the filter hooks using this function..
     164 * @global array $wp_current_filter stores the list of current filters with
     165 *         the current one last.
    153166 * @return array The filtered value after all hooked functions are applied to it.
    154167 */
    … …  
    192205
    193206/**
    194  * Get a template part in an output buffer, and return it
    195  *
    196  * @since BuddyPress (1.7)
    197  *
    198  * @param string $slug
    199  * @param string $name
    200  * @return string
     207 * Put a template part into an output buffer, and return it.
     208 *
     209 * @since BuddyPress (1.7.0)
     210 *
     211 * @see bp_get_template_part() for a description of $slug and $name params.
     212 *
     213 * @param string $slug See {@link bp_get_template_part()}.
     214 * @param string $name See {@link bp_get_template_part()}.
     215 * @param bool $echo If true, template content will be echoed. If false,
     216 *        returned. Default: true.
     217 * @return string|null If $echo, returns the template content.
    201218 */
    202219function bp_buffer_template_part( $slug, $name = null, $echo = true ) {
    … …  
    223240
    224241/**
    225  * Retrieve path to a template
     242 * Retrieve the path to a template.
    226243 *
    227244 * Used to quickly retrieve the path of a template without including the file
    … …  
    230247 * locations without the use of the other get_*_template() functions.
    231248 *
    232  * @since BuddyPress (1.7)
    233  *
    234  * @param string $type Filename without extension.
    235  * @param array $templates An optional list of template candidates
     249 * @since BuddyPress (1.7.0)
     250 *
    236251 * @uses bp_set_theme_compat_templates()
    237252 * @uses bp_locate_template()
    238253 * @uses bp_set_theme_compat_template()
     254 *
     255 * @param string $type Filename without extension.
     256 * @param array $templates An optional list of template candidates.
    239257 * @return string Full path to file.
    240258 */
    … …  
    272290
    273291/**
    274  * Add template locations to template files being searched for
    275  *
    276  * @since BuddyPress (1.7)
    277  *
    278  * @param array $stacks
    279  * @return array()
     292 * Add template locations to template files being searched for.
     293 *
     294 * @since BuddyPress (1.7.0)
     295 *
     296 * @param array $stacks Array of template locations.
     297 * @return array() Array of all template locations registered so far.
    280298 */
    281299function bp_add_template_stack_locations( $stacks = array() ) {
    … …  
    294312
    295313/**
    296  * Add checks for BuddyPress conditions to parse_query action
    297  *
    298  * @since BuddyPress (1.7)
     314 * Add checks for BuddyPress conditions to 'parse_query' action.
     315 *
     316 * @since BuddyPress (1.7.0)
    299317 *
    300318 * @param WP_Query $posts_query
    … …  
    319337
    320338/**
    321  * Possibly intercept the template being loaded
     339 * Possibly intercept the template being loaded.
    322340 *
    323341 * Listens to the 'template_include' filter and waits for any BuddyPress specific
    … …  
    328346 * from being stomped on accident.
    329347 *
    330  * @since BuddyPress (1.7)
     348 * @since BuddyPress (1.7.0)
    331349 *
    332350 * @param string $template
    333  *
    334  * @return string The path to the template file that is being used
     351 * @return string The path to the template file that is being used.
    335352 */
    336353function bp_template_include_theme_supports( $template = '' ) {
    … …  
    349366
    350367/**
    351  * Set the included template
    352  *
    353  * @since BuddyPress (1.8)
    354  * @param mixed $template Default false
    355  * @return mixed False if empty. Template name if template included
     368 * Set the included template.
     369 *
     370 * @since BuddyPress (1.8.0)
     371 *
     372 * @param mixed $template Default: false.
     373 * @return mixed False if empty. Template name if template included.
    356374 */
    357375function bp_set_template_included( $template = false ) {
    … …  
    364382 * Is a BuddyPress template being included?
    365383 *
    366  * @since BuddyPress (1.8)
    367  * @return bool True if yes, false if no
     384 * @since BuddyPress (1.8.0)
     385 * @return bool True if yes, false if no.
    368386 */
    369387function bp_is_template_included() {
    … …  
    372390
    373391/**
    374  * Attempt to load a custom BuddyPress functions file, similar to each themes
    375  * functions.php file.
    376  *
    377  * @since BuddyPress (1.7)
     392 * Attempt to load a custom BP functions file, similar to each themes functions.php file.
     393 *
     394 * @since BuddyPress (1.7.0)
    378395 *
    379396 * @global string $pagenow
    … …  
    399416
    400417/**
    401  * Get the templates to use as the endpoint for BuddyPress template parts
    402  *
    403  * @since BuddyPress (1.7)
    404  *
    405  * @uses apply_filters()
    406  * @return array Of possible root level wrapper template files
     418 * Get the templates to use as the endpoint for BuddyPress template parts.
     419 *
     420 * @since BuddyPress (1.7.0)
     421 *
     422 * @return array Array of possible root level wrapper template files.
    407423 */
    408424function bp_get_theme_compat_templates() {

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

    r7366 r7452  
    1111
    1212/**
    13  * Uses the $bp->bp_options_nav global to render out the sub navigation for the current component.
    14  * Each component adds to its sub navigation array within its own setup_nav() function.
    15  *
    16  * This sub navigation array is the secondary level navigation, so for profile it contains:
     13 * Output the "options nav", the secondary-level single item navigation menu.
     14 *
     15 * Uses the $bp->bp_options_nav global to render out the sub navigation for the
     16 * current component. Each component adds to its sub navigation array within
     17 * its own setup_nav() function.
     18 *
     19 * This sub navigation array is the secondary level navigation, so for profile
     20 * it contains:
    1721 *      [Public, Edit Profile, Change Avatar]
    1822 *
    19  * The function will also analyze the current action for the current component to determine whether
    20  * or not to highlight a particular sub nav item.
    21  *
    22  * @package BuddyPress Core
    23  * @global BuddyPress $bp The one true BuddyPress instance
    24  * @uses bp_get_user_nav() Renders the navigation for a profile of a currently viewed user.
     23 * The function will also analyze the current action for the current component
     24 * to determine whether or not to highlight a particular sub nav item.
     25 *
     26 * @global BuddyPress $bp The one true BuddyPress instance.
     27 * @uses bp_get_user_nav() Renders the navigation for a profile of a currently
     28 *       viewed user.
    2529 */
    2630function bp_get_options_nav() {
    … …  
    6569}
    6670
     71/**
     72 * Get the 'bp_options_title' property from the BP global.
     73 *
     74 * Not currently used in BuddyPress.
     75 * @todo Deprecate.
     76 */
    6777function bp_get_options_title() {
    6878    global $bp;
    … …  
    7787
    7888/**
    79  * Check to see if there is an options avatar. An options avatar is an avatar for something
    80  * like a group, or a friend. Basically an avatar that appears in the sub nav options bar.
    81  *
    82  * @package BuddyPress Core
    83  * @global BuddyPress $bp The one true BuddyPress instance
     89 * Check to see if there is an options avatar.
     90 *
     91 * An options avatar is an avatar for something like a group, or a friend.
     92 * Basically an avatar that appears in the sub nav options bar.
     93 *
     94 * Not currently used in BuddyPress.
     95 *
     96 * @global BuddyPress $bp The one true BuddyPress instance.
     97 * @todo Deprecate.
     98 *
     99 * @return bool Returns true if an options avatar has been set, otherwise
     100 *         false.
    84101 */
    85102function bp_has_options_avatar() {
    … …  
    92109}
    93110
     111/**
     112 * Output the options avatar.
     113 *
     114 * Not currently used in BuddyPress.
     115 *
     116 * @todo Deprecate.
     117 */
    94118function bp_get_options_avatar() {
    95119    global $bp;
    … …  
    98122}
    99123
     124/**
     125 * Output a comment author's avatar.
     126 *
     127 * Not currently used in BuddyPress.
     128 *
     129 * @todo Deprecate.
     130 */
    100131function bp_comment_author_avatar() {
    101132    global $comment;
    … …  
    107138}
    108139
     140/**
     141 * Output a post author's avatar.
     142 *
     143 * Not currently used in BuddyPress.
     144 *
     145 * @todo Deprecate.
     146 */
    109147function bp_post_author_avatar() {
    110148    global $post;
    … …  
    116154}
    117155
     156/**
     157 * Output the current avatar upload step.
     158 */
    118159function bp_avatar_admin_step() {
    119160    echo bp_get_avatar_admin_step();
    120161}
     162    /**
     163     * Return the current avatar upload step.
     164     *
     165     * @return string The current avatar upload step. Returns 'upload-image'
     166     *         if none is found.
     167     */
    121168    function bp_get_avatar_admin_step() {
    122169        global $bp;
    … …  
    130177    }
    131178
     179/**
     180 * Output the URL of the avatar to crop.
     181 */
    132182function bp_avatar_to_crop() {
    133183    echo bp_get_avatar_to_crop();
    134184}
     185    /**
     186     * Return the URL of the avatar to crop.
     187     *
     188     * @return string URL of the avatar awaiting cropping.
     189     */
    135190    function bp_get_avatar_to_crop() {
    136191        global $bp;
    … …  
    144199    }
    145200
     201/**
     202 * Output the relative file path to the avatar to crop.
     203 */
    146204function bp_avatar_to_crop_src() {
    147205    echo bp_get_avatar_to_crop_src();
    148206}
     207    /**
     208     * Return the relative file path to the avatar to crop.
     209     *
     210     * @return string Relative file path to the avatar.
     211     */
    149212    function bp_get_avatar_to_crop_src() {
    150213        global $bp;
    … …  
    153216    }
    154217
     218/**
     219 * Output the avatar cropper <img> markup.
     220 *
     221 * No longer used in BuddyPress.
     222 *
     223 * @todo Deprecate.
     224 */
    155225function bp_avatar_cropper() {
    156226    global $bp;
    … …  
    160230
    161231/**
    162  * Echoes bp_get_site_name()
     232 * Output the name of the BP site. Used in RSS headers.
    163233 */
    164234function bp_site_name() {
    … …  
    166236}
    167237    /**
    168      * Returns the name of the BP site. Used in RSS headers
     238     * Returns the name of the BP site. Used in RSS headers.
    169239     *
    170      * @since BuddyPress (1.6)
     240     * @since BuddyPress (1.6.0)
    171241     */
    172242    function bp_get_site_name() {
    … …  
    174244    }
    175245
     246/**
     247 * Format a date.
     248 *
     249 * @param int $time The UNIX timestamp to be formatted.
     250 * @param bool $just_date Optional. True to return only the month + day, false
     251 *        to return month, day, and time. Default: false.
     252 * @param bool $localize_time Optional. True to display in local time, false to
     253 *        leave in GMT. Default: true.
     254 * @return string|bool $localize_time Optional. A string representation of
     255 *         $time, in the format "January 1, 2010 at 9:50pm" (or whatever your
     256 *         'date_format' and 'time_format' settings are). False on failure.
     257 */
    176258function bp_format_time( $time, $just_date = false, $localize_time = true ) {
    177259    if ( !isset( $time ) || !is_numeric( $time ) )
    … …  
    201283}
    202284
     285/**
     286 * Select between two dynamic strings, according to context.
     287 *
     288 * This function can be used in cases where a phrase used in a template will
     289 * differ for a user looking at his own profile and a user looking at another
     290 * user's profile (eg, "My Friends" and "Joe's Friends"). Pass both versions
     291 * of the phrase, and bp_word_or_name() will detect which is appropriate, and
     292 * do the necessary argument swapping for dynamic phrases.
     293 *
     294 * @param string $youtext The "you" version of the phrase (eg "Your Friends").
     295 * @param string $nametext The other-user version of the phrase. Should be in
     296 *        a format appropriate for sprintf() - use %s in place of the displayed
     297 *        user's name (eg "%'s Friends").
     298 * @param bool $capitalize Optional. Force into title case. Default: true.
     299 * @param bool $echo Optional. True to echo the results, false to return them.
     300 *        Default: true.
     301 * @return string|null If ! $echo, returns the appropriate string.
     302 */
    203303function bp_word_or_name( $youtext, $nametext, $capitalize = true, $echo = true ) {
    204304
    … …  
    224324}
    225325
    226 
     326/**
     327 * Do the 'bp_styles' action, and call wp_print_styles().
     328 *
     329 * No longer used in BuddyPress.
     330 *
     331 * @todo Deprecate.
     332 */
    227333function bp_styles() {
    228334    do_action( 'bp_styles' );
    … …  
    232338/** Search Form ***************************************************************/
    233339
     340/**
     341 * Return the "action" attribute for search forms.
     342 *
     343 * @return string URL action attribute for search forms, eg example.com/search/.
     344 */
    234345function bp_search_form_action() {
    235346    return apply_filters( 'bp_search_form_action', trailingslashit( bp_get_root_domain() . '/' . bp_get_search_slug() ) );
    … …  
    237348
    238349/**
    239  * Generates the basic search form as used in BP-Default's header.
    240  *
    241  * @return string HTML <select> element
    242  * @since BuddyPress (1.0)
     350 * Generate the basic search form as used in BP-Default's header.
     351 *
     352 * @since BuddyPress (1.0.0)
     353 *
     354 * @return string HTML <select> element.
    243355 */
    244356function bp_search_form_type_select() {
    … …  
    274386
    275387/**
    276  * Get the default text for the search box for a given component.
    277  *
    278  * @global object $bp BuddyPress global settings
    279  * @return string
    280  * @since BuddyPress (1.5)
     388 * Output the default text for the search box for a given component.
     389 *
     390 * @since BuddyPress (1.5.0)
     391 *
     392 * @see bp_get_search_default_text()
     393 *
     394 * @param string $component See {@link bp_get_search_default_text()}.
    281395 */
    282396function bp_search_default_text( $component = '' ) {
    283397    echo bp_get_search_default_text( $component );
    284398}
     399    /**
     400     * Return the default text for the search box for a given component.
     401     *
     402     * @since BuddyPress (1.5.0)
     403     *
     404     * @param string $component Component name. Default: current component.
     405     * @return string Placeholder text for search field.
     406     */
    285407    function bp_get_search_default_text( $component = '' ) {
    286408        global $bp;
    … …  
    309431    }
    310432
     433/**
     434 * Fire the 'bp_custom_profile_boxes' action.
     435 *
     436 * No longer used in BuddyPress.
     437 *
     438 * @todo Deprecate.
     439 */
    311440function bp_custom_profile_boxes() {
    312441    do_action( 'bp_custom_profile_boxes' );
    313442}
    314443
     444/**
     445 * Fire the 'bp_custom_profile_sidebar_boxes' action.
     446 *
     447 * No longer used in BuddyPress.
     448 *
     449 * @todo Deprecate.
     450 */
    315451function bp_custom_profile_sidebar_boxes() {
    316452    do_action( 'bp_custom_profile_sidebar_boxes' );
    … …  
    318454
    319455/**
    320  * Creates and outputs a button.
    321  *
    322  * @param array $args See bp_get_button() for the list of arguments.
     456 * Create and output a button.
     457 *
    323458 * @see bp_get_button()
     459 *
     460 * @param array $args See {@link BP_Button}.
    324461 */
    325462function bp_button( $args = '' ) {
    … …  
    327464}
    328465    /**
    329      * Creates and returns a button.
     466     * Create and return a button.
    330467     *
    331      * Args:
    332      * component: Which component this button is for
    333      * must_be_logged_in: Button only appears for logged in users
    334      * block_self: Button will not appear when viewing your own profile.
    335      * wrapper: div|span|p|li|
    336      * wrapper_id: The DOM ID of the button wrapper
    337      * wrapper_class: The DOM class of the button wrapper
    338      * link_href: The destination link of the button
    339      * link_title: Title of the button
    340      * link_id: The DOM ID of the button
    341      * link_class: The DOM class of the button
    342      * link_rel: The DOM rel of the button
    343      * link_text: The contents of the button
     468     * @see BP_Button for a description of arguments and return value.
    344469     *
    345      * @param array $button
    346      * @return string
    347      * @see bp_add_friend_button()
    348      * @see bp_send_public_message_button()
    349      * @see bp_send_private_message_button()
     470     * @param array $args See {@link BP_Button}.
     471     * @return string HTML markup for the button.
    350472     */
    351473    function bp_get_button( $args = '' ) {
    … …  
    354476    }
    355477
    356 
    357 /**
    358  * Truncates text.
     478/**
     479 * Truncate text.
    359480 *
    360481 * Cuts a string to the length of $length and replaces the last characters
    … …  
    371492 * - `filter_shortcodes` If true, shortcodes will be stripped before truncating
    372493 *
    373  * @package BuddyPress
    374  *
    375  * @param string  $text String to truncate.
    376  * @param integer $length Length of returned string, including ellipsis.
    377  * @param array $options An array of html attributes and options.
     494 * @param string $text String to truncate.
     495 * @param int $length Optional. Length of returned string, including ellipsis.
     496 *        Default: 225.
     497 * @param array $options {
     498 *     An array of HTML attributes and options. Each item is optional.
     499 *     @type string $ending The string used after truncation.
     500 *           Default: ' [&hellip;]'.
     501 *     @type bool $exact If true, $text will be trimmed to exactly $length.
     502 *           If false, $text will not be cut mid-word. Default: false.
     503 *     @type bool $html If true, don't include HTML tags when calculating
     504 *           excerpt length. Default: true.
     505 *     @type bool $filter_shortcodes If true, shortcodes will be stripped.
     506 *           Default: true.
     507 * }
    378508 * @return string Trimmed string.
    379509 */
    … …  
    496626
    497627/**
    498  * Echoes the output of bp_get_total_member_count()
     628 * Output the total member count for the site.
    499629 */
    500630function bp_total_member_count() {
    … …  
    502632}
    503633    /**
    504      * Returns the total member count in your BP instance
     634     * Return the total member count in your BP instance.
    505635     *
    506      * Since BuddyPress 1.6, this function has used bp_core_get_active_member_count(), which
    507      * counts non-spam, non-deleted users who have last_activity. This value will correctly
    508      * match the total member count number used for pagination on member directories.
     636     * Since BuddyPress 1.6, this function has used bp_core_get_active_member_count(),
     637     * which counts non-spam, non-deleted users who have last_activity.
     638     * This value will correctly match the total member count number used
     639     * for pagination on member directories.
    509640     *
    510      * Before BuddyPress 1.6, this function used bp_core_get_total_member_count(), which did
    511      * not take into account last_activity, and thus often resulted in higher counts than
    512      * shown by member directory pagination.
     641     * Before BuddyPress 1.6, this function used bp_core_get_total_member_count(),
     642     * which did not take into account last_activity, and thus often
     643     * resulted in higher counts than shown by member directory pagination.
     644     *
     645     * @return int Member count.
    513646     */
    514647    function bp_get_total_member_count() {
    … …  
    517650    add_filter( 'bp_get_total_member_count', 'bp_core_number_format' );
    518651
     652/**
     653 * Output whether blog signup is allowed.
     654 *
     655 * @todo Deprecate. It doesn't make any sense to echo a boolean.
     656 */
    519657function bp_blog_signup_allowed() {
    520658    echo bp_get_blog_signup_allowed();
    521659}
     660    /**
     661     * Is blog signup allowed?
     662     *
     663     * Returns true if is_multisite() and blog creation is enabled at
     664     * Network Admin > Settings.
     665     *
     666     * @return bool True if blog signup is allowed, otherwise false.
     667     */
    522668    function bp_get_blog_signup_allowed() {
    523669        global $bp;
    … …  
    533679    }
    534680
     681/**
     682 * Check whether an activation has just been completed.
     683 *
     684 * @return bool True if the activation_complete global flag has been set,
     685 *         otherwise false.
     686 */
    535687function bp_account_was_activated() {
    536688    global $bp;
    … …  
    541693}
    542694
     695/**
     696 * Check whether registrations require activation on this installation.
     697 *
     698 * On a normal BuddyPress installation, all registrations require email
     699 * activation. This filter exists so that customizations that omit activation
     700 * can remove certain notification text from the registration screen.
     701 *
     702 * @return bool True by default.
     703 */
    543704function bp_registration_needs_activation() {
    544705    return apply_filters( 'bp_registration_needs_activation', true );
    … …  
    546707
    547708/**
    548  * Retrieve a client friendly version of the root blog name, plus take care of
    549  * the typical formatting bits and bobs.
     709 * Retrieve a client friendly version of the root blog name.
    550710 *
    551711 * The blogname option is escaped with esc_html on the way into the database in
    552712 * sanitize_option, we want to reverse this for the plain text arena of emails.
    553713 *
    554  * @link http://buddypress.trac.wordpress.org/ticket/4401
    555  * @since BuddyPress (1.7)
    556  * @return string
     714 * @since BuddyPress (1.7.0)
     715 *
     716 * @see http://buddypress.trac.wordpress.org/ticket/4401
     717 *
     718 * @param array $args {
     719 *     Array of optional parameters.
     720 *     @type string $before String to appear before the site name in the
     721 *           email subject. Default: '['.
     722 *     @type string $after String to appear after the site name in the
     723 *           email subject. Default: ']'.
     724 *     @type string $default The default site name, to be used when none is
     725 *           found in the database. Default: 'Community'.
     726 *     @type string $text Text to append to the site name (ie, the main text of
     727 *           the email subject).
     728 * }
     729 * @return string Sanitized email subject.
    557730 */
    558731function bp_get_email_subject( $args = array() ) {
    … …  
    571744
    572745/**
    573  * Allow templates to pass parameters directly into the template loops via AJAX
    574  *
    575  * For the most part this will be filtered in a theme's functions.php for example
    576  * in the default theme it is filtered via bp_dtheme_ajax_querystring()
    577  *
    578  * By using this template tag in the templates it will stop them from showing errors
    579  * if someone copies the templates from the default theme into another WordPress theme
    580  * without coping the functions from functions.php.
     746 * Allow templates to pass parameters directly into the template loops via AJAX.
     747 *
     748 * For the most part this will be filtered in a theme's functions.php for
     749 * example in the default theme it is filtered via bp_dtheme_ajax_querystring().
     750 *
     751 * By using this template tag in the templates it will stop them from showing
     752 * errors if someone copies the templates from the default theme into another
     753 * WordPress theme without coping the functions from functions.php.
     754 *
     755 * @param string $object
     756 * @return string The AJAX querystring.
    581757 */
    582758function bp_ajax_querystring( $object = false ) {
    … …  
    591767/** Template Classes and _is functions ****************************************/
    592768
     769/**
     770 * Return the name of the current component.
     771 *
     772 * @return string Component name.
     773 */
    593774function bp_current_component() {
    594775    global $bp;
    … …  
    597778}
    598779
     780/**
     781 * Return the name of the current action.
     782 *
     783 * @return string Action name.
     784 */
    599785function bp_current_action() {
    600786    global $bp;
    … …  
    603789}
    604790
     791/**
     792 * Return the name of the current item.
     793 *
     794 * @return unknown
     795 */
    605796function bp_current_item() {
    606797    global $bp;
    … …  
    610801
    611802/**
    612  * Return the value of $bp->action_variables
    613  *
    614  * @package BuddyPress
    615  *
    616  * @param mixed $action_variables The action variables array, or false if the array is empty
     803 * Return the value of $bp->action_variables.
     804 *
     805 * @return array|bool $action_variables The action variables array, or false
     806 *         if the array is empty.
    617807 */
    618808function bp_action_variables() {
    … …  
    623813
    624814/**
    625  * Return the value of a given action variable
    626  *
    627  * @package BuddyPress
    628  * @since BuddyPress (1.5)
    629  *
    630  * @param int $position The key of the action_variables array that you want
    631  * @return string $action_variable The value of that position in the array
     815 * Return the value of a given action variable.
     816 *
     817 * @since BuddyPress (1.5.0)
     818 *
     819 * @param int $position The key of the action_variables array that you want.
     820 * @return string|bool $action_variable The value of that position in the
     821 *         array, or false if not found.
    632822 */
    633823function bp_action_variable( $position = 0 ) {
    … …  
    638828}
    639829
     830/**
     831 * Output the "root domain", the URL of the BP root blog.
     832 */
    640833function bp_root_domain() {
    641834    echo bp_get_root_domain();
    642835}
     836    /**
     837     * Return the "root domain", the URL of the BP root blog.
     838     *
     839     * @return string URL of the BP root blog.
     840     */
    643841    function bp_get_root_domain() {
    644842        global $bp;
    … …  
    655853
    656854/**
    657  * Echoes the output of bp_get_root_slug()
    658  *
    659  * @package BuddyPress Core
    660  * @since BuddyPress (1.5)
     855 * Output the root slug for a given component.
     856 *
     857 * @since BuddyPress (1.5.0)
     858 *
     859 * @param string $component The component name.
    661860 */
    662861function bp_root_slug( $component = '' ) {
    … …  
    664863}
    665864    /**
    666      * Gets the root slug for a component slug
     865     * Get the root slug for given component.
    667866     *
    668      * In order to maintain backward compatibility, the following procedure is used:
     867     * The "root slug" is the string used when concatenating component
     868     * directory URLs. For example, on an installation where the Groups
     869     * component's directory is located at http://example.com/groups/, the
     870     * root slug for the Groups component is 'groups'. This string
     871     * generally corresponds to page_name of the component's directory
     872     * page.
     873     *
     874     * In order to maintain backward compatibility, the following procedure
     875     * is used:
    669876     * 1) Use the short slug to get the canonical component name from the
    670877     *    active component array
    671      * 2) Use the component name to get the root slug out of the appropriate part of the $bp
    672      *    global
    673      * 3) If nothing turns up, it probably means that $component is itself a root slug
     878     * 2) Use the component name to get the root slug out of the
     879     *    appropriate part of the $bp global
     880     * 3) If nothing turns up, it probably means that $component is itself
     881     *    a root slug
    674882     *
    675      * Example: If your groups directory is at /community/companies, this function first uses
    676      * the short slug 'companies' (ie the current component) to look up the canonical name
    677      * 'groups' in $bp->active_components. Then it uses 'groups' to get the root slug, from
    678      * $bp->groups->root_slug.
     883     * Example: If your groups directory is at /community/companies, this
     884     * function first uses the short slug 'companies' (ie the current
     885     * component) to look up the canonical name 'groups' in
     886     * $bp->active_components. Then it uses 'groups' to get the root slug,
     887     * from $bp->groups->root_slug.
    679888     *
    680      * @package BuddyPress Core
    681      * @since BuddyPress (1.5)
     889     * @since BuddyPress (1.5.0)
    682890     *
    683      * @global BuddyPress $bp The one true BuddyPress instance
    684      * @param string $component Optional. Defaults to the current component
    685      * @return string $root_slug The root slug
     891     * @global BuddyPress $bp The one true BuddyPress instance.
     892     *
     893     * @param string $component Optional. Defaults to the current component.
     894     * @return string $root_slug The root slug.
    686895     */
    687896    function bp_get_root_slug( $component = '' ) {
    … …  
    714923
    715924/**
    716  * Return the component name based on the current root slug
    717  *
    718  * @since BuddyPress (1.5)
    719  * @global BuddyPress $bp The one true BuddyPress instance
    720  * @param string $root_slug Needle to our active component haystack
    721  * @return mixed False if none found, component name if found
     925 * Return the component name based on a root slug.
     926 *
     927 * @since BuddyPress (1.5.0)
     928 *
     929 * @global BuddyPress $bp The one true BuddyPress instance.
     930 *
     931 * @param string $root_slug Needle to our active component haystack.
     932 * @return mixed False if none found, component name if found.
    722933 */
    723934function bp_get_name_from_root_slug( $root_slug = '' ) {
    … …  
    749960
    750961/**
    751  * Output the search slug
    752  *
    753  * @package BuddyPress
    754  * @since BuddyPress (1.5)
     962 * Output the search slug.
     963 *
     964 * @since BuddyPress (1.5.0)
    755965 *
    756966 * @uses bp_get_search_slug()
    … …  
    760970}
    761971    /**
    762      * Return the search slug
     972     * Return the search slug.
    763973     *
    764      * @package BuddyPress
    765      * @since BuddyPress (1.5)
     974     * @since BuddyPress (1.5.0)
     975     *
     976     * @return string The search slug. Default: 'search'.
    766977     */
    767978    function bp_get_search_slug() {
    … …  
    770981
    771982/**
    772  * Get the id of the currently displayed user
    773  *
    774  * @uses apply_filters() Filter 'bp_displayed_user_id' to change this value
    775  * @return int
     983 * Get the ID of the currently displayed user.
     984 *
     985 * @uses apply_filters() Filter 'bp_displayed_user_id' to change this value.
     986 *
     987 * @return int ID of the currently displayed user.
    776988 */
    777989function bp_displayed_user_id() {
    … …  
    783995
    784996/**
    785  * Get the id of the currently logged-in user
    786  *
    787  * @uses apply_filters() Filter 'bp_loggedin_user_id' to change this value
    788  * @return int
     997 * Get the ID of the currently logged-in user.
     998 *
     999 * @uses apply_filters() Filter 'bp_loggedin_user_id' to change this value.
     1000 *
     1001 * @return int ID of the logged-in user.
    7891002 */
    7901003function bp_loggedin_user_id() {
    … …  
    7981011
    7991012/**
    800  * Checks to see whether the current page belongs to the specified component
     1013 * Check to see whether the current page belongs to the specified component.
    8011014 *
    8021015 * This function is designed to be generous, accepting several different kinds
    … …  
    8061019 * - the component's id, or 'canonical' name
    8071020 *
    808  * @package BuddyPress Core
    809  * @since BuddyPress (1.5)
     1021 * @since BuddyPress (1.5.0)
     1022 *
     1023 * @param string $component Name of the component being checked.
    8101024 * @return bool Returns true if the component matches, or else false.
    8111025 */
    … …  
    8841098 * Check to see whether the current page matches a given action.
    8851099 *
    886  * Along with bp_is_current_component() and bp_is_action_variable(), this function is mostly used
    887  * to help determine when to use a given screen function.
    888  *
    889  * In BP parlance, the current_action is the URL chunk that comes directly after the
    890  * current item slug. E.g., in
     1100 * Along with bp_is_current_component() and bp_is_action_variable(), this
     1101 * function is mostly used to help determine when to use a given screen
     1102 * function.
     1103 *
     1104 * In BP parlance, the current_action is the URL chunk that comes directly
     1105 * after the current item slug. E.g., in
    8911106 *   http://example.com/groups/my-group/members
    8921107 * the current_action is 'members'.
    8931108 *
    894  * @package BuddyPress
    895  * @since BuddyPress (1.5)
    896  *
    897  * @param string $action The action being tested against
    898  * @return bool True if the current action matches $action
     1109 * @since BuddyPress (1.5.0)
     1110 *
     1111 * @param string $action The action being tested against.
     1112 * @return bool True if the current action matches $action.
    8991113 */
    9001114function bp_is_current_action( $action = '' ) {
    … …  
    9081122 * Check to see whether the current page matches a given action_variable.
    9091123 *
    910  * Along with bp_is_current_component() and bp_is_current_action(), this function is mostly used
    911  * to help determine when to use a given screen function.
    912  *
    913  * In BP parlance, action_variables are an array made up of the URL chunks appearing after the
    914  * current_action in a URL. For example,
     1124 * Along with bp_is_current_component() and bp_is_current_action(), this
     1125 * function is mostly used to help determine when to use a given screen
     1126 * function.
     1127 *
     1128 * In BP parlance, action_variables are an array made up of the URL chunks
     1129 * appearing after the current_action in a URL. For example,
    9151130 *   http://example.com/groups/my-group/admin/group-settings
    9161131 * $action_variables[0] is 'group-settings'.
    9171132 *
    918  * @package BuddyPress
    919  * @since BuddyPress (1.5)
    920  *
    921  * @param string $action_variable The action_variable being tested against
    922  * @param int $position The array key you're testing against. If you don't provide a $position,
    923  *   the function will return true if the $action_variable is found *anywhere* in the action
    924  *   variables array.
    925  * @return bool
     1133 * @since BuddyPress (1.5.0)
     1134 *
     1135 * @param string $action_variable The action_variable being tested against.
     1136 * @param int $position Optional. The array key you're testing against. If you
     1137 *        don't provide a $position, the function will return true if the
     1138 *        $action_variable is found *anywhere* in the action variables array.
     1139 * @return bool True if $action_variable matches at the $position provided.
    9261140 */
    9271141function bp_is_action_variable( $action_variable = '', $position = false ) {
    … …  
    9451159}
    9461160
     1161/**
     1162 * Check against the current_item.
     1163 *
     1164 * @param string $item The item being checked.
     1165 * @return bool True if $item is the current item.
     1166 */
    9471167function bp_is_current_item( $item = '' ) {
    9481168    if ( !empty( $item ) && $item == bp_current_item() )
    … …  
    9521172}
    9531173
     1174/**
     1175 * Are we looking at a single item? (group, user, etc)
     1176 *
     1177 * @return bool True if looking at a single item, otherwise false.
     1178 */
    9541179function bp_is_single_item() {
    9551180    global $bp;
    … …  
    9611186}
    9621187
     1188/**
     1189 * Is the logged-in user an admin for the current item?
     1190 *
     1191 * @return bool True if the current user is an admin for the current item,
     1192 *         otherwise false.
     1193 */
    9631194function bp_is_item_admin() {
    9641195    global $bp;
    … …  
    9701201}
    9711202
     1203/**
     1204 * Is the logged-in user a mod for the current item?
     1205 *
     1206 * @return bool True if the current user is a mod for the current item,
     1207 *         otherwise false.
     1208 */
    9721209function bp_is_item_mod() {
    9731210    global $bp;
    … …  
    9791216}
    9801217
     1218/**
     1219 * Is this a component directory page?
     1220 *
     1221 * @return bool True if the current page is a component directory, otherwise
     1222 *         false.
     1223 */
    9811224function bp_is_directory() {
    9821225    global $bp;
    … …  
    9891232
    9901233/**
    991  * Checks to see if a component's URL should be in the root, not under a
    992  * member page:
    993  *
    994  *   Yes: http://domain.com/groups/the-group
    995  *   No:  http://domain.com/members/andy/groups/the-group
    996  *
    997  * @package BuddyPress Core
     1234 * Check to see if a component's URL should be in the root, not under a member page.
     1235 *
     1236 *   Yes ('groups' is root): http://domain.com/groups/the-group
     1237 *   No ('groups' is not-root):  http://domain.com/members/andy/groups/the-group
     1238 *
    9981239 * @return bool True if root component, else false.
    9991240 */
    … …  
    10131254
    10141255/**
    1015  * Checks if the site's front page is set to the specified BuddyPress component
    1016  * page in wp-admin's Settings > Reading screen.
    1017  *
    1018  * @global BuddyPress $bp The one true BuddyPress instance
    1019  * @global $current_blog WordPress global for the current blog
    1020  * @param string $component Optional; Name of the component to check for.
    1021  * @return bool True If the specified component is set to be the site's front page.
    1022  * @since BuddyPress (1.5)
     1256 * Check if the specified BuddyPress component directory is set to be the front page.
     1257 *
     1258 * Corresponds to the setting in wp-admin's Settings > Reading screen.
     1259 *
     1260 * @since BuddyPress (1.5.0)
     1261 *
     1262 * @global BuddyPress $bp The one true BuddyPress instance.
     1263 * @global $current_blog WordPress global for the current blog.
     1264 *
     1265 * @param string $component Optional. Name of the component to check for.
     1266 *        Default: current component.
     1267 * @return bool True if the specified component is set to be the site's front
     1268 *         page, otherwise false.
    10231269 */
    10241270function bp_is_component_front_page( $component = '' ) {
    … …  
    10391285 * Is this a blog page, ie a non-BP page?
    10401286 *
    1041  * You can tell if a page is displaying BP content by whether the current_component has been defined
    1042  *
    1043  * @package BuddyPress
    1044  *
    1045  * @return bool True if it's a non-BP page, false otherwise
     1287 * You can tell if a page is displaying BP content by whether the
     1288 * current_component has been defined.
     1289 *
     1290 * @return bool True if it's a non-BP page, false otherwise.
    10461291 */
    10471292function bp_is_blog_page() {
    … …  
    10621307 *
    10631308 * You can tell if a page is displaying BP content by whether the
    1064  * current_component has been defined
     1309 * current_component has been defined.
    10651310 *
    10661311 * Generally, we can just check to see that there's no current component.
    … …  
    10681313 * is unset. Thus the addition of the bp_is_user() check.
    10691314 *
    1070  * @since BuddyPress (1.7)
    1071  *
    1072  * @package BuddyPress
    1073  * @return bool True if it's a BuddyPress page, false otherwise
     1315 * @since BuddyPress (1.7.0)
     1316 *
     1317 * @return bool True if it's a BuddyPress page, false otherwise.
    10741318 */
    10751319function is_buddypress() {
    … …  
    10811325/** Components ****************************************************************/
    10821326
     1327/**
     1328 * Check whether a given component has been activated by the admin.
     1329 *
     1330 * @param string $component The component name.
     1331 * @return bool True if the component is active, otherwise false.
     1332 */
    10831333function bp_is_active( $component ) {
    10841334    global $bp;
    … …  
    10901340}
    10911341
     1342/**
     1343 * Check whether the current page is part of the Members component.
     1344 *
     1345 * @return bool True if the current page is part of the Members component.
     1346 */
    10921347function bp_is_members_component() {
    10931348    if ( bp_is_current_component( 'members' ) )
    … …  
    10971352}
    10981353
     1354/**
     1355 * Check whether the current page is part of the Profile component.
     1356 *
     1357 * @return bool True if the current page is part of the Profile component.
     1358 */
    10991359function bp_is_profile_component() {
    11001360    if ( bp_is_current_component( 'xprofile' ) )
    … …  
    11041364}
    11051365
     1366/**
     1367 * Check whether the current page is part of the Activity component.
     1368 *
     1369 * @return bool True if the current page is part of the Activity component.
     1370 */
    11061371function bp_is_activity_component() {
    11071372    if ( bp_is_current_component( 'activity' ) )
    … …  
    11111376}
    11121377
     1378/**
     1379 * Check whether the current page is part of the Blogs component.
     1380 *
     1381 * @return bool True if the current page is part of the Blogs component.
     1382 */
    11131383function bp_is_blogs_component() {
    11141384    if ( is_multisite() && bp_is_current_component( 'blogs' ) )
    … …  
    11181388}
    11191389
     1390/**
     1391 * Check whether the current page is part of the Messages component.
     1392 *
     1393 * @return bool True if the current page is part of the Messages component.
     1394 */
    11201395function bp_is_messages_component() {
    11211396    if ( bp_is_current_component( 'messages' ) )
    … …  
    11251400}
    11261401
     1402/**
     1403 * Check whether the current page is part of the Friends component.
     1404 *
     1405 * @return bool True if the current page is part of the Friends component.
     1406 */
    11271407function bp_is_friends_component() {
    11281408    if ( bp_is_current_component( 'friends' ) )
    … …  
    11321412}
    11331413
     1414/**
     1415 * Check whether the current page is part of the Groups component.
     1416 *
     1417 * @return bool True if the current page is part of the Groups component.
     1418 */
    11341419function bp_is_groups_component() {
    11351420    if ( bp_is_current_component( 'groups' ) )
    … …  
    11391424}
    11401425
     1426/**
     1427 * Check whether the current page is part of the Forums component.
     1428 *
     1429 * @return bool True if the current page is part of the Forums component.
     1430 */
    11411431function bp_is_forums_component() {
    11421432    if ( bp_is_current_component( 'forums' ) )
    … …  
    11461436}
    11471437
     1438/**
     1439 * Check whether the current page is part of the Settings component.
     1440 *
     1441 * @return bool True if the current page is part of the Settings component.
     1442 */
    11481443function bp_is_settings_component() {
    11491444    if ( bp_is_current_component( 'settings' ) )
    … …  
    11541449
    11551450/**
    1156  * Is the current component an active core component.
     1451 * Is the current component an active core component?
    11571452 *
    11581453 * Use this function when you need to check if the current component is an
    … …  
    11621457 * BuddyPress core, it will return true.
    11631458 *
    1164  * @since BuddyPress (1.7)
    1165  * @return boolean
     1459 * @return bool True if the current component is active and is one of BP's
     1460 *         packaged components.
    11661461 */
    11671462function bp_is_current_component_core() {
    … …  
    11811476/** Activity ******************************************************************/
    11821477
     1478/**
     1479 * Is the current page a single activity item permalink?
     1480 *
     1481 * @return True if the current page is a single activity item permalink.
     1482 */
    11831483function bp_is_single_activity() {
    11841484    if ( bp_is_activity_component() && is_numeric( bp_current_action() ) )
    … …  
    11901490/** User **********************************************************************/
    11911491
     1492/**
     1493 * Is the current page part of the profile of the logged-in user?
     1494 *
     1495 * Will return true for any subpage of the logged-in user's profile, eg
     1496 * http://example.com/members/joe/friends/.
     1497 *
     1498 * @return True if the current page is part of the profile of the logged-in user.
     1499 */
    11921500function bp_is_my_profile() {
    11931501    if ( is_user_logged_in() && bp_loggedin_user_id() == bp_displayed_user_id() )
    … …  
    11991507}
    12001508
     1509/**
     1510 * Is the current page a user page?
     1511 *
     1512 * Will return true anytime there is a displayed user.
     1513 *
     1514 * @return True if the current page is a user page.
     1515 */
    12011516function bp_is_user() {
    12021517    if ( bp_displayed_user_id() )
    … …  
    12061521}
    12071522
     1523/**
     1524 * Is the current page a user's activity stream page?
     1525 *
     1526 * Eg http://example.com/members/joe/activity/ (or any subpages thereof).
     1527 *
     1528 * @return True if the current page is a user's activity stream page.
     1529 */
    12081530function bp_is_user_activity() {
    12091531    if ( bp_is_user() && bp_is_activity_component() )
    … …  
    12131535}
    12141536
     1537/**
     1538 * Is the current page a user's Friends activity stream?
     1539 *
     1540 * Eg http://example.com/members/joe/friends/
     1541 *
     1542 * @return True if the current page is a user's Friends activity stream.
     1543 */
    12151544function bp_is_user_friends_activity() {
    12161545
    … …  
    12291558}
    12301559
     1560/**
     1561 * Is the current page a user's Groups activity stream?
     1562 *
     1563 * Eg http://example.com/members/joe/groups/
     1564 *
     1565 * @return True if the current page is a user's Groups activity stream.
     1566 */
    12311567function bp_is_user_groups_activity() {
    12321568
    … …  
    12451581}
    12461582
     1583/**
     1584 * Is the current page part of a user's extended profile?
     1585 *
     1586 * Eg http://example.com/members/joe/profile/ (or a subpage thereof).
     1587 *
     1588 * @return True if the current page is part of a user's extended profile.
     1589 */
    12471590function bp_is_user_profile() {
    12481591    if ( bp_is_profile_component() || bp_is_current_component( 'profile' ) )
    … …  
    12521595}
    12531596
     1597/**
     1598 * Is the current page part of a user's profile editing section?
     1599 *
     1600 * Eg http://example.com/members/joe/profile/edit/ (or a subpage thereof).
     1601 *
     1602 * @return True if the current page is a user's profile edit page.
     1603 */
    12541604function bp_is_user_profile_edit() {
    12551605    if ( bp_is_profile_component() && bp_is_current_action( 'edit' ) )
    … …  
    12691619 * Is this a user's forums page?
    12701620 *
    1271  * @package BuddyPress
    1272  *
    1273  * @return bool
     1621 * Eg http://example.com/members/joe/forums/ (or a subpage thereof).
     1622 *
     1623 * @return bool True if the current page is a user's forums page.
    12741624 */
    12751625function bp_is_user_forums() {
    … …  
    12871637 * Is this a user's "Topics Started" page?
    12881638 *
    1289  * @package BuddyPress
    1290  * @since BuddyPress (1.5)
    1291  *
    1292  * @return bool
     1639 * Eg http://example.com/members/joe/forums/topics/.
     1640 *
     1641 * @since BuddyPress (1.5.0)
     1642 *
     1643 * @return bool True if the current page is a user's Topics Started page.
    12931644 */
    12941645function bp_is_user_forums_started() {
    … …  
    13021653 * Is this a user's "Replied To" page?
    13031654 *
    1304  * @package BuddyPress
    1305  * @since BuddyPress (1.5)
    1306  *
    1307  * @return bool
     1655 * Eg http://example.com/members/joe/forums/replies/.
     1656 *
     1657 * @since BuddyPress (1.5.0)
     1658 *
     1659 * @return bool True if the current page is a user's Replied To forums page.
    13081660 */
    13091661function bp_is_user_forums_replied_to() {
    … …  
    13141666}
    13151667
     1668/**
     1669 * Is the current page part of a user's Groups page?
     1670 *
     1671 * Eg http://example.com/members/joe/groups/ (or a subpage thereof).
     1672 *
     1673 * @return bool True if the current page is a user's Groups page.
     1674 */
    13161675function bp_is_user_groups() {
    13171676    if ( bp_is_user() && bp_is_groups_component() )
    … …  
    13211680}
    13221681
     1682/**
     1683 * Is the current page part of a user's Blogs page?
     1684 *
     1685 * Eg http://example.com/members/joe/blogs/ (or a subpage thereof).
     1686 *
     1687 * @return bool True if the current page is a user's Blogs page.
     1688 */
    13231689function bp_is_user_blogs() {
    13241690    if ( bp_is_user() && bp_is_blogs_component() )
    … …  
    13281694}
    13291695
     1696/**
     1697 * Is the current page a user's Recent Blog Posts page?
     1698 *
     1699 * Eg http://example.com/members/joe/blogs/recent-posts/.
     1700 *
     1701 * @return bool True if the current page is a user's Recent Blog Posts page.
     1702 */
    13301703function bp_is_user_recent_posts() {
    13311704    if ( bp_is_user_blogs() && bp_is_current_action( 'recent-posts' ) )
    … …  
    13351708}
    13361709
     1710/**
     1711 * Is the current page a user's Recent Blog Comments page?
     1712 *
     1713 * Eg http://example.com/members/joe/blogs/recent-comments/.
     1714 *
     1715 * @return bool True if the current page is a user's Recent Blog Comments page.
     1716 */
    13371717function bp_is_user_recent_commments() {
    13381718    if ( bp_is_user_blogs() && bp_is_current_action( 'recent-comments' ) )
    … …  
    13421722}
    13431723
     1724/**
     1725 * Is the current page a user's Friends page?
     1726 *
     1727 * Eg http://example.com/members/joe/blogs/friends/ (or a subpage thereof).
     1728 *
     1729 * @return bool True if the current page is a user's Friends page.
     1730 */
    13441731function bp_is_user_friends() {
    13451732    if ( bp_is_user() && bp_is_friends_component() )
    … …  
    13491736}
    13501737
     1738/**
     1739 * Is the current page a user's Friend Requests page?
     1740 *
     1741 * Eg http://example.com/members/joe/friends/requests/.
     1742 *
     1743 * @return bool True if the current page is a user's Friends Requests page.
     1744 */
    13511745function bp_is_user_friend_requests() {
    13521746    if ( bp_is_user_friends() && bp_is_current_action( 'requests' ) )
    … …  
    13591753 * Is this a user's settings page?
    13601754 *
    1361  * @package BuddyPress
    1362  *
    1363  * @return bool
     1755 * Eg http://example.com/members/joe/settings/ (or a subpage thereof).
     1756 *
     1757 * @return bool True if the current page is a user's Settings page.
    13641758 */
    13651759function bp_is_user_settings() {
    … …  
    13731767 * Is this a user's General Settings page?
    13741768 *
    1375  * @package BuddyPress
    1376  * @since BuddyPress (1.5)
    1377  *
    1378  * @return bool
     1769 * Eg http://example.com/members/joe/settings/general/.
     1770 *
     1771 * @since BuddyPress (1.5.0)
     1772 *
     1773 * @return bool True if the current page is a user's General Settings page.
    13791774 */
    13801775function bp_is_user_settings_general() {
    … …  
    13881783 * Is this a user's Notification Settings page?
    13891784 *
    1390  * @package BuddyPress
    1391  * @since BuddyPress (1.5)
    1392  *
    1393  * @return bool
     1785 * Eg http://example.com/members/joe/settings/notifications/.
     1786 *
     1787 * @since BuddyPress (1.5.0)
     1788 *
     1789 * @return bool True if the current page is a user's Notification Settings page.
    13941790 */
    13951791function bp_is_user_settings_notifications() {
    … …  
    14031799 * Is this a user's Account Deletion page?
    14041800 *
    1405  * @package BuddyPress
    1406  * @since BuddyPress (1.5)
    1407  *
    1408  * @return bool
     1801 * Eg http://example.com/members/joe/settings/delete-account/.
     1802 *
     1803 * @since BuddyPress (1.5.0)
     1804 *
     1805 * @return bool True if the current page is a user's Delete Account page.
    14091806 */
    14101807function bp_is_user_settings_account_delete() {
    … …  
    14151812}
    14161813
    1417 
    1418 /** Groups ******************************************************************/
    1419 
     1814/** Groups ********************************************************************/
     1815
     1816/**
     1817 * Does the current page belong to a single group?
     1818 *
     1819 * Will return true for any subpage of a single group.
     1820 *
     1821 * @return bool True if the current page is part of a single group.
     1822 */
    14201823function bp_is_group() {
    14211824    global $bp;
    … …  
    14271830}
    14281831
     1832/**
     1833 * Is the current page a single group's home page?
     1834 *
     1835 * URL will vary depending on which group tab is set to be the "home". By
     1836 * default, it's the group's recent activity.
     1837 *
     1838 * @return bool True if the current page is a single group's home page.
     1839 */
    14291840function bp_is_group_home() {
    14301841    if ( bp_is_single_item() && bp_is_groups_component() && ( !bp_current_action() || bp_is_current_action( 'home' ) ) )
    … …  
    14341845}
    14351846
     1847/**
     1848 * Is the current page part of the group creation process?
     1849 *
     1850 * @return bool True if the current page is part of the group creation process.
     1851 */
    14361852function bp_is_group_create() {
    14371853    if ( bp_is_groups_component() && bp_is_current_action( 'create' ) )
    … …  
    14411857}
    14421858
     1859/**
     1860 * Is the current page part of a single group's admin screens?
     1861 *
     1862 * Eg http://example.com/groups/mygroup/admin/settings/.
     1863 *
     1864 * @return bool True if the current page is part of a single group's admin.
     1865 */
    14431866function bp_is_group_admin_page() {
    14441867    if ( bp_is_single_item() && bp_is_groups_component() && bp_is_current_action( 'admin' ) )
    … …  
    14481871}
    14491872
     1873/**
     1874 * Is the current page a group's forum page?
     1875 *
     1876 * Only applies to legacy bbPress forums.
     1877 *
     1878 * @return bool True if the current page is a group forum page.
     1879 */
    14501880function bp_is_group_forum() {
    14511881    $retval = false;
    … …  
    14651895}
    14661896
     1897/**
     1898 * Is the current page a group's activity page?
     1899 *
     1900 * @return True if the current page is a group's activity page.
     1901 */
    14671902function bp_is_group_activity() {
    14681903    if ( bp_is_single_item() && bp_is_groups_component() && bp_is_current_action( 'activity' ) )
    … …  
    14721907}
    14731908
     1909/**
     1910 * Is the current page a group forum topic?
     1911 *
     1912 * Only applies to legacy bbPress (1.x) forums.
     1913 *
     1914 * @return bool True if the current page is part of a group forum topic.
     1915 */
    14741916function bp_is_group_forum_topic() {
    14751917    if ( bp_is_single_item() && bp_is_groups_component() && bp_is_current_action( 'forum' ) && bp_is_action_variable( 'topic', 0 ) )
    … …  
    14791921}
    14801922
     1923/**
     1924 * Is the current page a group forum topic edit page?
     1925 *
     1926 * Only applies to legacy bbPress (1.x) forums.
     1927 *
     1928 * @return bool True if the current page is part of a group forum topic edit page.
     1929 */
    14811930function bp_is_group_forum_topic_edit() {
    14821931    if ( bp_is_single_item() && bp_is_groups_component() && bp_is_current_action( 'forum' ) && bp_is_action_variable( 'topic', 0 ) && bp_is_action_variable( 'edit', 2 ) )
    … …  
    14861935}
    14871936
     1937/**
     1938 * Is the current page a group's Members page?
     1939 *
     1940 * Eg http://example.com/groups/mygroup/members/.
     1941 *
     1942 * @return bool True if the current page is part of a group's Members page.
     1943 */
    14881944function bp_is_group_members() {
    14891945    if ( bp_is_single_item() && bp_is_groups_component() && bp_is_current_action( 'members' ) )
    … …  
    14931949}
    14941950
     1951/**
     1952 * Is the current page a group's Invites page?
     1953 *
     1954 * Eg http://example.com/groups/mygroup/send-invites/.
     1955 *
     1956 * @return bool True if the current page is a group's Send Invites page.
     1957 */
    14951958function bp_is_group_invites() {
    14961959    if ( bp_is_groups_component() && bp_is_current_action( 'send-invites' ) )
    … …  
    15001963}
    15011964
     1965/**
     1966 * Is the current page a group's Request Membership page?
     1967 *
     1968 * Eg http://example.com/groups/mygroup/request-membership/.
     1969 *
     1970 * @return bool True if the current page is a group's Request Membership page.
     1971 */
    15021972function bp_is_group_membership_request() {
    15031973    if ( bp_is_groups_component() && bp_is_current_action( 'request-membership' ) )
    … …  
    15071977}
    15081978
     1979/**
     1980 * Is the current page a leave group attempt?
     1981 *
     1982 * @return bool True if the current page is a Leave Group attempt.
     1983 */
    15091984function bp_is_group_leave() {
    15101985
    … …  
    15151990}
    15161991
     1992/**
     1993 * Is the current page part of a single group?
     1994 *
     1995 * Not currently used by BuddyPress.
     1996 *
     1997 * @todo How is this functionally different from bp_is_group()?
     1998 *
     1999 * @return bool True if the current page is part of a single group.
     2000 */
    15172001function bp_is_group_single() {
    15182002    if ( bp_is_groups_component() && bp_is_single_item() )
    … …  
    15222006}
    15232007
     2008/**
     2009 * Is the current page the Create a Blog page?
     2010 *
     2011 * Eg http://example.com/sites/create/.
     2012 *
     2013 * @return bool True if the current page is the Create a Blog page.
     2014 */
    15242015function bp_is_create_blog() {
    15252016    if ( bp_is_blogs_component() && bp_is_current_action( 'create' ) )
    … …  
    15312022/** Messages ******************************************************************/
    15322023
     2024/**
     2025 * Is the current page part of a user's Messages pages?
     2026 *
     2027 * Eg http://example.com/members/joe/messages/ (or a subpage thereof).
     2028 *
     2029 * @return bool True if the current page is part of a user's Messages pages.
     2030 */
    15332031function bp_is_user_messages() {
    15342032    if ( bp_is_user() && bp_is_messages_component() )
    … …  
    15382036}
    15392037
     2038/**
     2039 * Is the current page a user's Messages Inbox?
     2040 *
     2041 * Eg http://example.com/members/joe/messages/inbox/.
     2042 *
     2043 * @return bool True if the current page is a user's Messages Inbox.
     2044 */
    15402045function bp_is_messages_inbox() {
    15412046    if ( bp_is_user_messages() && ( !bp_current_action() || bp_is_current_action( 'inbox' ) ) )
    … …  
    15452050}
    15462051
     2052/**
     2053 * Is the current page a user's Messages Sentbox?
     2054 *
     2055 * Eg http://example.com/members/joe/messages/sentbox/.
     2056 *
     2057 * @return bool True if the current page is a user's Messages Sentbox.
     2058 */
    15472059function bp_is_messages_sentbox() {
    15482060    if ( bp_is_user_messages() && bp_is_current_action( 'sentbox' ) )
    … …  
    15522064}
    15532065
     2066/**
     2067 * Is the current page a user's Messages Compose screen??
     2068 *
     2069 * Eg http://example.com/members/joe/messages/compose/.
     2070 *
     2071 * @return bool True if the current page is a user's Messages Compose screen.
     2072 */
    15542073function bp_is_messages_compose_screen() {
    15552074    if ( bp_is_user_messages() && bp_is_current_action( 'compose' ) )
    … …  
    15592078}
    15602079
     2080/**
     2081 * Is the current page the Notices screen?
     2082 *
     2083 * Eg http://example.com/members/joe/messages/notices/.
     2084 *
     2085 * @return bool True if the current page is the Notices screen.
     2086 */
    15612087function bp_is_notices() {
    15622088    if ( bp_is_user_messages() && bp_is_current_action( 'notices' ) )
    … …  
    15662092}
    15672093
     2094/**
     2095 * Is the current page a single Messages conversation thread?
     2096 *
     2097 * @return bool True if the current page a single Messages conversation thread?
     2098 */
    15682099function bp_is_messages_conversation() {
    15692100    if ( bp_is_user_messages() && ( bp_is_current_action( 'view' ) ) )
    … …  
    15732104}
    15742105
     2106/**
     2107 * Not currently used by BuddyPress.
     2108 *
     2109 * @return bool
     2110 */
    15752111function bp_is_single( $component, $callback ) {
    15762112    if ( bp_is_current_component( $component ) && ( true === call_user_func( $callback ) ) )
    … …  
    15822118/** Registration **************************************************************/
    15832119
     2120/**
     2121 * Is the current page the Activate page?
     2122 *
     2123 * Eg http://example.com/activate/.
     2124 *
     2125 * @return bool True if the current page is the Activate page.
     2126 */
    15842127function bp_is_activation_page() {
    15852128    if ( bp_is_current_component( 'activate' ) )
    … …  
    15892132}
    15902133
     2134/**
     2135 * Is the current page the Register page?
     2136 *
     2137 * Eg http://example.com/register/.
     2138 *
     2139 * @return bool True if the current page is the Register page.
     2140 */
    15912141function bp_is_register_page() {
    15922142    if ( bp_is_current_component( 'register' ) )
    … …  
    15972147
    15982148/**
    1599  * Use the above is_() functions to output a body class for each scenario
    1600  *
    1601  * @package BuddyPress
    1602  * @subpackage Core Template
    1603  *
    1604  * @param array $wp_classes The body classes coming from WP
    1605  * @param array $custom_classes Classes that were passed to get_body_class()
    1606  * @return array $classes The BP-adjusted body classes
     2149 * Customize the body class, according to the currently displayed BP content.
     2150 *
     2151 * Uses the above is_() functions to output a body class for each scenario.
     2152 *
     2153 * @param array $wp_classes The body classes coming from WP.
     2154 * @param array $custom_classes Classes that were passed to get_body_class().
     2155 * @return array $classes The BP-adjusted body classes.
    16072156 */
    16082157function bp_the_body_class() {
    … …  
    18032352 * Sort BuddyPress nav menu items by their position property.
    18042353 *
    1805  * This is an internal convenience function and it will probably be removed in a later release. Do not use.
     2354 * This is an internal convenience function and it will probably be removed in
     2355 * a later release. Do not use.
    18062356 *
    18072357 * @access private
    1808  * @param array $a First item
    1809  * @param array $b Second item
    1810  * @return int Returns an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
    1811  * @since BuddyPress (1.7)
     2358 * @since BuddyPress (1.7.0)
     2359 *
     2360 * @param array $a First item.
     2361 * @param array $b Second item.
     2362 * @return int Returns an integer less than, equal to, or greater than zero if
     2363 *         the first argument is considered to be respectively less than, equal to, or greater than the second.
    18122364 */
    18132365function _bp_nav_menu_sort( $a, $b ) {
    … …  
    18232375
    18242376/**
    1825  * Get an array of all the items registered in the primary and secondary BuddyPress navigation menus
    1826  *
    1827  * @return array
    1828  * @since BuddyPress (1.7)
     2377 * Get the items registered in the primary and secondary BuddyPress navigation menus.
     2378 *
     2379 * @since BuddyPress (1.7.0)
     2380 *
     2381 * @return array A multidimensional array of all navigation items.
    18292382 */
    18302383function bp_get_nav_menu_items() {
    … …  
    19002453
    19012454/**
    1902  * Displays a navigation menu.
    1903  *
    1904  * @param string|array $args Optional arguments:
    1905  *  - before           Text before the link text.
    1906  *  - container        Whether to wrap the ul, and what to wrap it with.
    1907  *                     Defaults to div.
    1908  *  - container_class  The class that is applied to the container. Defaults to
    1909  *                     'menu-bp-container'.
    1910  *  - container_id     The ID that is applied to the container. Defaults to
    1911  *                     blank.
    1912  *  - depth            How many levels of the hierarchy are to be included. 0
    1913  *                     means all. Defaults to 0.
    1914  *  - echo             Whether to echo the menu or return it. Defaults to echo.
    1915  *  - fallback_cb      If the menu doesn't exists, a callback function will
    1916  *                     fire. Defaults to false (no fallback).
    1917  *  - items_wrap       How the list items should be wrapped. Defaults to a ul
    1918  *                     with an id and class. Uses printf() format with numbered
    1919  *                     placeholders.
    1920  *  - link_after       Text after the link.
    1921  *  - link_before      Text before the link.
    1922  *  - menu_class       CSS class to use for the ul element which forms the menu.
    1923  *                     Defaults to 'menu'.
    1924  *  - menu_id          The ID that is applied to the ul element which forms the
    1925  *                     menu. Defaults to 'menu-bp', incremented.
    1926  *  - walker           Allows a custom walker to be specified. Defaults to
    1927  *                     'BP_Walker_Nav_Menu'.
    1928  *
    1929  * @since BuddyPress (1.7)
     2455 * Display a navigation menu.
     2456 *
     2457 * @since BuddyPress (1.7.0)
     2458 *
     2459 * @param string|array $args {
     2460 *     An array of optional arguments.
     2461 *     @type string $after Text after the link text. Default: ''.
     2462 *     @type string $before Text before the link text. Default: ''.
     2463 *     @type string $container The name of the element to wrap the navigation
     2464 *           with. 'div' or 'nav'. Default: 'div'.
     2465 *     @type string $container_class The class that is applied to the container.
     2466 *           Default: 'menu-bp-container'.
     2467 *     @type string $container_id The ID that is applied to the container.
     2468 *           Default: ''.
     2469 *     @type int depth How many levels of the hierarchy are to be included. 0
     2470 *           means all. Default: 0.
     2471 *     @type bool $echo True to echo the menu, false to return it.
     2472 *           Default: true.
     2473 *     @type bool $fallback_cb If the menu doesn't exist, should a callback
     2474 *           function be fired? Default: false (no fallback).
     2475 *     @type string $items_wrap How the list items should be wrapped. Should be
     2476 *           in the form of a printf()-friendly string, using numbered
     2477 *           placeholders. Default: '<ul id="%1$s" class="%2$s">%3$s</ul>'.
     2478 *     @type string $link_after Text after the link. Default: ''.
     2479 *     @type string $link_before Text before the link. Default: ''.
     2480 *     @type string $menu_class CSS class to use for the <ul> element which
     2481 *           forms the menu. Default: 'menu'.
     2482 *     @type string $menu_id The ID that is applied to the <ul> element which
     2483 *           forms the menu. Default: 'menu-bp', incremented.
     2484 *     @type string $walker Allows a custom walker class to be specified.
     2485 *           Default: 'BP_Walker_Nav_Menu'.
     2486 * }
     2487 * @return string|null If $echo is false, returns a string containing the nav
     2488 *         menu markup.
    19302489 */
    19312490function bp_nav_menu( $args = array() ) {
Note: See TracChangeset for help on using the changeset viewer.