Skip to:
Content

BuddyPress.org

Changeset 9135


Ignore:
Timestamp:
11/11/2014 08:12:02 PM (10 years ago)
Author:
boonebgorges
Message:

Add hook documentation in bp-activity-functions.php.

Props tw2113.
See #5938.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/bp-activity/bp-activity-functions.php

    r9054 r9135  
    4646 */
    4747function bp_activity_do_mentions() {
     48
     49    /**
     50     * Filters whether or not mentions are enabled.
     51     *
     52     * @since BuddyPress (1.8.0)
     53     *
     54     * @param bool $enabled True to enable mentions, false to disable.
     55     */
    4856    return (bool) apply_filters( 'bp_activity_do_mentions', true );
    4957}
    … …  
    6270        ( bp_is_activity_component() || bp_is_blog_page() && is_singular() && comments_open() || is_admin() );
    6371
     72    /**
     73     * Filters whether or not BuddyPress should load mentions scripts and assets.
     74     *
     75     * @since BuddyPress (2.1.0)
     76     *
     77     * @param bool $retval True to load mentions assets, false otherwise.
     78     */
    6479    return (bool) apply_filters( 'bp_activity_maybe_load_mentions_scripts', $retval );
    6580}
    … …  
    334349    }
    335350
     351    /**
     352     * Filters the action type being set for the current activity item.
     353     *
     354     * @since BuddyPress (1.1.0)
     355     *
     356     * @param array    $array Array of arguments for action type being set.
     357     * @param string   $component_id ID of the current component being set.
     358     * @param string   $type Action type being set.
     359     * @param string   $description Action description for action being set.
     360     * @param callable $format_callback Callback for formatting the action string.
     361     * @param string   $label String to describe this action in the activity stream filter dropdown.
     362     * @param array    $context Activity stream contexts where the filter should appear. 'activity', 'member',
     363     *                 'member_groups', 'group'.
     364     */
    336365    $bp->activity->actions->{$component_id}->{$type} = apply_filters( 'bp_activity_set_action', array(
    337366        'key'             => $type,
    … …  
    368397        : false;
    369398
     399    /**
     400     * Filters the current action by component and key.
     401     *
     402     * @since BuddyPress (1.1.0)
     403     *
     404     * @param string|bool $retval The action key.
     405     * @param string      $component_id The unique string ID of the component.
     406     * @param string      $key The action key.
     407     */
    370408    return apply_filters( 'bp_activity_get_action', $retval, $component_id, $key );
    371409}
    … …  
    393431    unset( $actions['friends_register_activity_action'] );
    394432
     433    /**
     434     * Filters the available activity types.
     435     *
     436     * @since BuddyPress (1.7.0)
     437     *
     438     * @param array $actions Array of registered activity types.
     439     */
    395440    return apply_filters( 'bp_activity_get_types', $actions );
    396441}
    … …  
    419464    $favs = bp_get_user_meta( $user_id, 'bp_favorite_activities', true );
    420465
     466    /**
     467     * Filters the favorited activity items for a specified user.
     468     *
     469     * @since BuddyPress (1.2.0)
     470     *
     471     * @param array $favs Array of user's favorited activity items.
     472     */
    421473    return apply_filters( 'bp_activity_get_user_favorites', $favs );
    422474}
    … …  
    474526    if ( bp_activity_update_meta( $activity_id, 'favorite_count', $fav_count ) ) {
    475527
    476         // Execute additional code
     528        /**
     529         * Fires if bp_activity_update_meta() for favorite_count is successful and before returning a true value for success.
     530         *
     531         * @since BuddyPress (1.2.1)
     532         *
     533         * @param int $activity_id ID of the activity item being favorited.
     534         * @param int $user_id ID of the user doing the favoriting.
     535         */
    477536        do_action( 'bp_activity_add_user_favorite', $activity_id, $user_id );
    478537
    … …  
    482541    // Saving meta was unsuccessful for an unknown reason
    483542    } else {
    484         // Execute additional code
     543
     544        /**
     545         * Fires if bp_activity_update_meta() for favorite_count is unsuccessful and before returning a false value for failure.
     546         *
     547         * @since BuddyPress (1.5.0)
     548         *
     549         * @param int $activity_id ID of the activity item being favorited.
     550         * @param int $user_id ID of the user doing the favoriting.
     551         */
    485552        do_action( 'bp_activity_add_user_favorite_fail', $activity_id, $user_id );
    486553
    … …  
    539606            if ( bp_update_user_meta( $user_id, 'bp_favorite_activities', $my_favs ) ) {
    540607
    541                 // Execute additional code
     608                /**
     609                 * Fires if bp_update_user_meta() is successful and before returning a true value for success.
     610                 *
     611                 * @since BuddyPress (1.2.1)
     612                 *
     613                 * @param int $activity_id ID of the activity item being unfavorited.
     614                 * @param int $user_id ID of the user doing the unfavoriting.
     615                 */
    542616                do_action( 'bp_activity_remove_user_favorite', $activity_id, $user_id );
    543617
    … …  
    573647 */
    574648function bp_activity_check_exists_by_content( $content ) {
     649
     650    /**
     651     * Filters the results of the check for whether an activity item exists by specified content.
     652     *
     653     * @since BuddyPress (1.1.0)
     654     *
     655     * @param BP_Activity_Activity $content_exists ID of the activity if found, else null.
     656     */
    575657    return apply_filters( 'bp_activity_check_exists_by_content', BP_Activity_Activity::check_exists_by_content( $content ) );
    576658}
    … …  
    587669 */
    588670function bp_activity_get_last_updated() {
     671
     672    /**
     673     * Filters the value for the last updated time for an activity item.
     674     *
     675     * @since BuddyPress (1.1.0)
     676     *
     677     * @param BP_Activity_Activity $last_updated Date last updated.
     678     */
    589679    return apply_filters( 'bp_activity_get_last_updated', BP_Activity_Activity::get_last_updated() );
    590680}
    … …  
    677767    remove_filter( 'query', 'bp_filter_metaid_column_name' );
    678768
    679     // Filter result before returning
     769    /**
     770     * Filters the metadata for a specified activity item.
     771     *
     772     * @since BuddyPress (1.5.0)
     773     *
     774     * @param mixed  $retval The meta values for the activity item.
     775     * @param int    $activity_id ID of the activity item.
     776     * @param string $meta_key Meta key for the value being requested.
     777     * @param bool   $single Whether to return one matched meta key row or all.
     778     */
    680779    return apply_filters( 'bp_activity_get_meta', $retval, $activity_id, $meta_key, $single );
    681780}
    … …  
    758857    do_action( 'bp_activity_remove_data', $user_id ); // Deprecated! Do not use!
    759858
    760     // Use this going forward
     859    /**
     860     * Fires after the removal of all of a user's activity data.
     861     *
     862     * @since BuddyPress (1.5.0)
     863     *
     864     * @param int $user_id ID of the user being deleted.
     865     */
    761866    do_action( 'bp_activity_remove_all_user_data', $user_id );
    762867}
    … …  
    821926    $wpdb->query( $wpdb->prepare( "UPDATE {$bp->activity->table_name} SET is_spam = 1 WHERE user_id = %d", $user_id ) );
    822927
    823     // Call an action for plugins to use
     928    /**
     929     * Fires after all activity data from a user has been marked as spam.
     930     *
     931     * @since BuddyPress (1.6.0)
     932     *
     933     * @param int   $user_id ID of the user whose activity is being marked as spam.
     934     * @param array $activities Array of activity items being marked as spam.
     935     */
    824936    do_action( 'bp_activity_spam_all_user_data', $user_id, $activities['activities'] );
    825937}
    … …  
    881993    }
    882994
    883     // Mark all of this user's activities as spam
     995    // Mark all of this user's activities as not spam
    884996    $wpdb->query( $wpdb->prepare( "UPDATE {$bp->activity->table_name} SET is_spam = 0 WHERE user_id = %d", $user_id ) );
    885997
    886     // Call an action for plugins to use
     998    /**
     999     * Fires after all activity data from a user has been marked as ham.
     1000     *
     1001     * @since BuddyPress (1.6.0)
     1002     *
     1003     * @param int   $user_id ID of the user whose activity is being marked as ham.
     1004     * @param array $activities Array of activity items being marked as ham.
     1005     */
    8871006    do_action( 'bp_activity_ham_all_user_data', $user_id, $activities['activities'] );
    8881007}
    … …  
    9141033    );
    9151034
     1035    /**
     1036     * Fires at the end of the activity actions registration.
     1037     *
     1038     * Allows plugin authors to add their own activity actions alongside the core actions.
     1039     *
     1040     * @since BuddyPress (1.6.0)
     1041     */
    9161042    do_action( 'bp_activity_register_activity_actions' );
    9171043
    … …  
    9431069    add_filter( 'bp_activity_generate_action_string', buddypress()->activity->actions->{$activity->component}->{$activity->type}['format_callback'], 10, 2 );
    9441070
    945     // Generate the action string (run through the filter defined above)
     1071    /**
     1072     * Filters the string for the activity action being returned.
     1073     *
     1074     * @since BuddyPress (2.0.0)
     1075     *
     1076     * @param BP_Activity_Activity $action Action string being requested.
     1077     * @param BP_Activity_Activity $activity Activity item object.
     1078     */
    9461079    $action = apply_filters( 'bp_activity_generate_action_string', $activity->action, $activity );
    9471080
    … …  
    9631096function bp_activity_format_activity_action_activity_update( $action, $activity ) {
    9641097    $action = sprintf( __( '%s posted an update', 'buddypress' ), bp_core_get_userlink( $activity->user_id ) );
     1098
     1099    /**
     1100     * Filters the formatted activity action update string.
     1101     *
     1102     * @since BuddyPress (1.2.0)
     1103     *
     1104     * @param string               $action Activity action string value.
     1105     * @param BP_Activity_Activity $activity Activity item object.
     1106     */
    9651107    return apply_filters( 'bp_activity_new_update_action', $action, $activity );
    9661108}
    … …  
    9771119function bp_activity_format_activity_action_activity_comment( $action, $activity ) {
    9781120    $action = sprintf( __( '%s posted a new activity comment', 'buddypress' ), bp_core_get_userlink( $activity->user_id ) );
     1121
     1122    /**
     1123     * Filters the formatted activity action comment string.
     1124     *
     1125     * @since BuddyPress (1.2.0)
     1126     *
     1127     * @param string               $action Activity action string value.
     1128     * @param BP_Activity_Activity $activity Activity item object.
     1129     */
    9791130    return apply_filters( 'bp_activity_comment_action', $action, $activity );
    9801131}
    … …  
    10851236    }
    10861237
     1238    /**
     1239     * Filters the requested activity item(s).
     1240     *
     1241     * @since BuddyPress (1.2.0)
     1242     *
     1243     * @param BP_Activity_Activity $activity Requested activity object.
     1244     * @param array                $r Arguments used for the activity query.
     1245     */
    10871246    return apply_filters_ref_array( 'bp_activity_get', array( &$activity, &$r ) );
    10881247}
    … …  
    11321291    );
    11331292
     1293    /**
     1294     * Filters the requested specific activity item.
     1295     *
     1296     * @since BuddyPress (1.2.0)
     1297     *
     1298     * @param BP_Activity_Activity $activity Requested activity object.
     1299     * @param array                $args Original passed in arguments.
     1300     * @param array                $get_args Constructed arguments used with request.
     1301     */
    11341302    return apply_filters( 'bp_activity_get_specific', BP_Activity_Activity::get( $get_args ), $args, $get_args );
    11351303}
    … …  
    12341402
    12351403    wp_cache_delete( 'bp_activity_sitewide_front', 'bp' );
     1404
     1405    /**
     1406     * Fires at the end of the execution of adding a new activity item, before returning the new activity item ID.
     1407     *
     1408     * @since BuddyPress (1.1.0)
     1409     *
     1410     * @param array $r Array of parsed arguments for the activity item being added.
     1411     */
    12361412    do_action( 'bp_activity_add', $r );
    12371413
    … …  
    12801456    $primary_link     = bp_core_get_userlink( $r['user_id'], false, true );
    12811457
     1458    /**
     1459     * Filters the new activity content for current activity item.
     1460     *
     1461     * @since BuddyPress (1.2.0)
     1462     *
     1463     * @param string $activity_content Activity content posted by user.
     1464     */
     1465    $add_content = apply_filters( 'bp_activity_new_update_content', $activity_content );
     1466
     1467    /**
     1468     * Filters the activity primary link for current activity item.
     1469     *
     1470     * @since BuddyPress (1.2.0)
     1471     *
     1472     * @param string $primary_link Link to the profile for the user who posted the activity.
     1473     */
     1474    $add_primary_link = apply_filters( 'bp_activity_new_update_primary_link', $primary_link );
     1475
    12821476    // Now write the values
    12831477    $activity_id = bp_activity_add( array(
    12841478        'user_id'      => $r['user_id'],
    1285         'content'      => apply_filters( 'bp_activity_new_update_content', $activity_content ),
    1286         'primary_link' => apply_filters( 'bp_activity_new_update_primary_link', $primary_link ),
     1479        'content'      => $add_content,
     1480        'primary_link' => $add_primary_link,
    12871481        'component'    => buddypress()->activity->id,
    12881482        'type'         => 'activity_update',
    12891483    ) );
    12901484
     1485    /**
     1486     * Filters the latest update content for the activity item.
     1487     *
     1488     * @since BuddyPress (1.6.0)
     1489     *
     1490     * @param string $r Content of the activity update.
     1491     * @param string $activity_content Content of the activity update.
     1492     */
    12911493    $activity_content = apply_filters( 'bp_activity_latest_update_content', $r['content'], $activity_content );
    12921494
    … …  
    12971499    ) );
    12981500
     1501    /**
     1502     * Fires at the end of an activity post update, before returning the updated activity item ID.
     1503     *
     1504     * @since BuddyPress (1.2.0)
     1505     *
     1506     * @param string $content Content of the activity post update.
     1507     * @param int    $user_id ID of the user posting the activity update.
     1508     * @param int    $activity_id ID of the activity item being updated.
     1509     */
    12991510    do_action( 'bp_activity_posted_update', $r['content'], $r['user_id'], $activity_id );
    13001511
    … …  
    13751586    $is_hidden = ( (int) $activity->hide_sitewide ) ? 1 : 0;
    13761587
     1588    /**
     1589     * Filters the content of a new comment.
     1590     *
     1591     * @since BuddyPress (1.2.0)
     1592     *
     1593     * @param string $r Content for the newly posted comment.
     1594     */
     1595    $comment_content = apply_filters( 'bp_activity_comment_content', $r['content'] );
     1596
    13771597    // Insert the activity comment
    13781598    $comment_id = bp_activity_add( array(
    13791599        'id'                => $r['id'],
    1380         'content'           => apply_filters( 'bp_activity_comment_content', $r['content'] ),
     1600        'content'           => $comment_content,
    13811601        'component'         => buddypress()->activity->id,
    13821602        'type'              => 'activity_comment',
    … …  
    13991619    wp_cache_delete( $activity_id, 'bp_activity' );
    14001620
     1621    /**
     1622     * Fires near the end of an activity comment posting, before the returning of the comment ID.
     1623     *
     1624     * @since BuddyPress (1.2.0)
     1625     *
     1626     * @param int   $comment_id ID of the newly posted activity comment.
     1627     * @param array $r Array of parsed comment arguments.
     1628     * @param int   $activity ID of the activity item being commented on.
     1629     */
    14011630    do_action( 'bp_activity_comment_posted', $comment_id, $r, $activity );
    14021631
    … …  
    14351664    ) );
    14361665
     1666    /**
     1667     * Filters the activity ID being requested.
     1668     *
     1669     * @since BuddyPress (1.2.0)
     1670     *
     1671     * @param BP_Activity_Activity ID returned by BP_Activity_Activity get_id() method with provided arguments.
     1672     */
    14371673    return apply_filters( 'bp_activity_get_activity_id', BP_Activity_Activity::get_id(
    14381674        $r['user_id'],
    … …  
    14961732    ) );
    14971733
     1734    /**
     1735     * Fires before an activity item proceeds to be deleted.
     1736     *
     1737     * @since BuddyPress (1.5.0)
     1738     *
     1739     * @param array $args Array of arguments to be used with the activity deletion.
     1740     */
    14981741    do_action( 'bp_before_activity_delete', $args );
    14991742
    … …  
    15181761    }
    15191762
     1763    /**
     1764     * Fires after the activity item has been deleted.
     1765     *
     1766     * @since BuddyPress (1.0.0)
     1767     *
     1768     * @param array $args Array of arguments used with the activity deletion.
     1769     */
    15201770    do_action( 'bp_activity_delete', $args );
     1771
     1772    /**
     1773     * Fires after the activity item has been deleted.
     1774     *
     1775     * @since BuddyPress (1.2.0)
     1776     *
     1777     * @param array $activity_ids_deleted Array of affected activity item IDs.
     1778     */
    15211779    do_action( 'bp_activity_deleted_activities', $activity_ids_deleted );
    15221780
    … …  
    15321790     *
    15331791     * @since BuddyPress (1.1.0)
    1534      * @deprecated BuddyPress (1.2)
     1792     * @deprecated BuddyPress (1.2.0)
    15351793     *
    15361794     * @uses wp_parse_args()
    … …  
    15751833     *
    15761834     * @since BuddyPress (1.1.0)
    1577      * @deprecated BuddyPress (1.2)
     1835     * @deprecated BuddyPress (1.2.0)
    15781836     *
    15791837     * @uses bp_activity_delete()
    … …  
    16001858     *
    16011859     * @since BuddyPress (1.1.0)
    1602      * @deprecated BuddyPress (1.2)
     1860     * @deprecated BuddyPress (1.2.0)
    16031861     *
    16041862     * @uses bp_activity_delete()
    … …  
    16361894 */
    16371895function bp_activity_delete_comment( $activity_id, $comment_id ) {
    1638     /***
     1896
     1897    /**
     1898     * Filters whether BuddyPress should delete an activity comment or not.
     1899     *
    16391900     * You may want to hook into this filter if you want to override this function and
    16401901     * handle the deletion of child comments differently. Make sure you return false.
     1902     *
     1903     * @since BuddyPress (1.2.0)
     1904     *
     1905     * @param bool $value Whether BuddyPress should continue or not.
     1906     * @param int  $activity_id ID of the root activity item being deleted.
     1907     * @param int  $comment_id ID of the comment being deleted.
    16411908     */
    16421909    if ( ! apply_filters( 'bp_activity_delete_comment_pre', true, $activity_id, $comment_id ) ) {
    … …  
    16581925    BP_Activity_Activity::rebuild_activity_comment_tree( $activity_id );
    16591926
     1927    /**
     1928     * Fires at the end of the deletion of an activity comment, before returning success.
     1929     *
     1930     * @since BuddyPress (1.2.0)
     1931     *
     1932     * @param int $activity_id ID of the activity that has had a comment deleted from.
     1933     * @param int $comment_id ID of the comment that was deleted.
     1934     */
    16601935    do_action( 'bp_activity_delete_comment', $activity_id, $comment_id );
    16611936
    … …  
    17342009    }
    17352010
     2011    /**
     2012     * Filters the activity permalink for the specified activity item.
     2013     *
     2014     * @since BuddyPress (1.2.0)
     2015     *
     2016     * @param array $array Array holding activity permalink and activity item object.
     2017     */
    17362018    return apply_filters_ref_array( 'bp_activity_get_permalink', array( $link, &$activity_obj ) );
    17372019}
    … …  
    18132095    }
    18142096
     2097    /**
     2098     * Filters the activity content that had a thumbnail replace images.
     2099     *
     2100     * @since BuddyPress (1.2.0)
     2101     *
     2102     * @param string $content Activity content that had images replaced in.
     2103     * @param array  $matches Array of all image tags found in the posted content.
     2104     * @param array  $args Arguments passed into function creating the activity update.
     2105     */
    18152106    return apply_filters( 'bp_activity_thumbnail_content_images', $content, $matches, $args );
    18162107}
    … …  
    18242115 */
    18252116function bp_activity_user_can_mark_spam() {
     2117
     2118    /**
     2119     * Filters whether the current user should be able to mark items as spam.
     2120     *
     2121     * @since BuddyPress (1.6.0)
     2122     *
     2123     * @param bool $moderate Whether or not the current user has bp_moderate capability.
     2124     */
    18262125    return apply_filters( 'bp_activity_user_can_mark_spam', bp_current_user_can( 'bp_moderate' ) );
    18272126}
    … …  
    18622161    }
    18632162
     2163    /**
     2164     * Fires at the end of the process to mark an activity item as spam.
     2165     *
     2166     * @since BuddyPress (1.6.0)
     2167     *
     2168     * @param BP_Activity_Activity $activity Activity item being marked as spam.
     2169     * @param string               $source Source of determination of spam status. For example
     2170     *                             "by_a_person" or "by_akismet".
     2171     */
    18642172    do_action( 'bp_activity_mark_as_spam', $activity, $source );
    18652173}
    … …  
    19002208    }
    19012209
     2210    /**
     2211     * Fires at the end of the process to mark an activity item as ham.
     2212     *
     2213     * @since BuddyPress (1.6.0)
     2214     *
     2215     * @param BP_Activity_Activity $activity Activity item being marked as ham.
     2216     * @param string               $source Source of determination of ham status. For example
     2217     *                             "by_a_person" or "by_akismet".
     2218     */
    19022219    do_action( 'bp_activity_mark_as_ham', $activity, $source );
    19032220}
Note: See TracChangeset for help on using the changeset viewer.