Skip to:
Content

BuddyPress.org

Changeset 9352


Ignore:
Timestamp:
01/13/2015 01:35:21 AM (10 years ago)
Author:
tw2113
Message:

Adds hooks documentation to the BP-Notifications component.

Fixes #5946.

Location:
trunk/src/bp-notifications
Files:
6 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/bp-notifications/bp-notifications-actions.php

    r9351 r9352  
    126126 * Handles bulk management (mark as read/unread, delete) of notifications.
    127127 *
    128  * @since BuddyPress (2.2)
     128 * @since BuddyPress (2.2.0)
    129129 *
    130130 * @return bool

  • trunk/src/bp-notifications/bp-notifications-cache.php

    r8958 r9352  
    1212 * @since BuddyPress (2.0.0)
    1313 *
    14  * @param BP_Notification_Notification $n Notification object.
     14 * @param BP_Notifications_Notification $n Notification object.
    1515 */
    1616function bp_notifications_clear_all_for_user_cache_after_save( BP_Notifications_Notification $n ) {

  • trunk/src/bp-notifications/bp-notifications-classes.php

    r9351 r9352  
    139139        $data_format = array( '%d', '%d', '%d', '%s', '%s', '%s', '%d' );
    140140
     141        /**
     142         * Fires before the current notification item gets saved.
     143         *
     144         * Please use this hook to filter the properties above. Each part will be passed in.
     145         *
     146         * @since BuddyPress (2.0.0)
     147         *
     148         * @param BP_Notifications_Notification Current instance of the notification item being saved. Passed by reference.
     149         */
    141150        do_action_ref_array( 'bp_notification_before_save', array( &$this ) );
    142151
    … …  
    158167        }
    159168
     169        /**
     170         * Fires after the current notification item gets saved.
     171         *
     172         * @since BuddyPress (2.0.0)
     173         *
     174         * @param BP_Notifications_Notification Current instance of the notification item being saved. Passed by reference.
     175         */
    160176        do_action_ref_array( 'bp_notification_after_save', array( &$this ) );
    161177
    … …  
    704720        $where = self::get_query_clauses( $args );
    705721
     722        /**
     723         * Fires before the deletion of a notification item.
     724         *
     725         * @since BuddyPress (2.0.0)
     726         *
     727         * @param array $args Associative array of columns/values, to determine
     728         *                    which rows should be deleted. Of the format
     729         *                    array( 'item_id' => 7, 'component_action' => 'members' ).
     730         */
    706731        do_action( 'bp_notification_before_delete', $args );
    707732

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

    r9351 r9352  
    152152    }
    153153
    154     // Filter and return
     154    /**
     155     * Filters all notifications for a user.
     156     *
     157     * @since BuddyPress (2.1.0)
     158     *
     159     * @param array $notifications Array of notifications for user.
     160     * @param int   $user_id       ID of the user being fetched.
     161     */
    155162    return apply_filters( 'bp_notifications_get_all_notifications_for_user', $notifications, $user_id );
    156163}
    … …  
    262269                if ( 'object' === $format ) {
    263270
    264                     // Retrieve the content of the notification using the callback
     271                    /**
     272                     * Filters the notifications for a user.
     273                     *
     274                     * @since BuddyPress (1.9.0)
     275                     *
     276                     * @param array $ref_array Array of properties for the current notification being rendered.
     277                     */
    265278                    $content = apply_filters_ref_array( 'bp_notifications_get_notifications_for_user', $ref_array );
    266279
    … …  
    282295                // Return an array of content strings
    283296                } else {
     297
     298                    /** This filters is documented in bp-notifications/bp-notifications-functions.php */
    284299                    $renderable[] = apply_filters_ref_array( 'bp_notifications_get_notifications_for_user', $ref_array );
    285300                }
    … …  
    293308    }
    294309
    295     // Filter and return
     310    /**
     311     * Filters the final array of notifications to be displayed for a user.
     312     *
     313     * @since BuddyPress (1.6.0)
     314     *
     315     * @param Array|Bool $renderable Array of notifications to render or false if no notifications.
     316     * @param int        $user_id    ID of the user whose notifications are being displayed.
     317     * @param string     $format     Display format requested for the notifications.
     318     */
    296319    return apply_filters( 'bp_core_get_notifications_for_user', $renderable, $user_id, $format );
    297320}
    … …  
    541564    $count         = ! empty( $notifications ) ? count( $notifications ) : 0;
    542565
     566    /**
     567     * Filters the count of unread notification items for a user.
     568     *
     569     * @since BuddyPress (1.9.0)
     570     *
     571     * @param int $count Count of unread notification items for a user.
     572     */
    543573    return apply_filters( 'bp_notifications_get_total_notification_count', (int) $count );
    544574}
    … …  
    572602    }
    573603
    574     // Return active components with registered notifications callbacks
     604    /**
     605     * Filters active components with registered notifications callbacks.
     606     *
     607     * @since BuddyPress (1.9.1)
     608     *
     609     * @param array $component_names   Array of registered component names.
     610     * @param array $active_components Array of active components.
     611     */
    575612    return apply_filters( 'bp_notifications_get_registered_components', $component_names, $active_components );
    576613}

  • trunk/src/bp-notifications/bp-notifications-screens.php

    r8958 r9352  
    2121 */
    2222function bp_notifications_screen_unread() {
     23
     24    /**
     25     * Fires right before the loading of the notifications unread screen template file.
     26     *
     27     * @since BuddyPress (1.9.0)
     28     */
    2329    do_action( 'bp_notifications_screen_unread' );
    2430
     31    /**
     32     * Filters the template to load for the notifications unread screen.
     33     *
     34     * @since BuddyPress (1.9.0)
     35     *
     36     * @param string $template Path to the notifications unread template to load.
     37     */
    2538    bp_core_load_template( apply_filters( 'bp_notifications_template_unread', 'members/single/home' ) );
    2639}
    … …  
    3245 */
    3346function bp_notifications_screen_read() {
     47
     48    /**
     49     * Fires right before the loading of the notifications read screen template file.
     50     *
     51     * @since BuddyPress (1.9.0)
     52     */
    3453    do_action( 'bp_notifications_screen_read' );
    3554
     55    /**
     56     * Filters the template to load for the notifications read screen.
     57     *
     58     * @since BuddyPress (1.9.0)
     59     *
     60     * @param string $template Path to the notifications read template to load.
     61     */
    3662    bp_core_load_template( apply_filters( 'bp_notifications_template_read', 'members/single/home' ) );
    3763}

  • trunk/src/bp-notifications/bp-notifications-template.php

    r9351 r9352  
    2727     */
    2828    function bp_get_notifications_slug() {
     29
     30        /**
     31         * Filters the notifications component slug.
     32         *
     33         * @since BuddyPress (1.9.0)
     34         *
     35         * @param string $slug Notifications component slug.
     36         */
    2937        return apply_filters( 'bp_get_notifications_slug', buddypress()->notifications->slug );
    3038    }
    … …  
    4755    function bp_get_notifications_permalink() {
    4856        $retval = trailingslashit( bp_loggedin_user_domain() . bp_get_notifications_slug() );
     57
     58        /**
     59         * Filters the notifications permalink.
     60         *
     61         * @since BuddyPress (1.9.0)
     62         *
     63         * @param string $retval Permalink for the notifications.
     64         */
    4965        return apply_filters( 'bp_get_notifications_permalink', $retval );
    5066    }
    … …  
    6783    function bp_get_notifications_unread_permalink() {
    6884        $retval = trailingslashit( bp_loggedin_user_domain() . bp_get_notifications_slug() . '/unread' );
     85
     86        /**
     87         * Filters the unread notifications permalink.
     88         *
     89         * @since BuddyPress (1.9.0)
     90         *
     91         * @param string $retval Permalink for the unread notifications.
     92         */
    6993        return apply_filters( 'bp_get_notifications_unread_permalink', $retval );
    7094    }
    … …  
    87111    function bp_get_notifications_read_permalink() {
    88112        $retval = trailingslashit( bp_loggedin_user_domain() . bp_get_notifications_slug() . '/read' );
     113
     114        /**
     115         * Filters the read notifications permalink.
     116         *
     117         * @since BuddyPress (1.9.0)
     118         *
     119         * @param string $retval Permalink for the read notifications.
     120         */
    89121        return apply_filters( 'bp_get_notifications_unread_permalink', $retval );
    90122    }
    … …  
    390422
    391423        } elseif ( $this->current_notification + 1 == $this->notification_count ) {
     424
     425            /**
     426             * Fires right before the rewinding of notification posts.
     427             *
     428             * @since BuddyPress (1.9.0)
     429             */
    392430            do_action( 'notifications_loop_end');
    393431
    … …  
    416454        // loop has just started
    417455        if ( 0 === $this->current_notification ) {
     456
     457            /**
     458             * Fires if the current notification item is the first in the notification loop.
     459             *
     460             * @since BuddyPress (1.9.0)
     461             */
    418462            do_action( 'notifications_loop_start' );
    419463        }
    … …  
    490534    buddypress()->notifications->query_loop = $query_loop;
    491535
     536    /**
     537     * Filters whether or not the user has notifications to display.
     538     *
     539     * @since BuddyPress (1.9.0)
     540     *
     541     * @param bool                      $value      Whether or not there are notifications to display.
     542     * @param BP_Notifications_Template $query_loop BP_Notifications_Template object instance.
     543     */
    492544    return apply_filters( 'bp_has_notifications', $query_loop->has_notifications(), $query_loop );
    493545}
    … …  
    533585     */
    534586    function bp_get_the_notification_id() {
     587
     588        /**
     589         * Filters the ID of the notification currently being iterated on.
     590         *
     591         * @since BuddyPress (1.9.0)
     592         *
     593         * @param int $id ID of the notification being iterated on.
     594         */
    535595        return apply_filters( 'bp_get_the_notification_id', buddypress()->notifications->query_loop->notification->id );
    536596    }
    … …  
    552612     */
    553613    function bp_get_the_notification_item_id() {
     614
     615        /**
     616         * Filters the associated item ID of the notification currently being iterated on.
     617         *
     618         * @since BuddyPress (1.9.0)
     619         *
     620         * @param int $item_id ID of the associated item.
     621         */
    554622        return apply_filters( 'bp_get_the_notification_item_id', buddypress()->notifications->query_loop->notification->item_id );
    555623    }
    … …  
    571639     */
    572640    function bp_get_the_notification_secondary_item_id() {
     641
     642        /**
     643         * Filters the secondary associated item ID of the notification currently being iterated on.
     644         *
     645         * @since BuddyPress (1.9.0)
     646         *
     647         * @param int $secondary_item_id ID of the secondary associated item.
     648         */
    573649        return apply_filters( 'bp_get_the_notification_secondary_item_id', buddypress()->notifications->query_loop->notification->secondary_item_id );
    574650    }
    … …  
    590666     */
    591667    function bp_get_the_notification_component_name() {
     668
     669        /**
     670         * Filters the name of the component associated with the notification currently being iterated on.
     671         *
     672         * @since BuddyPress (1.9.0)
     673         *
     674         * @param int $component_name Name of the component associated with the current notification.
     675         */
    592676        return apply_filters( 'bp_get_the_notification_component_name', buddypress()->notifications->query_loop->notification->component_name );
    593677    }
    … …  
    609693     */
    610694    function bp_get_the_notification_component_action() {
     695
     696        /**
     697         * Filters the name of the action associated with the notification currently being iterated on.
     698         *
     699         * @since BuddyPress (1.9.0)
     700         *
     701         * @param int $component_action Name of the action associated with the current notification.
     702         */
    611703        return apply_filters( 'bp_get_the_notification_component_action', buddypress()->notifications->query_loop->notification->component_action );
    612704    }
    … …  
    628720     */
    629721    function bp_get_the_notification_date_notified() {
     722
     723        /**
     724         * Filters the timestamp of the current notification.
     725         *
     726         * @since BuddyPress (1.9.0)
     727         *
     728         * @param string $date_notified Timestamp of the current notification.
     729         */
    630730        return apply_filters( 'bp_get_the_notification_date_notified', buddypress()->notifications->query_loop->notification->date_notified );
    631731    }
    … …  
    660760        }
    661761
     762        /**
     763         * Filters the time since value of the current notification.
     764         *
     765         * @since BuddyPress (1.9.0)
     766         *
     767         * @param string $retval Time since value for current notification.
     768         */
    662769        return apply_filters( 'bp_get_the_notification_time_since', $retval );
    663770    }
    … …  
    693800        // Allow non BuddyPress components to hook in
    694801        } else {
     802
     803            /** This filter is documented in bp-notifications/bp-notifications-functions.php */
    695804            $description = apply_filters_ref_array( 'bp_notifications_get_notifications_for_user', array( $notification->component_action, $notification->item_id, $notification->secondary_item_id, 1 ) );
    696805        }
    697806
    698         // Filter and return
     807        /**
     808         * Filters the full-text description for a specific notification.
     809         *
     810         * @since BuddyPress (1.9.0)
     811         *
     812         * @param string $description Full-text description for a specific notification.
     813         */
    699814        return apply_filters( 'bp_get_the_notification_description', $description );
    700815    }
    … …  
    724839        <?php $retval = ob_get_clean();
    725840
     841        /**
     842         * Filters the mark read link for the current notification.
     843         *
     844         * @since BuddyPress (1.9.0)
     845         *
     846         * @param string $retval HTML for the mark read link for the current notification.
     847         */
    726848        return apply_filters( 'bp_get_the_notification_mark_read_link', $retval );
    727849    }
    … …  
    761883        $url = wp_nonce_url( $url, 'bp_notification_mark_read_' . $id );
    762884
    763         // Filter and return
     885        /**
     886         * Filters the URL used for marking a single notification as read.
     887         *
     888         * @since BuddyPress (2.1.0)
     889         *
     890         * @param string $url URL to use for marking the single notification as read.
     891         */
    764892        return apply_filters( 'bp_get_the_notification_mark_read_url', $url );
    765893    }
    766894
    767895/**
    768  * Output the mark read link for the current notification.
     896 * Output the mark unread link for the current notification.
    769897 *
    770898 * @since BuddyPress (1.9.0)
    … …  
    776904}
    777905    /**
    778      * Return the mark read link for the current notification.
     906     * Return the mark unread link for the current notification.
    779907     *
    780908     * @since BuddyPress (1.9.0)
    … …  
    789917        <?php $retval = ob_get_clean();
    790918
     919        /**
     920         * Filters the link used for marking a single notification as unread.
     921         *
     922         * @since BuddyPress (1.9.0)
     923         *
     924         * @param string $retval HTML for the mark unread link for the current notification.
     925         */
    791926        return apply_filters( 'bp_get_the_notification_mark_unread_link', $retval );
    792927    }
    … …  
    826961        $url = wp_nonce_url( $url, 'bp_notification_mark_unread_' . $id );
    827962
    828         // Filter and return
     963        /**
     964         * Filters the URL used for marking a single notification as unread.
     965         *
     966         * @since BuddyPress (2.1.0)
     967         *
     968         * @param string $url URL to use for marking the single notification as unread.
     969         */
    829970        return apply_filters( 'bp_get_the_notification_mark_unread_url', $url );
    830971    }
    … …  
    853994        }
    854995
     996        /**
     997         * Filters the mark link for the current notification.
     998         *
     999         * @since BuddyPress (1.9.0)
     1000         *
     1001         * @param string $retval The mark link for the current notification.
     1002         */
    8551003        return apply_filters( 'bp_get_the_notification_mark_link', $retval );
    8561004    }
    … …  
    8801028        <?php $retval = ob_get_clean();
    8811029
     1030        /**
     1031         * Filters the delete link for the current notification.
     1032         *
     1033         * @since BuddyPress (1.9.0)
     1034         *
     1035         * @param string $retval HTML for the delete link for the current notification.
     1036         */
    8821037        return apply_filters( 'bp_get_the_notification_delete_link', $retval );
    8831038    }
    … …  
    9271082        $url = wp_nonce_url( $url, 'bp_notification_delete_' . $id );
    9281083
    929         // Filter and return
     1084        /**
     1085         * Filters the URL used for deleting a single notification.
     1086         *
     1087         * @since BuddyPress (2.1.0)
     1088         *
     1089         * @param string $url URL used for deleting a single notification.
     1090         */
    9301091        return apply_filters( 'bp_get_the_notification_delete_url', $url );
    9311092    }
    … …  
    9691130        $retval = $r['before'] . implode( $r['links'], $r['sep'] ) . $r['after'];
    9701131
     1132        /**
     1133         * Filters the action links for the current notification.
     1134         *
     1135         * @since BuddyPress (1.9.0)
     1136         *
     1137         * @param string $retval HTML links for actions to take on single notifications.
     1138         */
    9711139        return apply_filters( 'bp_get_the_notification_action_links', $retval );
    9721140    }
    … …  
    9951163        $pag        = sprintf( _n( 'Viewing 1 notification', 'Viewing %1$s - %2$s of %3$s notifications', $total, 'buddypress' ), $from_num, $to_num, $total );
    9961164
     1165        /**
     1166         * Filters the pagination count for the current notification loop.
     1167         *
     1168         * @since BuddyPress (1.9.0)
     1169         *
     1170         * @param string $pag HTML for the pagination count.
     1171         */
    9971172        return apply_filters( 'bp_notifications_pagination_count', $pag );
    9981173    }
    … …  
    10141189     */
    10151190    function bp_get_notifications_pagination_links() {
     1191
     1192        /**
     1193         * Filters the pagination links for the current notification loop.
     1194         *
     1195         * @since BuddyPress (1.9.0)
     1196         *
     1197         * @param string $pag_links HTML for the pagination links.
     1198         */
    10161199        return apply_filters( 'bp_get_notifications_pagination_links', buddypress()->notifications->query_loop->pag_links );
    10171200    }
Note: See TracChangeset for help on using the changeset viewer.