Skip to:
Content

BuddyPress.org

Changeset 7449


Ignore:
Timestamp:
10/20/2013 12:06:35 AM (11 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-core. See #5022

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/bp-core/bp-core-functions.php

    r7427 r7449  
    22
    33/**
    4  * BuddyPress Common Functions
     4 * BuddyPress Common Functions.
    55 *
    66 * @package BuddyPress
     
    1414
    1515/**
    16  * Output the BuddyPress version
    17  *
    18  * @since BuddyPress (1.6)
    19  * @uses bp_get_version() To get the BuddyPress version
     16 * Output the BuddyPress version.
     17 *
     18 * @since BuddyPress (1.6.0)
     19 *
     20 * @uses bp_get_version() To get the BuddyPress version.
    2021 */
    2122function bp_version() {
     
    2324}
    2425    /**
    25      * Return the BuddyPress version
     26     * Return the BuddyPress version.
    2627     *
    27      * @since BuddyPress (1.6)
    28      * @return string The BuddyPress version
     28     * @since BuddyPress (1.6.0)
     29     *
     30     * @return string The BuddyPress version.
    2931     */
    3032    function bp_get_version() {
     
    3335
    3436/**
    35  * Output the BuddyPress database version
    36  *
    37  * @since BuddyPress (1.6)
    38  * @uses bp_get_db_version() To get the BuddyPress version
     37 * Output the BuddyPress database version.
     38 *
     39 * @since BuddyPress (1.6.0)
     40 *
     41 * @uses bp_get_db_version() To get the BuddyPress database version.
    3942 */
    4043function bp_db_version() {
    4144    echo bp_get_db_version();
     45}
     46    /**
     47     * Return the BuddyPress database version.
     48     *
     49     * @since BuddyPress (1.6.0)
     50     * @return string The BuddyPress database version.
     51     */
     52    function bp_get_db_version() {
     53        return buddypress()->db_version;
     54    }
     55
     56/**
     57 * Output the BuddyPress database version.
     58 *
     59 * @since BuddyPress (1.6.0)
     60 *
     61 * @uses bp_get_db_version_raw() To get the current database BuddyPress version.
     62 */
     63function bp_db_version_raw() {
     64    echo bp_get_db_version_raw();
    4265}
    4366    /**
     
    4568     *
    4669     * @since BuddyPress (1.6)
    47      * @return string The BuddyPress version
    48      */
    49     function bp_get_db_version() {
    50         return buddypress()->db_version;
    51     }
    52 
    53 /**
    54  * Output the BuddyPress database version
    55  *
    56  * @since BuddyPress (1.6)
    57  * @uses bp_get_db_version_raw() To get the current BuddyPress version
    58  */
    59 function bp_db_version_raw() {
    60     echo bp_get_db_version_raw();
    61 }
    62     /**
    63      * Return the BuddyPress database version
    6470     *
    65      * @since BuddyPress (1.6)
    66      * @return string The BuddyPress version direct from the database
     71     * @return string The BuddyPress version direct from the database.
    6772     */
    6873    function bp_get_db_version_raw() {
     
    7479
    7580/**
    76  * Allow filtering of database prefix. Intended for use in multinetwork installations.
    77  *
    78  * @global object $wpdb WordPress database object
    79  * @return string Filtered database prefix
     81 * Get the $wpdb base prefix, run through the 'bp_core_get_table_prefix' filter.
     82 *
     83 * The filter is intended primarily for use in multinetwork installations.
     84 *
     85 * @global object $wpdb WordPress database object.
     86 *
     87 * @return string Filtered database prefix.
    8088 */
    8189function bp_core_get_table_prefix() {
     
    132140
    133141/**
    134  * Format numbers the BuddyPress way
    135  *
    136  * @param int $number
    137  * @param bool $decimals
    138  * @return string
     142 * Format numbers the BuddyPress way.
     143 *
     144 * @param int $number The number to be formatted.
     145 * @param bool $decimals Whether to use decimals. See {@link number_format_i18n()}.
     146 * @return string The formatted number.
    139147 */
    140148function bp_core_number_format( $number, $decimals = false ) {
     
    178186 *
    179187 * @since BuddyPress (1.6)
    180  * @param array $old_args_keys
    181  * @param array $func_args
    182  * @return array $new_args
     188 * @param array $old_args_keys Old argument indexs, keyed to their positions.
     189 * @param array $func_args The parameters passed to the originating function.
     190 * @return array $new_args The parsed arguments.
    183191 */
    184192function bp_core_parse_args_array( $old_args_keys, $func_args ) {
     
    195203
    196204/**
    197  * Sanitize an 'order' parameter for use in building SQL queries
     205 * Sanitize an 'order' parameter for use in building SQL queries.
    198206 *
    199207 * Strings like 'DESC', 'desc', ' desc' will be interpreted into 'DESC'.
    200208 * Everything else becomes 'ASC'.
    201209 *
    202  * @since BuddyPress (1.8)
    203  * @param string $order The 'order' string, as passed to the SQL constructor
    204  * @return string The sanitized value 'DESC' or 'ASC'
     210 * @since BuddyPress (1.8.0)
     211 *
     212 * @param string $order The 'order' string, as passed to the SQL constructor.
     213 * @return string The sanitized value 'DESC' or 'ASC'.
    205214 */
    206215function bp_esc_sql_order( $order = '' ) {
     
    212221 * Are we running username compatibility mode?
    213222 *
    214  * @package BuddyPress
    215  * @since BuddyPress (1.5)
    216  *
    217  * @uses apply_filters() Filter 'bp_is_username_compatibility_mode' to alter
    218  * @return bool False when compatibility mode is disabled (default); true when enabled
     223 * @since BuddyPress (1.5.0)
     224 *
     225 * @uses apply_filters() Filter 'bp_is_username_compatibility_mode' to alter.
    219226 * @todo Move to members component?
     227 *
     228 * @return bool False when compatibility mode is disabled, true when enabled.
     229 *         Default: false.
    220230 */
    221231function bp_is_username_compatibility_mode() {
     
    226236 * Should we use the WP Toolbar?
    227237 *
    228  * The WP Toolbar, introduced in WP 3.1, is fully supported in BuddyPress as of BP 1.5.
    229  * For BP 1.6, the WP Toolbar is the default.
    230  *
    231  * @return bool False when WP Toolbar support is disabled; true when enabled (default)
    232  * @since BuddyPress (1.5)
    233  * @uses apply_filters() Filter 'bp_use_wp_admin_bar' to alter
     238 * The WP Toolbar, introduced in WP 3.1, is fully supported in BuddyPress as
     239 * of BP 1.5. For BP 1.6, the WP Toolbar is the default.
     240 *
     241 * @since BuddyPress (1.5.0)
     242 *
     243 * @uses apply_filters() Filter 'bp_use_wp_admin_bar' to alter.
     244 *
     245 * @return bool False when WP Toolbar support is disabled, true when enabled.
     246 *        Default: true.
    234247 */
    235248function bp_use_wp_admin_bar() {
     
    250263
    251264/**
    252  * Fetches BP pages from the meta table, depending on setup
    253  *
    254  * @package BuddyPress Core
    255  * @since BuddyPress (1.5)
     265 * Fetch a list of BP directory pages from the appropriate meta table.
     266 *
     267 * @since BuddyPress (1.5.0)
     268 *
     269 * @return array|string An array of page IDs, keyed by component names, or an
     270 *         empty string if the list is not found.
    256271 */
    257272function bp_core_get_directory_page_ids() {
     
    271286
    272287/**
    273  * Stores BP pages in the meta table, depending on setup
    274  *
    275  * bp-pages data is stored in site_options (falls back to options on non-MS), in an array keyed by
    276  * blog_id. This allows you to change your bp_get_root_blog_id() and go through the setup process again.
    277  *
    278  * @package BuddyPress Core
    279  * @since BuddyPress (1.5)
    280  *
    281  * @param array $blog_page_ids The IDs of the WP pages corresponding to BP component directories
     288 * Store the list of BP directory pages in the appropriate meta table.
     289 *
     290 * bp-pages data is stored in site_options (falls back to options on non-MS),
     291 * in an array keyed by blog_id. This allows you to change your
     292 * bp_get_root_blog_id() and go through the setup process again.
     293 *
     294 * @since BuddyPress (1.5.0)
     295 *
     296 * @param array $blog_page_ids The IDs of the WP pages corresponding to BP
     297 *        component directories.
    282298 */
    283299function bp_core_update_directory_page_ids( $blog_page_ids ) {
     
    286302
    287303/**
    288  * Get bp-pages names and slugs
    289  *
    290  * @package BuddyPress Core
    291  * @since BuddyPress (1.5)
    292  *
    293  * @return object Page names, IDs, and slugs
     304 * Get names and slugs for BuddyPress component directory pages.
     305 *
     306 * @since BuddyPress (1.5.0).
     307 *
     308 * @return object Page names, IDs, and slugs.
    294309 */
    295310function bp_core_get_directory_pages() {
     
    340355
    341356/**
    342  * Add the pages for the component mapping. These are most often used by components with directories (e.g. groups, members).
    343  *
    344  * @param array $default_components Optional components to create pages for
     357 * Creates necessary directory pages.
     358 *
     359 * Directory pages are those WordPress pages used by BP components to display
     360 * content (eg, the 'groups' page created by BP).
     361 *
     362 * @since BuddyPress (1.7.0)
     363 *
     364 * @param array $default_components Components to create pages for.
    345365 * @param string $existing 'delete' if you want to delete existing page
    346366 *   mappings and replace with new ones. Otherwise existing page mappings
    347  *   are kept, and the gaps filled in with new pages
    348  * @since BuddyPress (1.7)
     367 *   are kept, and the gaps filled in with new pages. Default: 'keepy'.
    349368 */
    350369function bp_core_add_page_mappings( $components, $existing = 'keep' ) {
     
    421440
    422441/**
    423  * Creates a default component slug from a WP page root_slug
     442 * Create a default component slug from a WP page root_slug.
    424443 *
    425444 * Since 1.5, BP components get their root_slug (the slug used immediately
     
    427446 *
    428447 * E.g. if your BP installation at example.com has its members page at
    429  * example.com/community/people, $bp->members->root_slug will be 'community/people'.
     448 * example.com/community/people, $bp->members->root_slug will be
     449 * 'community/people'.
    430450 *
    431451 * By default, this function creates a shorter version of the root_slug for
     
    434454 *
    435455 * Filter on 'bp_core_component_slug_from_root_slug' to override this method
    436  * in general, or define a specific component slug constant (e.g. BP_MEMBERS_SLUG)
    437  * to override specific component slugs.
    438  *
    439  * @package BuddyPress Core
    440  * @since BuddyPress (1.5)
    441  *
    442  * @param string $root_slug The root slug, which comes from $bp->pages->[component]->slug
    443  * @return string The short slug for use in the middle of URLs
     456 * in general, or define a specific component slug constant (e.g.
     457 * BP_MEMBERS_SLUG) to override specific component slugs.
     458 *
     459 * @since BuddyPress (1.5.0)
     460 *
     461 * @param string $root_slug The root slug, which comes from $bp->pages->[component]->slug.
     462 * @return string The short slug for use in the middle of URLs.
    444463 */
    445464function bp_core_component_slug_from_root_slug( $root_slug ) {
     
    451470
    452471/**
    453  * This function originally let plugins add support for pages in the root of the install.
    454  * These root level pages are now handled by actual WordPress pages and this function is now
    455  * a convenience for compatibility with the new method.
    456  *
    457  * @global $bp BuddyPress global settings
    458  * @param string $slug The slug of the component
     472 * Add support for a top-level ("root") component.
     473 *
     474 * This function originally (pre-1.5) let plugins add support for pages in the
     475 * root of the install. These root level pages are now handled by actual
     476 * WordPress pages and this function is now a convenience for compatibility
     477 * with the new method.
     478 *
     479 * @global $bp BuddyPress global settings.
     480 *
     481 * @param string $slug The slug of the component being added to the root list.
    459482 */
    460483function bp_core_add_root_component( $slug ) {
     
    484507}
    485508
     509/**
     510 * Create WordPress pages to be used as BP component directories.
     511 */
    486512function bp_core_create_root_component_page() {
    487513    global $bp;
     
    497523
    498524/**
    499  * Adds illegal names to WP so that root components will not conflict with
    500  * blog names on a subdirectory installation.
     525 * Add illegal blog names to WP so that root components will not conflict with blog names on a subdirectory installation.
    501526 *
    502527 * For example, it would stop someone creating a blog with the slug "groups".
     
    511536
    512537/**
    513  * Returns the domain for the root blog.
    514  * eg: http://domain.com/ OR https://domain.com
    515  *
    516  * @package BuddyPress Core
     538 * Return the domain for the root blog.
     539 *
     540 * eg: http://domain.com OR https://domain.com
     541 *
    517542 * @uses get_blog_option() WordPress function to fetch blog meta.
     543 *
    518544 * @return string The domain URL for the blog.
    519545 */
     
    526552
    527553/**
    528  * Performs a status safe wp_redirect() that is compatible with bp_catch_uri()
    529  *
    530  * @package BuddyPress Core
     554 * Perform a status-safe wp_redirect() that is compatible with BP's URI parser.
     555 *
    531556 * @uses wp_safe_redirect()
     557 *
     558 * @param string $location The redirect URL.
     559 * @param int $status Optional. The numeric code to give in the redirect
     560 *        headers. Default: 302.
    532561 */
    533562function bp_core_redirect( $location, $status = 302 ) {
     
    548577
    549578/**
    550  * Returns the referrer URL without the http(s)://
    551  *
    552  * @package BuddyPress Core
    553  * @return string The referrer URL
     579 * Return the referrer URL without the http(s)://
     580 *
     581 * @return string The referrer URL.
    554582 */
    555583function bp_core_referrer() {
     
    562590 * Get the path of of the current site.
    563591 *
    564  * @package BuddyPress Core
    565  *
    566592 * @global object $current_site
    567  * @return string
     593 *
     594 * @return string URL to the current site.
    568595 */
    569596function bp_core_get_site_path() {
     
    596623
    597624/**
    598  * Get the current GMT time to save into the DB
    599  *
    600  * @package BuddyPress Core
     625 * Get the current GMT time to save into the DB.
     626 *
    601627 * @since BuddyPress (1.2.6)
     628 *
     629 * @param bool $gmt True to use GMT (rather than local) time. Default: true.
     630 * @return string Current time in 'Y-m-d h:i:s' format.
    602631 */
    603632function bp_core_current_time( $gmt = true ) {
     
    609638
    610639/**
     640 * Get an English-language representation of the time elapsed since a given date.
     641 *
    611642 * Based on function created by Dunstan Orchard - http://1976design.com
    612643 *
     
    621652 * interval of 3 minutes 59 seconds.
    622653 *
    623  * @package BuddyPress Core
    624  * @uses apply_filters() Filter 'bp_core_time_since_pre' to bypass BP's calculations
    625  * @uses apply_filters() Filter 'bp_core_time_since' to modify BP's calculations
    626  * @param int $older_date Unix timestamp of date you want to calculate the time since for
    627  * @param int $newer_date Unix timestamp of date to compare older date to. Default false (current time).
    628  * @return string The time since.
     654 * @uses apply_filters() Filter 'bp_core_time_since_pre' to bypass BP's calculations.
     655 * @uses apply_filters() Filter 'bp_core_time_since' to modify BP's calculations.
     656 *
     657 * @param int|string $older_date The earlier time from which you're calculating
     658 *        the time elapsed. Enter either as an integer Unix timestamp, or as a
     659 *        date string of the format 'Y-m-d h:i:s'.
     660 * @param int $newer_date Optional. Unix timestamp of date to compare older
     661 *        date to. Default: false (current time).
     662 * @return string String representing the time since the older date, eg
     663 *         "2 hours and 50 minutes".
    629664 */
    630665function bp_core_time_since( $older_date, $newer_date = false ) {
     
    774809
    775810/**
    776  * Adds a feedback (error/success) message to the WP cookie so it can be
    777  * displayed after the page reloads.
    778  *
    779  * @package BuddyPress Core
    780  *
    781  * @global BuddyPress $bp The one true BuddyPress instance
    782  * @param string $message Feedback to give to user
    783  * @param string $type updated|success|error|warning
     811 * Add a feedback (error/success) message to the WP cookie so it can be displayed after the page reloads.
     812 *
     813 * @global BuddyPress $bp The one true BuddyPress instance.
     814 *
     815 * @param string $message Feedback message to be displayed.
     816 * @param string $type Message type. 'updated', 'success', 'error', 'warning'.
     817 *        Default: 'success'.
    784818 */
    785819function bp_core_add_message( $message, $type = '' ) {
     
    803837
    804838/**
    805  * Checks if there is a feedback message in the WP cookie, if so, adds a
    806  * "template_notices" action so that the message can be parsed into the template
    807  * and displayed to the user.
     839 * Set up the display of the 'template_notices' feedback message.
     840 *
     841 * Checks whether there is a feedback message in the WP cookie and, if so, adds
     842 * a "template_notices" action so that the message can be parsed into the
     843 * template and displayed to the user.
    808844 *
    809845 * After the message is displayed, it removes the message vars from the cookie
    810846 * so that the message is not shown to the user multiple times.
    811847 *
    812  * @package BuddyPress Core
    813  * @global $bp_message The message text
    814  * @global $bp_message_type The type of message (error/success)
     848 * @global BuddyPress $bp BuddyPress global settings object.
    815849 * @uses setcookie() Sets a cookie value for the user.
    816850 */
     
    834868
    835869/**
    836  * Renders a feedback message (either error or success message) to the theme template.
    837  * The hook action 'template_notices' is used to call this function, it is not called directly.
    838  *
    839  * @package BuddyPress Core
    840  * @global BuddyPress $bp The one true BuddyPress instance
     870 * Render the 'template_notices' feedback message.
     871 *
     872 * The hook action 'template_notices' is used to call this function, it is not
     873 * called directly.
     874 *
     875 * @global BuddyPress $bp The one true BuddyPress instance.
    841876 */
    842877function bp_core_render_message() {
     
    863898
    864899/**
    865  * Record user activity to the database. Many functions use a "last active" feature to
    866  * show the length of time since the user was last active.
    867  * This function will update that time as a usermeta setting for the user every 5 minutes.
    868  *
    869  * @package BuddyPress Core
    870  * @global $userdata WordPress user data for the current logged in user.
    871  * @uses bp_update_user_meta() BP function to update user metadata in the usermeta table.
     900 * Listener function for the logged-in user's 'last_activity' metadata.
     901 *
     902 * Many functions use a "last active" feature to show the length of time since
     903 * the user was last active. This function will update that time as a usermeta
     904 * setting for the user every 5 minutes while the user is actively browsing the
     905 * site.
     906 *
     907 * @uses bp_update_user_meta() BP function to update user metadata in the
     908 *       usermeta table.
     909 *
     910 * @return bool|null Returns false if there is nothing to do.
    872911 */
    873912function bp_core_record_activity() {
     
    901940
    902941/**
    903  * Formats last activity based on time since date given.
    904  *
    905  * @package BuddyPress Core
    906  * @param string $last_activity_date The date of last activity.
    907  * @param string $string
    908  * @uses bp_core_time_since() This function will return an English representation of the time elapsed.
     942 * Format last activity string based on time since date given.
     943 *
     944 * @uses bp_core_time_since() This function will return an English
     945 *       representation of the time elapsed.
     946 *
     947 * @param int|string $last_activity_date The date of last activity.
     948 * @param string $string A sprintf()-able statement of the form '% ago'.
     949 * @return string $last_active A string of the form '3 years ago'.
    909950 */
    910951function bp_core_get_last_activity( $last_activity_date, $string ) {
     
    923964 * Get the meta_key for a given piece of user metadata
    924965 *
    925  * BuddyPress stores a number of pieces of userdata in the WordPress central usermeta table. In
    926  * order to allow plugins to enable multiple instances of BuddyPress on a single WP installation,
    927  * BP's usermeta keys are filtered with this function, so that they can be altered on the fly.
    928  *
    929  * Plugin authors should use BP's _user_meta() functions, which bakes in bp_get_user_meta_key().
     966 * BuddyPress stores a number of pieces of userdata in the WordPress central
     967 * usermeta table. In order to allow plugins to enable multiple instances of
     968 * BuddyPress on a single WP installation, BP's usermeta keys are filtered
     969 * through this function, so that they can be altered on the fly.
     970 *
     971 * Plugin authors should use BP's _user_meta() functions, which bakes in
     972 * bp_get_user_meta_key():
    930973 *    $last_active = bp_get_user_meta( $user_id, 'last_activity', true );
    931  * If you have to use WP's _user_meta() functions for some reason, you should use this function, eg
     974 * If you must use WP's _user_meta() functions directly for some reason, you
     975 * should use this function to determine the $key parameter, eg
    932976 *    $last_active = get_user_meta( $user_id, bp_get_user_meta_key( 'last_activity' ), true );
    933977 * If using the WP functions, do not not hardcode your meta keys.
    934978 *
    935  * @package BuddyPress
    936  * @since BuddyPress (1.5)
    937  *
    938  * @uses apply_filters() Filter bp_get_user_meta_key to modify keys individually
    939  * @param string $key
    940  * @return string $key
     979 * @since BuddyPress (1.5.0)
     980 *
     981 * @uses apply_filters() Filter 'bp_get_user_meta_key' to modify keys individually.
     982 *
     983 * @param string $key The usermeta meta_key.
     984 * @return string $key The usermeta meta_key.
    941985 */
    942986function bp_get_user_meta_key( $key = false ) {
     
    945989
    946990/**
    947  * Get a piece of usermeta
    948  *
    949  * This is a wrapper for get_user_meta() that allows for easy use of bp_get_user_meta_key(), thereby
    950  * increasing compatibility with non-standard BP setups.
    951  *
    952  * @package BuddyPress
    953  * @since BuddyPress (1.5)
    954  *
    955  * @uses bp_get_user_meta_key() For a filterable version of the meta key
    956  * @uses get_user_meta() See get_user_meta() docs for more details on parameters
    957  * @param int $user_id The id of the user whose meta you're fetching
     991 * Get a piece of usermeta.
     992 *
     993 * This is a wrapper for get_user_meta() that allows for easy use of
     994 * bp_get_user_meta_key(), thereby increasing compatibility with non-standard
     995 * BP setups.
     996 *
     997 * @since BuddyPress (1.5.0)
     998 *
     999 * @see get_user_meta() For complete details about parameters and return values.
     1000 * @uses bp_get_user_meta_key() For a filterable version of the meta key.
     1001 *
     1002 * @param int $user_id The ID of the user whose meta you're fetching.
    9581003 * @param string $key The meta key to retrieve.
    9591004 * @param bool $single Whether to return a single value.
    9601005 * @return mixed Will be an array if $single is false. Will be value of meta data field if $single
    961  *  is true.
     1006 *         is true.
    9621007 */
    9631008function bp_get_user_meta( $user_id, $key, $single = false ) {
     
    9661011
    9671012/**
    968  * Update a piece of usermeta
    969  *
    970  * This is a wrapper for update_user_meta() that allows for easy use of bp_get_user_meta_key(),
    971  * thereby increasing compatibility with non-standard BP setups.
    972  *
    973  * @package BuddyPress
    974  * @since BuddyPress (1.5)
    975  *
    976  * @uses bp_get_user_meta_key() For a filterable version of the meta key
    977  * @uses update_user_meta() See update_user_meta() docs for more details on parameters
    978  * @param int $user_id The id of the user whose meta you're setting
     1013 * Update a piece of usermeta.
     1014 *
     1015 * This is a wrapper for update_user_meta() that allows for easy use of
     1016 * bp_get_user_meta_key(), thereby increasing compatibility with non-standard
     1017 * BP setups.
     1018 *
     1019 * @since BuddyPress (1.5.0)
     1020 *
     1021 * @see update_user_meta() For complete details about parameters and return values.
     1022 * @uses bp_get_user_meta_key() For a filterable version of the meta key.
     1023 *
     1024 * @param int $user_id The ID of the user whose meta you're setting.
    9791025 * @param string $key The meta key to set.
    9801026 * @param mixed $value Metadata value.
    9811027 * @param mixed $prev_value Optional. Previous value to check before removing.
    982  * @return bool False on failure, true if success.
     1028 * @return bool False on failure, true on success.
    9831029 */
    9841030function bp_update_user_meta( $user_id, $key, $value, $prev_value = '' ) {
     
    9871033
    9881034/**
    989  * Delete a piece of usermeta
    990  *
    991  * This is a wrapper for delete_user_meta() that allows for easy use of bp_get_user_meta_key(),
    992  * thereby increasing compatibility with non-standard BP setups.
    993  *
    994  * @package BuddyPress
    995  * @since BuddyPress (1.5)
    996  *
    997  * @uses bp_get_user_meta_key() For a filterable version of the meta key
    998  * @uses delete_user_meta() See delete_user_meta() docs for more details on parameters
    999  * @param int $user_id The id of the user whose meta you're deleting
     1035 * Delete a piece of usermeta.
     1036 *
     1037 * This is a wrapper for delete_user_meta() that allows for easy use of
     1038 * bp_get_user_meta_key(), thereby increasing compatibility with non-standard
     1039 * BP setups.
     1040 *
     1041 * @since BuddyPress (1.5.0)
     1042 *
     1043 * @see delete_user_meta() For complete details about parameters and return values.
     1044 * @uses bp_get_user_meta_key() For a filterable version of the meta key.
     1045 *
     1046 * @param int $user_id The ID of the user whose meta you're deleting.
    10001047 * @param string $key The meta key to delete.
    10011048 * @param mixed $value Optional. Metadata value.
     
    10111058 * Initializes {@link BP_Embed} after everything is loaded.
    10121059 *
    1013  * @global object $bp BuddyPress global settings
    1014  * @package BuddyPress Core
    1015  * @since BuddyPress (1.5)
     1060 * @since BuddyPress (1.5.0)
     1061 *
     1062 * @global BuddyPress $bp BuddyPress global settings.
    10161063 */
    10171064function bp_embed_init() {
     
    10261073 * Are oembeds allowed in activity items?
    10271074 *
    1028  * @return bool False when activity embed support is disabled; true when enabled (default)
    1029  * @since BuddyPress (1.5)
     1075 * @since BuddyPress (1.5.0)
     1076 *
     1077 * @return bool False when activity embed support is disabled; true when
     1078 *         enabled. Default: true.
    10301079 */
    10311080function bp_use_embed_in_activity() {
     
    10361085 * Are oembeds allwoed in activity replies?
    10371086 *
    1038  * @return bool False when activity replies embed support is disabled; true when enabled (default)
    1039  * @since BuddyPress (1.5)
     1087 * @since BuddyPress (1.5.0)
     1088 *
     1089 * @return bool False when activity replies embed support is disabled; true
     1090 *         when enabled. Default: true.
    10401091 */
    10411092function bp_use_embed_in_activity_replies() {
     
    10461097 * Are oembeds allowed in forum posts?
    10471098 *
    1048  * @return bool False when form post embed support is disabled; true when enabled (default)
    1049  * @since BuddyPress (1.5)
     1099 * @since BuddyPress (1.5.0)
     1100 *
     1101 * @return bool False when forum post embed support is disabled; true when
     1102 *         enabled. Default: true.
    10501103 */
    10511104function bp_use_embed_in_forum_posts() {
     
    10561109 * Are oembeds allowed in private messages?
    10571110 *
    1058  * @return bool False when form post embed support is disabled; true when enabled (default)
    1059  * @since BuddyPress (1.5)
     1111 * @since BuddyPress (1.5.0)
     1112 *
     1113 * @return bool False when private message embed support is disabled; true when
     1114 *         enabled. Default: true.
    10601115 */
    10611116function bp_use_embed_in_private_messages() {
     
    10661121
    10671122/**
    1068  * Output the correct URL based on BuddyPress and WordPress configuration
    1069  *
    1070  * @package BuddyPress
    1071  * @since BuddyPress (1.5)
    1072  *
    1073  * @param string $path
    1074  * @param string $scheme
    1075  *
    1076  * @uses bp_get_admin_url()
     1123 * Output the correct admin URL based on BuddyPress and WordPress configuration.
     1124 *
     1125 * @since BuddyPress (1.5.0)
     1126 *
     1127 * @see bp_get_admin_url() For description of parameters.
     1128 *
     1129 * @param string $path See {@link bp_get_admin_url()}.
     1130 * @param string $scheme See {@link bp_get_admin_url()}.
    10771131 */
    10781132function bp_admin_url( $path = '', $scheme = 'admin' ) {
     
    10801134}
    10811135    /**
    1082      * Return the correct URL based on BuddyPress and WordPress configuration
     1136     * Return the correct admin URL based on BuddyPress and WordPress configuration.
    10831137     *
    1084      * @package BuddyPress
    1085      * @since BuddyPress (1.5)
    1086      *
    1087      * @param string $path
    1088      * @param string $scheme
     1138     * @since BuddyPress (1.5.0)
    10891139     *
    10901140     * @uses bp_core_do_network_admin()
    10911141     * @uses network_admin_url()
    10921142     * @uses admin_url()
     1143     *
     1144     * @param string $path Optional. The sub-path under /wp-admin to be
     1145     *        appended to the admin URL.
     1146     * @param string $scheme The scheme to use. Default is 'admin', which
     1147     *        obeys {@link force_ssl_admin()} and {@link is_ssl()}. 'http'
     1148     *        or 'https' can be passed to force those schemes.
     1149     * @return string Admin url link with optional path appended.
    10931150     */
    10941151    function bp_get_admin_url( $path = '', $scheme = 'admin' ) {
     
    11071164
    11081165/**
    1109  * Should BuddyPress appear in network admin, or site admin?
     1166 * Should BuddyPress appear in network admin (vs a single site Dashboard)?
    11101167 *
    11111168 * Because BuddyPress can be installed in multiple ways and with multiple
     
    11131170 * to hook into certain areas of WordPress's admin.
    11141171 *
    1115  * This function defaults to BuddyPress being network activated.
    1116  * @since BuddyPress (1.5)
     1172 * @since BuddyPress (1.5.0)
    11171173 *
    11181174 * @uses bp_is_network_activated()
    11191175 * @uses bp_is_multiblog_mode()
    1120  * @return boolean
     1176 *
     1177 * @return bool True if the BP admin screen should appear in the Network Admin,
     1178 *         otherwise false.
    11211179 */
    11221180function bp_core_do_network_admin() {
     
    11311189}
    11321190
     1191/**
     1192 * Return the action name that BuddyPress nav setup callbacks should be hooked to.
     1193 *
     1194 * Functions used to set up BP Dashboard pages (wrapping such admin-panel
     1195 * functions as add_submenu_page()) should use bp_core_admin_hook() for the
     1196 * first parameter in add_action(). BuddyPress will then determine
     1197 * automatically whether to load the panels in the Network Admin. Ie:
     1198 *
     1199 *     add_action( bp_core_admin_hook(), 'myplugin_dashboard_panel_setup' );
     1200 *
     1201 * @return string $hook The proper hook ('network_admin_menu' or 'admin_menu').
     1202 */
    11331203function bp_core_admin_hook() {
    11341204    $hook = bp_core_do_network_admin() ? 'network_admin_menu' : 'admin_menu';
     
    11401210
    11411211/**
    1142  * Is this the root blog ID?
    1143  *
    1144  * @package BuddyPress
    1145  * @since BuddyPress (1.5)
    1146  *
    1147  * @param int $blog_id Optional. Defaults to the current blog id.
     1212 * Is this the root blog?
     1213 *
     1214 * @since BuddyPress (1.5.0)
     1215 *
     1216 * @param int $blog_id Optional. Default: the ID of the current blog.
    11481217 * @return bool $is_root_blog Returns true if this is bp_get_root_blog_id().
    11491218 */
     
    11651234
    11661235/**
    1167  * Is this bp_get_root_blog_id()?
    1168  *
    1169  * @package BuddyPress
    1170  * @since BuddyPress (1.5)
    1171  *
    1172  * @return int Return the root site ID
     1236 * Get the ID of the root blog.
     1237 *
     1238 * The "root blog" is the blog on a WordPress network where BuddyPress content
     1239 * appears (where member profile URLs resolve, where a given theme is loaded,
     1240 * etc.).
     1241 *
     1242 * @since BuddyPress (1.5.0)
     1243 *
     1244 * @return int The root site ID.
    11731245 */
    11741246function bp_get_root_blog_id() {
     
    12011273 * down this road unless you specifically need to.
    12021274 *
    1203  * @package BuddyPress
    1204  * @since BuddyPress (1.5)
    1205  *
    1206  * @uses apply_filters() Filter 'bp_is_multiblog_mode' to alter
    1207  * @return bool False when multiblog mode is disabled (default); true when enabled
     1275 * @since BuddyPress (1.5.0)
     1276 *
     1277 * @uses apply_filters() Filter 'bp_is_multiblog_mode' to alter.
     1278 *
     1279 * @return bool False when multiblog mode is disabled; true when enabled.
     1280 *         Default: false.
    12081281 */
    12091282function bp_is_multiblog_mode() {
     
    12321305 * Used to determine admin menu placement, and where settings and options are
    12331306 * stored. If you're being *really* clever and manually pulling BuddyPress in
    1234  * with an mu-plugin or some other method, you'll want to
    1235  *
    1236  * @since BuddyPress (1.7)
    1237  * @return boolean
     1307 * with an mu-plugin or some other method, you'll want to filter
     1308 * 'bp_is_network_activated' and override the auto-determined value.
     1309 *
     1310 * @since BuddyPress (1.7.0)
     1311 *
     1312 * @return bool True if BuddyPress is network activated.
    12381313 */
    12391314function bp_is_network_activated() {
     
    12561331
    12571332/**
    1258  * Set the $bp->is_directory global
    1259  *
    1260  * @global BuddyPress $bp The one true BuddyPress instance
    1261  * @param bool $is_directory
    1262  * @param string $component
     1333 * Set the $bp->is_directory global.
     1334 *
     1335 * @global BuddyPress $bp The one true BuddyPress instance.
     1336 *
     1337 * @param bool $is_directory Optional. Default: false.
     1338 * @param string $component Optional. Component name. Default: the current
     1339 *        component.
    12631340 */
    12641341function bp_update_is_directory( $is_directory = false, $component = '' ) {
     
    12721349
    12731350/**
    1274  * Set the $bp->is_item_admin global
    1275  *
    1276  * @global BuddyPress $bp The one true BuddyPress instance
    1277  * @param bool $is_item_admin
    1278  * @param string $component
     1351 * Set the $bp->is_item_admin global.
     1352 *
     1353 * @global BuddyPress $bp The one true BuddyPress instance.
     1354 *
     1355 * @param bool $is_item_admin Optional. Default: false.
     1356 * @param string $component. Optional. Component name. Default: the current
     1357 *        component.
    12791358 */
    12801359function bp_update_is_item_admin( $is_item_admin = false, $component = '' ) {
     
    12881367
    12891368/**
    1290  * Set the $bp->is_item_mod global
    1291  *
    1292  * @global BuddyPress $bp The one true BuddyPress instance
    1293  * @param bool $is_item_mod
    1294  * @param string $component
     1369 * Set the $bp->is_item_mod global.
     1370 *
     1371 * @global BuddyPress $bp The one true BuddyPress instance.
     1372 *
     1373 * @param bool $is_item_mod Optional. Default: false.
     1374 * @param string $component. Optional. Component name. Default: the current
     1375 *        component.
    12951376 */
    12961377function bp_update_is_item_mod( $is_item_mod = false, $component = '' ) {
     
    13041385
    13051386/**
    1306  * Trigger a 404
    1307  *
    1308  * @global BuddyPress $bp The one true BuddyPress instance
    1309  * @global WP_Query $wp_query WordPress query object
    1310  * @param string $redirect If 'remove_canonical_direct', remove WordPress' "helpful" redirect_canonical action.
    1311  * @since BuddyPress (1.5)
     1387 * Trigger a 404.
     1388 *
     1389 * @since BuddyPress (1.5.0)
     1390 *
     1391 * @global WP_Query $wp_query WordPress query object.
     1392 *
     1393 * @param string $redirect If 'remove_canonical_direct', remove WordPress'
     1394 *        "helpful" redirect_canonical action. Default: 'remove_canonical_redirect'.
    13121395 */
    13131396function bp_do_404( $redirect = 'remove_canonical_direct' ) {
     
    13311414 * To avoid security exploits within the theme.
    13321415 *
    1333  * @since BuddyPress (1.6)
     1416 * @since BuddyPress (1.6.0)
    13341417 *
    13351418 * @uses do_action() Calls 'bp_verify_nonce_request' on $action.
    1336  * @param string $action Action nonce
    1337  * @param string $query_arg where to look for nonce in $_REQUEST
     1419 *
     1420 * @param string $action Action nonce.
     1421 * @param string $query_arg where to look for nonce in $_REQUEST.
     1422 * @return bool True if the nonce is verified, otherwise false.
    13381423 */
    13391424function bp_verify_nonce_request( $action = '', $query_arg = '_wpnonce' ) {
     
    13601445
    13611446/**
    1362  * Load the buddypress translation file for current language
    1363  *
    1364  * @package BuddyPress Core
     1447 * Load the buddypress translation file for current language.
     1448 *
     1449 * @see load_textdomain() for a description of return values.
     1450 *
     1451 * @return bool True on success, false on failure.
    13651452 */
    13661453function bp_core_load_buddypress_textdomain() {
     
    13801467
    13811468/**
    1382  * A javascript free implementation of the search functions in BuddyPress
    1383  *
    1384  * @package BuddyPress Core
     1469 * A javascript-free implementation of the search functions in BuddyPress.
     1470 *
    13851471 * @param string $slug The slug to redirect to for searching.
    13861472 */
     
    14461532
    14471533/**
    1448  * Prints the generation time in the footer of the site.
    1449  *
    1450  * @package BuddyPress Core
     1534 * Print the generation time in the footer of the site.
    14511535 */
    14521536function bp_core_print_generation_time() {
Note: See TracChangeset for help on using the changeset viewer.