diff --git a/plugins/Realtime/realtimeupdate.js b/plugins/Realtime/realtimeupdate.js
index f49cef95e6..ea1f429b6a 100644
--- a/plugins/Realtime/realtimeupdate.js
+++ b/plugins/Realtime/realtimeupdate.js
@@ -26,8 +26,22 @@
* @link http://status.net/
*/
-// TODO: i18n
-
+/**
+ * This is the UI portion of the Realtime plugin base class, handling
+ * queueing up and displaying of notices that have been received through
+ * other code in one of the subclassed plugin implementations such as
+ * Meteor or Orbited.
+ *
+ * Notices are passed in as JSON objects formatted per the Twitter-compatible
+ * API.
+ *
+ * @todo Currently we duplicate a lot of formatting and layout code from
+ * the PHP side of StatusNet, which makes it very difficult to maintain
+ * this package. Internationalization as well as newer features such
+ * as location data, customized source links for OStatus profiles,
+ * and image thumbnails are not yet supported in Realtime yet because
+ * they have not been implemented here.
+ */
RealtimeUpdate = {
_userid: 0,
_replyurl: '',
@@ -41,6 +55,25 @@ RealtimeUpdate = {
_paused:false,
_queuedNotices:[],
+ /**
+ * Initialize the Realtime plugin UI on a page with a timeline view.
+ *
+ * This function is called from a JS fragment inserted by the PHP side
+ * of the Realtime plugin, and provides us with base information
+ * needed to build a near-replica of StatusNet's NoticeListItem output.
+ *
+ * Once the UI is initialized, a plugin subclass will need to actually
+ * feed data into the RealtimeUpdate object!
+ *
+ * @param {int} userid: local profile ID of the currently logged-in user
+ * @param {String} replyurl: URL for newnotice action, used when generating reply buttons
+ * @param {String} favorurl: URL for favor action, used when generating fave buttons
+ * @param {String} repeaturl: URL for repeat action, used when generating repeat buttons
+ * @param {String} deleteurl: URL template for deletenotice action, used when generating delete buttons.
+ * This URL contains a stub value of 0000000000 which will be replaced with the notice ID.
+ *
+ * @access public
+ */
init: function(userid, replyurl, favorurl, repeaturl, deleteurl)
{
RealtimeUpdate._userid = userid;
@@ -66,6 +99,24 @@ RealtimeUpdate = {
});
},
+ /**
+ * Accept a notice in a Twitter-API JSON style and either show it
+ * or queue it up, depending on whether the realtime display is
+ * active.
+ *
+ * The meat of a Realtime plugin subclass is to provide a substrate
+ * transport to receive data and shove it into this function. :)
+ *
+ * Note that the JSON data is extended from the standard API return
+ * with additional fields added by RealtimePlugin's PHP code.
+ *
+ * @param {Object} data: extended JSON API-formatted notice
+ *
+ * @fixme Ticket #2914: already-visible sent notices are still queued up
+ * when paused, inflating the queue count
+ *
+ * @access public
+ */
receive: function(data)
{
if (RealtimeUpdate._paused === false) {
@@ -82,6 +133,20 @@ RealtimeUpdate = {
RealtimeUpdate.updateWindowCounter();
},
+ /**
+ * Add a visible representation of the given notice at the top of
+ * the current timeline.
+ *
+ * If the notice is already in the timeline, nothing will be added.
+ *
+ * @param {Object} data: extended JSON API-formatted notice
+ *
+ * @fixme while core UI JS code is used to activate the AJAX UI controls,
+ * the actual production of HTML (in makeNoticeItem and its subs)
+ * duplicates core code without plugin hook points or i18n support.
+ *
+ * @access private
+ */
insertNoticeItem: function(data) {
// Don't add it if it already exists
if ($("#notice-"+data.id).length > 0) {
@@ -99,12 +164,26 @@ RealtimeUpdate = {
SN.U.NoticeWithAttachment($('#'+noticeItemID));
},
+ /**
+ * Trims a notice off the end of the timeline if we have more than the
+ * maximum number of notices visible.
+ *
+ * @access private
+ */
purgeLastNoticeItem: function() {
if ($('#notices_primary .notice').length > RealtimeUpdate._maxnotices) {
$("#notices_primary .notice:last").remove();
}
},
+ /**
+ * If the window/tab is in background, increment the counter of newly
+ * received notices and append it onto the window title.
+ *
+ * Has no effect if the window is in foreground.
+ *
+ * @access private
+ */
updateWindowCounter: function() {
if (RealtimeUpdate._windowhasfocus === false) {
RealtimeUpdate._updatecounter += 1;
@@ -112,6 +191,19 @@ RealtimeUpdate = {
}
},
+ /**
+ * Builds a notice HTML block from JSON API-style data.
+ *
+ * @param {Object} data: extended JSON API-formatted notice
+ * @return {String} HTML fragment
+ *
+ * @fixme this replicates core StatusNet code, making maintenance harder
+ * @fixme sloppy HTML building (raw concat without escaping)
+ * @fixme no i18n support
+ * @fixme local variables pollute global namespace
+ *
+ * @access private
+ */
makeNoticeItem: function(data)
{
if (data.hasOwnProperty('retweeted_status')) {
@@ -182,6 +274,19 @@ RealtimeUpdate = {
return ni;
},
+ /**
+ * Creates a favorite button.
+ *
+ * @param {number} id: notice ID to work with
+ * @param {String} session_key: session token for form CSRF protection
+ * @return {String} HTML fragment
+ *
+ * @fixme this replicates core StatusNet code, making maintenance harder
+ * @fixme sloppy HTML building (raw concat without escaping)
+ * @fixme no i18n support
+ *
+ * @access private
+ */
makeFavoriteForm: function(id, session_key)
{
var ff;
@@ -197,6 +302,19 @@ RealtimeUpdate = {
return ff;
},
+ /**
+ * Creates a reply button.
+ *
+ * @param {number} id: notice ID to work with
+ * @param {String} nickname: nick of the user to whom we are replying
+ * @return {String} HTML fragment
+ *
+ * @fixme this replicates core StatusNet code, making maintenance harder
+ * @fixme sloppy HTML building (raw concat without escaping)
+ * @fixme no i18n support
+ *
+ * @access private
+ */
makeReplyLink: function(id, nickname)
{
var rl;
@@ -204,6 +322,19 @@ RealtimeUpdate = {
return rl;
},
+ /**
+ * Creates a repeat button.
+ *
+ * @param {number} id: notice ID to work with
+ * @param {String} session_key: session token for form CSRF protection
+ * @return {String} HTML fragment
+ *
+ * @fixme this replicates core StatusNet code, making maintenance harder
+ * @fixme sloppy HTML building (raw concat without escaping)
+ * @fixme no i18n support
+ *
+ * @access private
+ */
makeRepeatForm: function(id, session_key)
{
var rf;
@@ -219,6 +350,18 @@ RealtimeUpdate = {
return rf;
},
+ /**
+ * Creates a delete button.
+ *
+ * @param {number} id: notice ID to create a delete link for
+ * @return {String} HTML fragment
+ *
+ * @fixme this replicates core StatusNet code, making maintenance harder
+ * @fixme sloppy HTML building (raw concat without escaping)
+ * @fixme no i18n support
+ *
+ * @access private
+ */
makeDeleteLink: function(id)
{
var dl, delurl;
@@ -229,6 +372,19 @@ RealtimeUpdate = {
return dl;
},
+ /**
+ * Adds a control widget at the top of the timeline view, containing
+ * pause/play and popup buttons.
+ *
+ * @param {String} url: full URL to the popup window variant of this timeline page
+ * @param {String} timeline: string key for the timeline (eg 'public' or 'evan-all')
+ * @param {String} path: URL to the base directory containing the Realtime plugin,
+ * used to fetch resources if needed.
+ *
+ * @todo timeline and path parameters are unused and probably should be removed.
+ *
+ * @access private
+ */
initActions: function(url, timeline, path)
{
$('#notices_primary').prepend('');
@@ -239,6 +395,14 @@ RealtimeUpdate = {
RealtimeUpdate.initAddPopup(url, timeline, RealtimeUpdate._pluginPath);
},
+ /**
+ * Initialize the state of the play/pause controls.
+ *
+ * If the browser supports the localStorage interface, we'll attempt
+ * to retrieve a pause state from there; otherwise we default to paused.
+ *
+ * @access private
+ */
initPlayPause: function()
{
if (typeof(localStorage) == 'undefined') {
@@ -254,6 +418,15 @@ RealtimeUpdate = {
}
},
+ /**
+ * Switch the realtime UI into paused state.
+ * Uses SN.msg i18n system for the button label and tooltip.
+ *
+ * State will be saved and re-used next time if the browser supports
+ * the localStorage interface (via setPause).
+ *
+ * @access private
+ */
showPause: function()
{
RealtimeUpdate.setPause(false);
@@ -271,6 +444,15 @@ RealtimeUpdate = {
});
},
+ /**
+ * Switch the realtime UI into play state.
+ * Uses SN.msg i18n system for the button label and tooltip.
+ *
+ * State will be saved and re-used next time if the browser supports
+ * the localStorage interface (via setPause).
+ *
+ * @access private
+ */
showPlay: function()
{
RealtimeUpdate.setPause(true);
@@ -284,6 +466,17 @@ RealtimeUpdate = {
});
},
+ /**
+ * Update the internal pause/play state.
+ * Do not call directly; use showPause() and showPlay().
+ *
+ * State will be saved and re-used next time if the browser supports
+ * the localStorage interface.
+ *
+ * @param {boolean} state: true = paused, false = not paused
+ *
+ * @access private
+ */
setPause: function(state)
{
RealtimeUpdate._paused = state;
@@ -292,6 +485,15 @@ RealtimeUpdate = {
}
},
+ /**
+ * Go through notices we have previously received while paused,
+ * dumping them into the timeline view.
+ *
+ * @fixme long timelines are not trimmed here as they are for things received while not paused
+ * @fixme Ticket #2913: the queued counter on the window title does not get cleared
+ *
+ * @access private
+ */
showQueuedNotices: function()
{
$.each(RealtimeUpdate._queuedNotices, function(i, n) {
@@ -303,16 +505,35 @@ RealtimeUpdate = {
RealtimeUpdate.removeQueuedCounter();
},
+ /**
+ * Update the Realtime widget control's counter of queued notices to show
+ * the current count. This will be called after receiving and queueing
+ * a notice while paused.
+ *
+ * @access private
+ */
updateQueuedCounter: function()
{
$('#realtime_playpause #queued_counter').html('('+RealtimeUpdate._queuedNotices.length+')');
},
+ /**
+ * Clear the Realtime widget control's counter of queued notices.
+ *
+ * @access private
+ */
removeQueuedCounter: function()
{
$('#realtime_playpause #queued_counter').empty();
},
+ /**
+ * Set up event handlers on the timeline view to automatically pause
+ * when the mouse is over the timeline, as this indicates the user's
+ * desire to interact with the UI. (Which is hard to do when it's moving!)
+ *
+ * @access private
+ */
addNoticesHover: function()
{
$('#notices_primary .notices').hover(
@@ -329,11 +550,38 @@ RealtimeUpdate = {
);
},
+ /**
+ * Tear down event handlers on the timeline view to automatically pause
+ * when the mouse is over the timeline.
+ *
+ * @fixme this appears to remove *ALL* event handlers from the timeline,
+ * which assumes that nobody else is adding any event handlers.
+ * Sloppy -- we should only remove the ones we add.
+ *
+ * @access private
+ */
removeNoticesHover: function()
{
$('#notices_primary .notices').unbind();
},
+ /**
+ * UI initialization, to be called from Realtime plugin code on regular
+ * timeline pages.
+ *
+ * Adds a button to the control widget at the top of the timeline view,
+ * allowing creation of a popup window with a more compact real-time
+ * view of the current timeline.
+ *
+ * @param {String} url: full URL to the popup window variant of this timeline page
+ * @param {String} timeline: string key for the timeline (eg 'public' or 'evan-all')
+ * @param {String} path: URL to the base directory containing the Realtime plugin,
+ * used to fetch resources if needed.
+ *
+ * @todo timeline and path parameters are unused and probably should be removed.
+ *
+ * @access public
+ */
initAddPopup: function(url, timeline, path)
{
$('#realtime_timeline').append('');
@@ -348,6 +596,17 @@ RealtimeUpdate = {
});
},
+ /**
+ * UI initialization, to be called from Realtime plugin code on popup
+ * compact timeline pages.
+ *
+ * Sets up links in notices to open in a new window.
+ *
+ * @fixme fails to do the same for UI links like context view which will
+ * look bad in the tiny chromeless window.
+ *
+ * @access public
+ */
initPopupWindow: function()
{
$('.notices .entry-title a, .notices .entry-content a').bind('click', function() {