Skip to:
Content

BuddyPress.org

Changeset 8482


Ignore:
Timestamp:
06/08/2014 09:12:34 PM (10 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.