Skip to:
Content

BuddyPress.org

Changeset 8482


Ignore:
Timestamp:
06/08/2014 09:12:34 PM (12 years ago)
Author:
boonebgorges
Message:

Improved inline documentation in the Messages component.

See #5022

Location:
trunk/src/bp-messages
Files:
4 edited

Legend:

Unmodified
Added
Removed

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

    r8414 r8482  
    1414
    1515/**
    16  * Email message recipients to alert them of a new unread private message
    17  *
    18  * @since BuddyPress (1.0)
    19  * @param array $raw_args
     16 * Email message recipients to alert them of a new unread private message.
     17 *
     18 * @since BuddyPress (1.0.0)
     19 *
     20 * @param array|BP_Messages_Message $raw_args {
     21 *     Array of arguments. Also accepts a BP_Messages_Message object.
     22 *     @type array $recipients User IDs of recipients.
     23 *     @type string $email_subject Subject line of message.
     24 *     @type string $email_content Content of message.
     25 *     @type int $sender_id User ID of sender.
     26 * }
    2027 */
    2128function messages_notification_new_message( $raw_args = array() ) {
    … …  
    102109
    103110/**
    104  * Format the BuddyBar/Toolbar notifications for the Messages component
    105  *
    106  * @since BuddyPress (1.0)
    107  * @param string $action The kind of notification being rendered
    108  * @param int $item_id The primary item id
    109  * @param int $secondary_item_id The secondary item id
    110  * @param int $total_items The total number of messaging-related notifications waiting for the user
    111  * @param string $format 'string' for BuddyBar-compatible notifications; 'array' for WP Toolbar
     111 * Format the BuddyBar/Toolbar notifications for the Messages component.
     112 *
     113 * @since BuddyPress (1.0.0)
     114 *
     115 * @param string $action The kind of notification being rendered.
     116 * @param int $item_id The primary item id.
     117 * @param int $secondary_item_id The secondary item id.
     118 * @param int $total_items The total number of messaging-related notifications
     119 *        waiting for the user
     120 * @param string $format Return value format. 'string' for BuddyBar-compatible
     121 *        notifications; 'array' for WP Toolbar. Default: 'string'.
     122 * @return string|array Formatted notifications.
    112123 */
    113124function messages_format_notifications( $action, $item_id, $secondary_item_id, $total_items, $format = 'string' ) {
    … …  
    151162
    152163/**
    153  * Send notifications to message recipients
     164 * Send notifications to message recipients.
    154165 *
    155166 * @since BuddyPress (1.9.0)
    156  * @param obj $message
     167 *
     168 * @param BP_Messages_Message $message Message object.
    157169 */
    158170function bp_messages_message_sent_add_notification( $message ) {

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

    r6806 r8482  
    44 * BuddyPress Messages Screens
    55 *
    6  * Screen functions are the controllers of BuddyPress. They will execute when their
    7  * specific URL is caught. They will first save or manipulate data using business
    8  * functions, then pass on the user to a template file.
     6 * Screen functions are the controllers of BuddyPress. They will execute when
     7 * their specific URL is caught. They will first save or manipulate data using
     8 * business functions, then pass on the user to a template file.
    99 *
    1010 * @package BuddyPress
    … …  
    1515if ( !defined( 'ABSPATH' ) ) exit;
    1616
     17/**
     18 * Load the Messages > Inbox screen.
     19 */
    1720function messages_screen_inbox() {
    1821        if ( bp_action_variables() ) {
    … …  
    2528}
    2629
     30/**
     31 * Load the Messages > Sent screen.
     32 */
    2733function messages_screen_sentbox() {
    2834        if ( bp_action_variables() ) {
    … …  
    3541}
    3642
     43/**
     44 * Load the Messages > Compose screen.
     45 */
    3746function messages_screen_compose() {
    3847        global $bp;
    … …  
    8796}
    8897
     98/**
     99 * Load an individual conversation screen.
     100 *
     101 * @return bool|null False on failure.
     102 */
    89103function messages_screen_conversation() {
    90104
    … …  
    110124add_action( 'bp_screens', 'messages_screen_conversation' );
    111125
     126/**
     127 * Load the Messages > Notices screen.
     128 *
     129 * @return false|null False on failure.
     130 */
    112131function messages_screen_notices() {
    113132        global $notice_id;
    … …  
    153172}
    154173
     174/**
     175 * Render the markup for the Messages section of Settings > Notifications.
     176 */
    155177function messages_screen_notification_settings() {
    156178        if ( bp_action_variables() ) {

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

    r8202 r8482  
    1515 */
    1616class BP_Messages_Box_Template {
     17        /**
     18         * The loop iterator.
     19         *
     20         * @access public
     21         * @var int
     22         */
    1723        var $current_thread = -1;
     24
     25        /**
     26         * The number of threads returned by the paged query.
     27         *
     28         * @access public
     29         * @var int
     30         */
    1831        var $current_thread_count;
     32
     33        /**
     34         * Total number of threads matching the query params.
     35         *
     36         * @access public
     37         * @var int
     38         */
    1939        var $total_thread_count;
     40
     41        /**
     42         * Array of threads located by the query.
     43         *
     44         * @access public
     45         * @var array
     46         */
    2047        var $threads;
     48
     49        /**
     50         * The thread object currently being iterated on.
     51         *
     52         * @access public
     53         * @var object
     54         */
    2155        var $thread;
    2256
     57        /**
     58         * A flag for whether the loop is currently being iterated.
     59         *
     60         * @access public
     61         * @var bool
     62         */
    2363        var $in_the_loop;
     64
     65        /**
     66         * User ID of the current inbox.
     67         *
     68         * @access public
     69         * @var int
     70         */
    2471        var $user_id;
     72
     73        /**
     74         * The current "box" view ('notices', 'sentbox', 'inbox')
     75         *
     76         * @access public
     77         * @var string
     78         */
    2579        var $box;
    2680
     81        /**
     82         * The page number being requested.
     83         *
     84         * @access public
     85         * @var int
     86         */
    2787        var $pag_page;
     88
     89        /**
     90         * The number of items being requested per page.
     91         *
     92         * @access public
     93         * @var int
     94         */
    2895        var $pag_num;
     96
     97        /**
     98         * An HTML string containing pagination links.
     99         *
     100         * @access public
     101         * @var string
     102         */
    29103        var $pag_links;
     104
     105        /**
     106         * Search terms for limiting the thread query.
     107         *
     108         * @access public
     109         * @var string
     110         */
    30111        var $search_terms;
    31112
     113        /**
     114         * Constructor method.
     115         *
     116         * @param int $user_id ID of the user whose Messages box is being
     117         *        viewed.
     118         * @param string $box Type of box being viewed ('notices', 'sentbox',
     119         *        'inbox').
     120         * @param int $per_page Number of thread to return per page of results.
     121         * @param int $max Max number of results to return.
     122         * @param string $type Type of results to return. 'unread', 'read',
     123         *        or 'all'.
     124         * @param string $search_terms Search terms for limiting results.
     125         * @param string $page_arg Optional. URL argument for pagination
     126         *        parameter. Default: 'mpage'.
     127         */
    32128        function __construct( $user_id, $box, $per_page, $max, $type, $search_terms, $page_arg = 'mpage' ) {
    33129                $this->pag_page = isset( $_GET[$page_arg] ) ? intval( $_GET[$page_arg] ) : 1;
    … …  
    89185        }
    90186
     187        /**
     188         * Whether there are threads available in the loop.
     189         *
     190         * @see bp_has_message_threads()
     191         *
     192         * @return bool True if there are items in the loop, otherwise false.
     193         */
    91194        function has_threads() {
    92195                if ( $this->thread_count )
    … …  
    96199        }
    97200
     201        /**
     202         * Set up the next member and iterate index.
     203         *
     204         * @return object The next member to iterate over.
     205         */
    98206        function next_thread() {
    99207                $this->current_thread++;
    … …  
    103211        }
    104212
     213        /**
     214         * Rewind the threads and reset thread index.
     215         */
    105216        function rewind_threads() {
    106217                $this->current_thread = -1;
    … …  
    110221        }
    111222
     223        /**
     224         * Whether there are threads left in the loop to iterate over.
     225         *
     226         * This method is used by {@link bp_message_threads()} as part of the
     227         * while loop that controls iteration inside the threads loop, eg:
     228         *     while ( bp_message_threads() ) { ...
     229         *
     230         * @see bp_message_threads()
     231         *
     232         * @return bool True if there are more threads to show, otherwise false.
     233         */
    112234        function message_threads() {
    113235                if ( $this->current_thread + 1 < $this->thread_count ) {
    … …  
    123245        }
    124246
     247        /**
     248         * Set up the current thread inside the loop.
     249         *
     250         * Used by {@link bp_message_thread()} to set up the current thread data
     251         * while looping, so that template tags used during that iteration make
     252         * reference to the current thread.
     253         *
     254         * @see bp_message_thread()
     255         */
    125256        function the_message_thread() {
    126257
    … …  
    167298
    168299/**
    169  * Retrieve private message threads for display in inbox/sentbox/notices
     300 * Retrieve private message threads for display in inbox/sentbox/notices.
    170301 *
    171302 * Similar to WordPress's have_posts() function, this function is responsible
    … …  
    176307 *
    177308 * @global BP_Messages_Box_Template $messages_template
    178  * @param array $args
    179  * @return object
     309 *
     310 * @param array $args {
     311 *     Array of arguments. All are optional.
     312 *     @type int $user_id ID of the user whose threads are being loaded.
     313 *           Default: ID of the logged-in user.
     314 *     @type string $box Current "box" view. If not provided here, the current
     315 *           view will be inferred from the URL.
     316 *     @type int $per_page Number of results to return per page. Default: 10.
     317 *     @type int $max Max results to return. Default: false.
     318 *     @type string $search_terms Terms to which to limit results. Default:
     319 *           the value of $_REQUEST['s'].
     320 *     @type string $page_arg URL argument used for the pagination param.
     321 *           Default: 'mpage'.
     322 * }
     323 * @return bool True if there are threads to display, otherwise false.
    180324 */
    181325function bp_has_message_threads( $args = '' ) {
    … …  
    221365}
    222366
     367/**
     368 * Check whether there are more threads to iterate over.
     369 *
     370 * @return bool
     371 */
    223372function bp_message_threads() {
    224373        global $messages_template;
    … …  
    226375}
    227376
     377/**
     378 * Set up the current thread inside the loop.
     379 *
     380 * @return object
     381 */
    228382function bp_message_thread() {
    229383        global $messages_template;
    … …  
    231385}
    232386
     387/**
     388 * Output the ID of the current thread in the loop.
     389 */
    233390function bp_message_thread_id() {
    234391        echo bp_get_message_thread_id();
    235392}
     393        /**
     394         * Get the ID of the current thread in the loop.
     395         *
     396         * @return int
     397         */
    236398        function bp_get_message_thread_id() {
    237399                global $messages_template;
    … …  
    240402        }
    241403
     404/**
     405 * Output the subject of the current thread in the loop.
     406 */
    242407function bp_message_thread_subject() {
    243408        echo bp_get_message_thread_subject();
    244409}
     410        /**
     411         * Get the subject of the current thread in the loop.
     412         *
     413         * @return string
     414         */
    245415        function bp_get_message_thread_subject() {
    246416                global $messages_template;
    … …  
    249419        }
    250420
     421/**
     422 * Output an excerpt from the current message in the loop.
     423 */
    251424function bp_message_thread_excerpt() {
    252425        echo bp_get_message_thread_excerpt();
    253426}
     427        /**
     428         * Generate an excerpt from the current message in the loop.
     429         *
     430         * @return string
     431         */
    254432        function bp_get_message_thread_excerpt() {
    255433                global $messages_template;
    … …  
    290468        }
    291469
     470/**
     471 * Output a link to the page of the current thread's last author.
     472 */
    292473function bp_message_thread_from() {
    293474        echo bp_get_message_thread_from();
    294475}
     476        /**
     477         * Get a link to the page of the current thread's last author.
     478         *
     479         * @return string
     480         */
    295481        function bp_get_message_thread_from() {
    296482                global $messages_template;
    … …  
    299485        }
    300486
     487/**
     488 * Output links to the pages of the current thread's recipients.
     489 */
    301490function bp_message_thread_to() {
    302491        echo bp_get_message_thread_to();
    303492}
     493        /**
     494         * Generate HTML links to the pages of the current thread's recipients.
     495         *
     496         * @return string
     497         */
    304498        function bp_get_message_thread_to() {
    305499                global $messages_template;
    … …  
    307501        }
    308502
     503/**
     504 * Output the permalink for a particular thread.
     505 *
     506 * @param int $thread_id Optional. ID of the thread. Default: current thread
     507 *        being iterated on in the loop.
     508 */
    309509function bp_message_thread_view_link( $thread_id = 0 ) {
    310510        echo bp_get_message_thread_view_link( $thread_id );
    311511}
     512        /**
     513         * Get the permalink of a particular thread.
     514         *
     515         * @param int $thread_id Optional. ID of the thread. Default: current
     516         *        thread being iterated on in the loop.
     517         * @return string
     518         */
    312519        function bp_get_message_thread_view_link( $thread_id = 0 ) {
    313520                global $messages_template;
    … …  
    322529        }
    323530
     531/**
     532 * Output the URL for deleting the current thread.
     533 */
    324534function bp_message_thread_delete_link() {
    325535        echo bp_get_message_thread_delete_link();
    326536}
     537        /**
     538         * Generate the URL for deleting the current thread.
     539         *
     540         * @return string
     541         */
    327542        function bp_get_message_thread_delete_link() {
    328543                global $messages_template, $bp;
    … …  
    330545        }
    331546
     547/**
     548 * Output the CSS class for the current thread.
     549 */
    332550function bp_message_css_class() {
    333551        echo bp_get_message_css_class();
    334552}
    335 
     553        /**
     554         * Generate the CSS class for the current thread.
     555         *
     556         * @return string
     557         */
    336558        function bp_get_message_css_class() {
    337559                global $messages_template;
    … …  
    345567        }
    346568
     569/**
     570 * Check whether the current thread has unread items.
     571 *
     572 * @return bool True if there are unread items, otherwise false.
     573 */
    347574function bp_message_thread_has_unread() {
    348575        global $messages_template;
    … …  
    354581}
    355582
     583/**
     584 * Output the current thread's unread count.
     585 */
    356586function bp_message_thread_unread_count() {
    357587        echo bp_get_message_thread_unread_count();
    358588}
     589        /**
     590         * Get the current thread's unread count.
     591         *
     592         * @return int
     593         */
    359594        function bp_get_message_thread_unread_count() {
    360595                global $messages_template;
    … …  
    366601        }
    367602
     603/**
     604 * Output the date of the last post in the current thread.
     605 */
    368606function bp_message_thread_last_post_date() {
    369607        echo bp_get_message_thread_last_post_date();
    370608}
     609        /**
     610         * Get the date of the last post in the current thread.
     611         *
     612         * @return string
     613         */
    371614        function bp_get_message_thread_last_post_date() {
    372615                global $messages_template;
    … …  
    431674        }
    432675
     676/**
     677 * Output the unread messages count for the current inbox.
     678 */
    433679function bp_total_unread_messages_count() {
    434680        echo bp_get_total_unread_messages_count();
    435681}
     682        /**
     683         * Get the unread messages count for the current inbox.
     684         *
     685         * @return int
     686         */
    436687        function bp_get_total_unread_messages_count() {
    437688                return apply_filters( 'bp_get_total_unread_messages_count', BP_Messages_Thread::get_inbox_count() );
    438689        }
    439690
     691/**
     692 * Output the pagination HTML for the current thread loop.
     693 */
    440694function bp_messages_pagination() {
    441695        echo bp_get_messages_pagination();
    442696}
     697        /**
     698         * Get the pagination HTML for the current thread loop.
     699         *
     700         * @return string
     701         */
    443702        function bp_get_messages_pagination() {
    444703                global $messages_template;
    … …  
    446705        }
    447706
     707/**
     708 * Generate the "Viewing message x to y (of z messages)" string for a loop.
     709 *
     710 * @return string
     711 */
    448712function bp_messages_pagination_count() {
    449713        global $messages_template;
    … …  
    458722
    459723/**
    460  * Output the Private Message search form
    461  *
    462  * @since BuddyPress (1.6)
     724 * Output the Private Message search form.
     725 *
     726 * @since BuddyPress (1.6.0)
    463727 */
    464728function bp_message_search_form() {
    … …  
    476740
    477741/**
    478  * Echoes the form action for Messages HTML forms
    479  *
    480  * @package BuddyPress
     742 * Echo the form action for Messages HTML forms.
    481743 */
    482744function bp_messages_form_action() {
    … …  
    484746}
    485747        /**
    486          * Returns the form action for Messages HTML forms
    487          *
    488          * @package BuddyPress
     748         * Return the form action for Messages HTML forms.
    489749         *
    490750         * @return string The form action
    … …  
    494754        }
    495755
     756/**
     757 * Output the default username for the recipient box.
     758 */
    496759function bp_messages_username_value() {
    497760        echo bp_get_messages_username_value();
    498761}
     762        /**
     763         * Get the default username for the recipient box.
     764         *
     765         * @return string
     766         */
    499767        function bp_get_messages_username_value() {
    500768                if ( isset( $_COOKIE['bp_messages_send_to'] ) ) {
    … …  
    505773        }
    506774
     775/**
     776 * Output the default value for the Subject field.
     777 */
    507778function bp_messages_subject_value() {
    508779        echo bp_get_messages_subject_value();
    509780}
     781        /**
     782         * Get the default value for the Subject field.
     783         *
     784         * Will get a value out of $_POST['subject'] if available (ie after a
     785         * failed submission).
     786         *
     787         * @return string
     788         */
    510789        function bp_get_messages_subject_value() {
    511790                $subject = '';
    … …  
    516795        }
    517796
     797/**
     798 * Output the default value for the Compose content field.
     799 */
    518800function bp_messages_content_value() {
    519801        echo bp_get_messages_content_value();
    520802}
     803        /**
     804         * Get the default value fo the Compose content field.
     805         *
     806         * Will get a value out of $_POST['content'] if available (ie after a
     807         * failed submission).
     808         *
     809         * @return string
     810         */
    521811        function bp_get_messages_content_value() {
    522812                $content = '';
    … …  
    527817        }
    528818
     819/**
     820 * Output the markup for the message type dropdown.
     821 */
    529822function bp_messages_options() {
    530823?>
    … …  
    552845
    553846/**
    554  * Return whether or not the notice is currently active
    555  *
    556  * @since BuddyPress (1.6)
    557  * @uses bp_get_messages_is_active_notice()
     847 * Return whether or not the notice is currently active.
     848 *
     849 * @since BuddyPress (1.6.0)
    558850 */
    559851function bp_messages_is_active_notice() {
    … …  
    567859
    568860/**
    569  * Output a string for the active notice
    570  *
    571  * Since 1.6 this function has been deprecated in favor of text in the theme
    572  *
    573  * @since BuddyPress (1.0)
    574  * @deprecated BuddyPress (1.6)
     861 * Output a string for the active notice.
     862 *
     863 * Since 1.6 this function has been deprecated in favor of text in the theme.
     864 *
     865 * @since BuddyPress (1.0.0)
     866 * @deprecated BuddyPress (1.6.0)
    575867 * @uses bp_get_message_is_active_notice()
    576868 */
    … …  
    579871}
    580872        /**
    581          * Returns a string for the active notice
    582          *
    583          * Since 1.6 this function has been deprecated in favor of text in the theme
    584          *
    585          * @since BuddyPress (1.0)
    586          * @deprecated BuddyPress (1.6)
     873         * Returns a string for the active notice.
     874         *
     875         * Since 1.6 this function has been deprecated in favor of text in the
     876         * theme.
     877         *
     878         * @since BuddyPress (1.0.0)
     879         * @deprecated BuddyPress (1.6.0)
    587880         * @uses bp_messages_is_active_notice()
    588881         */
    … …  
    596889        }
    597890
     891/**
     892 * Output the ID of the current notice in the loop.
     893 */
    598894function bp_message_notice_id() {
    599895        echo bp_get_message_notice_id();
    600896}
     897        /**
     898         * Get the ID of the current notice in the loop.
     899         *
     900         * @return int
     901         */
    601902        function bp_get_message_notice_id() {
    602903                global $messages_template;
    … …  
    604905        }
    605906
     907/**
     908 * Output the post date of the current notice in the loop.
     909 */
    606910function bp_message_notice_post_date() {
    607911        echo bp_get_message_notice_post_date();
    608912}
     913        /**
     914         * Get the post date of the current notice in the loop.
     915         *
     916         * @return string
     917         */
    609918        function bp_get_message_notice_post_date() {
    610919                global $messages_template;
    … …  
    612921        }
    613922
     923/**
     924 * Output the subject of the current notice in the loop.
     925 */
    614926function bp_message_notice_subject() {
    615927        echo bp_get_message_notice_subject();
    616928}
     929        /**
     930         * Get the subject of the current notice in the loop.
     931         *
     932         * @return string
     933         */
    617934        function bp_get_message_notice_subject() {
    618935                global $messages_template;
    … …  
    620937        }
    621938
     939/**
     940 * Output the text of the current notice in the loop.
     941 */
    622942function bp_message_notice_text() {
    623943        echo bp_get_message_notice_text();
    624944}
     945        /**
     946         * Get the text of the current notice in the loop.
     947         *
     948         * @return string
     949         */
    625950        function bp_get_message_notice_text() {
    626951                global $messages_template;
    … …  
    628953        }
    629954
     955/**
     956 * Output the URL for deleting the current notice.
     957 */
    630958function bp_message_notice_delete_link() {
    631959        echo bp_get_message_notice_delete_link();
    632960}
     961        /**
     962         * Get the URL for deleting the current notice.
     963         *
     964         * @return string Delete URL.
     965         */
    633966        function bp_get_message_notice_delete_link() {
    634967                global $messages_template, $bp;
    … …  
    637970        }
    638971
     972/**
     973 * Output the URL for deactivating the current notice.
     974 */
    639975function bp_message_activate_deactivate_link() {
    640976        echo bp_get_message_activate_deactivate_link();
    641977}
     978        /**
     979         * Get the URL for deactivating the current notice.
     980         *
     981         * @return string
     982         */
    642983        function bp_get_message_activate_deactivate_link() {
    643984                global $messages_template, $bp;
    … …  
    651992        }
    652993
     994/**
     995 * Output the Deactivate/Activate text for the notice action link.
     996 */
    653997function bp_message_activate_deactivate_text() {
    654998        echo bp_get_message_activate_deactivate_text();
    655999}
     1000        /**
     1001         * Generate the text ('Deactivate' or 'Activate' for the notice action link.
     1002         *
     1003         * @return string
     1004         */
    6561005        function bp_get_message_activate_deactivate_text() {
    6571006                global $messages_template;
    … …  
    6661015
    6671016/**
    668  * Output the messages component slug
    669  *
    670  * @package BuddyPress
    671  * @subpackage Messages Template
    672  * @since BuddyPress (1.5)
     1017 * Output the messages component slug.
     1018 *
     1019 * @since BuddyPress (1.5.0)
    6731020 *
    6741021 * @uses bp_get_messages_slug()
    … …  
    6781025}
    6791026        /**
    680          * Return the messages component slug
    681          *
    682          * @package BuddyPress
    683          * @subpackage Messages Template
    684          * @since BuddyPress (1.5)
     1027         * Return the messages component slug.
     1028         *
     1029         * @since BuddyPress (1.5.0)
     1030         *
     1031         * @return string
    6851032         */
    6861033        function bp_get_messages_slug() {
    … …  
    6891036        }
    6901037
     1038/**
     1039 * Generate markup for currently active notices.
     1040 */
    6911041function bp_message_get_notices() {
    6921042        $notice = BP_Messages_Notice::get_active();
    … …  
    7151065}
    7161066
     1067/**
     1068 * Output the URL for the Private Message link in member profile headers.
     1069 */
    7171070function bp_send_private_message_link() {
    7181071        echo bp_get_send_private_message_link();
    7191072}
     1073        /**
     1074         * Generate the URL for the Private Message link in member profile headers.
     1075         *
     1076         * @return bool|string False on failure, otherwise the URL.
     1077         */
    7201078        function bp_get_send_private_message_link() {
    7211079
    … …  
    7271085
    7281086/**
    729  * bp_send_private_message_button()
     1087 * Output the 'Private Message' button for member profile headers.
    7301088 *
    7311089 * Explicitly named function to avoid confusion with public messages.
    7321090 *
     1091 * @since BuddyPress (1.2.6)
     1092 *
    7331093 * @uses bp_get_send_message_button()
    734  * @since BuddyPress (1.2.6)
    7351094 */
    7361095function bp_send_private_message_button() {
    … …  
    7381097}
    7391098
     1099/**
     1100 * Output the 'Private Message' button for member profile headers.
     1101 */
    7401102function bp_send_message_button() {
    7411103        echo bp_get_send_message_button();
    7421104}
     1105        /**
     1106         * Generate the 'Private Message' button for member profile headers.
     1107         *
     1108         * @return string
     1109         */
    7431110        function bp_get_send_message_button() {
    7441111                // Note: 'bp_get_send_message_button' is a legacy filter. Use
    … …  
    7591126        }
    7601127
     1128/**
     1129 * Output the URL of the Messages AJAX loader gif.
     1130 */
    7611131function bp_message_loading_image_src() {
    7621132        echo bp_get_message_loading_image_src();
    7631133}
     1134        /**
     1135         * Get the URL of the Messages AJAX loader gif.
     1136         *
     1137         * @return string
     1138         */
    7641139        function bp_get_message_loading_image_src() {
    7651140                global $bp;
    … …  
    7671142        }
    7681143
     1144/**
     1145 * Output the markup for the message recipient tabs.
     1146 */
    7691147function bp_message_get_recipient_tabs() {
    7701148        $recipients = explode( ' ', bp_get_message_get_recipient_usernames() );
    … …  
    7861164}
    7871165
     1166/**
     1167 * Output recipient usernames for prefilling the 'To' field on the Compose screen.
     1168 */
    7881169function bp_message_get_recipient_usernames() {
    7891170        echo bp_get_message_get_recipient_usernames();
    7901171}
     1172        /**
     1173         * Get the recipient usernames for prefilling the 'To' field on the Compose screen.
     1174         *
     1175         * @return string
     1176         */
    7911177        function bp_get_message_get_recipient_usernames() {
    7921178                $recipients = isset( $_GET['r'] ) ? stripslashes( $_GET['r'] ) : '';
    … …  
    7961182
    7971183
    798 /*****************************************************************************
     1184/**
    7991185 * Message Thread Template Class
    800  **/
    801 
     1186 */
    8021187class BP_Messages_Thread_Template {
     1188        /**
     1189         * The loop iterator.
     1190         *
     1191         * @access public
     1192         * @var int
     1193         */
    8031194        var $current_message = -1;
     1195
     1196        /**
     1197         * Number of messages returned by the paged query.
     1198         *
     1199         * @access public
     1200         * @var int
     1201         */
    8041202        var $message_count;
     1203
     1204        /**
     1205         * The message object currently being iterated on.
     1206         *
     1207         * @access public
     1208         * @var object
     1209         */
    8051210        var $message;
    8061211
     1212        /**
     1213         * Thread that the current messages belong to.
     1214         *
     1215         * @access public
     1216         * @var BP_Messages_Thread
     1217         */
    8071218        var $thread;
    8081219
     1220        /**
     1221         * A flag for whether the loop is currently being iterated.
     1222         *
     1223         * @access public
     1224         * @var bool
     1225         */
    8091226        var $in_the_loop;
    8101227
     1228        /**
     1229         * The page number being requested.
     1230         *
     1231         * @access public
     1232         * @var int
     1233         */
    8111234        var $pag_page;
     1235
     1236        /**
     1237         * The number of items being requested per page.
     1238         *
     1239         * @access public
     1240         * @var int
     1241         */
    8121242        var $pag_num;
     1243
     1244        /**
     1245         * An HTML string containing pagination links.
     1246         *
     1247         * @access public
     1248         * @var string
     1249         */
    8131250        var $pag_links;
     1251
     1252        /**
     1253         * The total number of messages matching the query.
     1254         *
     1255         * @access public
     1256         * @var int
     1257         */
    8141258        var $total_message_count;
    8151259
     1260        /**
     1261         * Constructor method.
     1262         *
     1263         * @param int $thread_id ID of the message thread.
     1264         * @param string $order 'ASC' or 'DESC'.
     1265         */
    8161266        function __construct( $thread_id, $order ) {
    8171267                $this->thread        = new BP_Messages_Thread( $thread_id, $order );
    … …  
    8261276        }
    8271277
     1278        /**
     1279         * Whether there are messages available in the loop.
     1280         *
     1281         * @see bp_thread_has_messages()
     1282         *
     1283         * @return bool True if there are items in the loop, otherwise false.
     1284         */
    8281285        function has_messages() {
    8291286                if ( $this->message_count )
    … …  
    8331290        }
    8341291
     1292        /**
     1293         * Set up the next member and iterate index.
     1294         *
     1295         * @return object The next member to iterate over.
     1296         */
    8351297        function next_message() {
    8361298                $this->current_message++;
    … …  
    8401302        }
    8411303
     1304        /**
     1305         * Rewind the messages and reset message index.
     1306         */
    8421307        function rewind_messages() {
    8431308                $this->current_message = -1;
    … …  
    8471312        }
    8481313
     1314        /**
     1315         * Whether there are messages left in the loop to iterate over.
     1316         *
     1317         * This method is used by {@link bp_thread_messages()} as part of the
     1318         * while loop that controls iteration inside the messages loop, eg:
     1319         *     while ( bp_thread_messages() ) { ...
     1320         *
     1321         * @see bp_thread_messages()
     1322         *
     1323         * @return bool True if there are more messages to show, otherwise false.
     1324         */
    8491325        function messages() {
    8501326                if ( $this->current_message + 1 < $this->message_count ) {
    … …  
    8601336        }
    8611337
     1338        /**
     1339         * Set up the current message inside the loop.
     1340         *
     1341         * Used by {@link bp_thread_the_message()} to set up the current
     1342         * message data while looping, so that template tags used during
     1343         * that iteration make reference to the current message.
     1344         *
     1345         * @see bp_thread_the_message()
     1346         */
    8621347        function the_message() {
    8631348                $this->in_the_loop = true;
    … …  
    8701355}
    8711356
     1357/**
     1358 * Initialize the messages template loop for a specific thread.
     1359 *
     1360 * @param array $args {
     1361 *     Array of arguments. All are optional.
     1362 *     @type int $thread_id ID of the thread whose messages you are displaying.
     1363 *           Default: if viewing a thread, the thread ID will be parsed from
     1364 *           the URL (bp_action_variable( 0 )).
     1365 *     @type string $order 'ASC' or 'DESC'. Default: 'ASC'.
     1366 * }
     1367 * @return bool True if there are messages to display, otherwise false.
     1368 */
    8721369function bp_thread_has_messages( $args = '' ) {
    8731370        global $thread_template;
    … …  
    8881385}
    8891386
     1387/**
     1388 * Output the 'ASC' or 'DESC' messages order string for this loop.
     1389 */
    8901390function bp_thread_messages_order() {
    8911391        echo bp_get_thread_messages_order();
    8921392}
    893 
     1393        /**
     1394         * Get the 'ASC' or 'DESC' messages order string for this loop.
     1395         *
     1396         * @return string
     1397         */
    8941398        function bp_get_thread_messages_order() {
    8951399                global $thread_template;
    … …  
    8971401        }
    8981402
     1403/**
     1404 * Check whether there are more messages to iterate over.
     1405 *
     1406 * @return bool
     1407 */
    8991408function bp_thread_messages() {
    9001409        global $thread_template;
    … …  
    9031412}
    9041413
     1414/**
     1415 * Set up the current thread inside the loop.
     1416 *
     1417 * @return object
     1418 */
    9051419function bp_thread_the_message() {
    9061420        global $thread_template;
    … …  
    9091423}
    9101424
     1425/**
     1426 * Output the ID of the thread that the current loop belongs to.
     1427 */
    9111428function bp_the_thread_id() {
    9121429        echo bp_get_the_thread_id();
    9131430}
     1431        /**
     1432         * Get the ID of the thread that the current loop belongs to.
     1433         *
     1434         * @return int
     1435         */
    9141436        function bp_get_the_thread_id() {
    9151437                global $thread_template;
    … …  
    9181440        }
    9191441
     1442/**
     1443 * Output the subject of the thread currently being iterated over.
     1444 */
    9201445function bp_the_thread_subject() {
    9211446        echo bp_get_the_thread_subject();
    9221447}
     1448        /**
     1449         * Get the subject of the thread currently being iterated over.
     1450         *
     1451         * @return string
     1452         */
    9231453        function bp_get_the_thread_subject() {
    9241454                global $thread_template;
    … …  
    9271457        }
    9281458
     1459/**
     1460 * Output HTML links to recipients in the current thread.
     1461 */
    9291462function bp_the_thread_recipients() {
    9301463        echo bp_get_the_thread_recipients();
    9311464}
     1465        /**
     1466         * Generate HTML links to the profiles of recipients in the current thread.
     1467         *
     1468         * @return string
     1469         */
    9321470        function bp_get_the_thread_recipients() {
    9331471                global $thread_template;
    … …  
    9541492
    9551493/**
    956  * Echoes the ID of the current message in the thread
    957  *
    958  * @since BuddyPress (1.9)
     1494 * Echo the ID of the current message in the thread.
     1495 *
     1496 * @since BuddyPress (1.9.0)
    9591497 */
    9601498function bp_the_thread_message_id() {
    … …  
    9621500}
    9631501        /**
    964          * Gets the ID of the current message in the thread
    965          *
    966          * @since BuddyPress (1.9)
     1502         * Get the ID of the current message in the thread.
     1503         *
     1504         * @since BuddyPress (1.9.0)
     1505         *
    9671506         * @return int
    9681507         */
    … …  
    9741513        }
    9751514
     1515/**
     1516 * Output the CSS class used for message zebra striping.
     1517 */
    9761518function bp_the_thread_message_alt_class() {
    9771519        echo bp_get_the_thread_message_alt_class();
    9781520}
     1521        /**
     1522         * Get the CSS class used for message zebra striping.
     1523         *
     1524         * @return string
     1525         */
    9791526        function bp_get_the_thread_message_alt_class() {
    9801527                global $thread_template;
    … …  
    9891536        }
    9901537
     1538/**
     1539 * Output the avatar for the current message sender.
     1540 *
     1541 * @param array $args See {@link bp_get_the_thread_message_sender_avatar_thumb()}
     1542 *        for a description.
     1543 */
    9911544function bp_the_thread_message_sender_avatar( $args = '' ) {
    9921545        echo bp_get_the_thread_message_sender_avatar_thumb( $args );
    9931546}
     1547        /**
     1548         * Get the avatar for the current message sender.
     1549         *
     1550         * @param array $args {
     1551         *     Array of arguments. See {@link bp_core_fetch_avatar()} for more
     1552         *     complete details. All arguments are optional.
     1553         *     @type string $type Avatar type. Default: 'thumb'.
     1554         *     @type int $width Avatar width. Default: default for your $type.
     1555         *     @type int $height Avatar height. Default: default for your $type.
     1556         * }
     1557         * @return string <img> tag containing the avatar.
     1558         */
    9941559        function bp_get_the_thread_message_sender_avatar_thumb( $args = '' ) {
    9951560                global $thread_template;
    … …  
    10071572        }
    10081573
     1574/**
     1575 * Output a link to the sender of the current message.
     1576 */
    10091577function bp_the_thread_message_sender_link() {
    10101578        echo bp_get_the_thread_message_sender_link();
    10111579}
     1580        /**
     1581         * Get a link to the sender of the current message.
     1582         *
     1583         * @return string
     1584         */
    10121585        function bp_get_the_thread_message_sender_link() {
    10131586                global $thread_template;
    … …  
    10161589        }
    10171590
     1591/**
     1592 * Output the display name of the sender of the current message.
     1593 */
    10181594function bp_the_thread_message_sender_name() {
    10191595        echo bp_get_the_thread_message_sender_name();
    10201596}
     1597        /**
     1598         * Get the display name of the sender of the current message.
     1599         *
     1600         * @return string
     1601         */
    10211602        function bp_get_the_thread_message_sender_name() {
    10221603                global $thread_template;
    … …  
    10301611        }
    10311612
     1613/**
     1614 * Output the URL for deleting the current thread.
     1615 */
    10321616function bp_the_thread_delete_link() {
    10331617        echo bp_get_the_thread_delete_link();
    10341618}
     1619        /**
     1620         * Get the URL for deleting the current thread.
     1621         *
     1622         * @return string URL
     1623         */
    10351624        function bp_get_the_thread_delete_link() {
    10361625                global $bp;
    … …  
    10391628        }
    10401629
     1630/**
     1631 * Output the 'Sent x hours ago' string for the current message.
     1632 */
    10411633function bp_the_thread_message_time_since() {
    10421634        echo bp_get_the_thread_message_time_since();
    10431635}
     1636        /**
     1637         * Generate the 'Sent x hours ago' string for the current message.
     1638         *
     1639         * @return string
     1640         */
    10441641        function bp_get_the_thread_message_time_since() {
    10451642                global $thread_template;
    … …  
    10481645        }
    10491646
     1647/**
     1648 * Output the content of the current message in the loop.
     1649 */
    10501650function bp_the_thread_message_content() {
    10511651        echo bp_get_the_thread_message_content();
    10521652}
     1653        /**
     1654         * Get the content of the current message in the loop.
     1655         *
     1656         * @return string
     1657         */
    10531658        function bp_get_the_thread_message_content() {
    10541659                global $thread_template;
    … …  
    10601665
    10611666/**
    1062  * Enable oembed support for Messages.
     1667 * Enable oEmbed support for Messages.
    10631668 *
    10641669 * There's no caching as BP 1.5 does not have a Messages meta API.
    10651670 *
     1671 * @since BuddyPress (1.5.0)
     1672 *
    10661673 * @see BP_Embed
    1067  * @since BuddyPress (1.5)
     1674 *
    10681675 * @todo Add Messages meta?
    10691676 */

  • trunk/src/bp-messages/bp-messages-widgets.php

    r7430 r8482  
    1717add_action( 'bp_register_widgets', 'bp_messages_register_widgets' );
    1818
    19 /** Sitewide Notices widget *************************************************/
     19/** Sitewide Notices widget ***************************************************/
    2020
    2121/**
Note: See TracChangeset for help on using the changeset viewer.