wamo/gnu-social
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Went through realtimeupdate.js and added documentation comments -- does not alter the minified version. :)

Browse Source 
Identified several bugs and fixmes, and added more thorough labeling of the issues with replicating the entire HTML structure of notices (no i18n, missing new features, maintenance problems, possible other issues)
This commit is contained in:
Brion Vibber 2010-11-30 16:35:47 -08:00
parent 749367e12f
commit f222e2132d
1 changed files with 261 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

263
plugins/Realtime/realtimeupdate.js
View File

@ -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('<ul id="realtime_actions"><li id="realtime_playpause"></li><li id="realtime_timeline"></li></ul>');
@ -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('<button id="realtime_popup"></button>');
@ -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() {