Paragraph-level commenting #1
Comments
Proof of concept of letting the site admin choose the plugin they want to use. Could do more with CSS and javascript to integrate things better into our full-width template. See #1.
|
So in our spec doc on the Commons, I've outlined a few plugins that are currently available. I think for our needs, we will let those plugins handle paragraph commenting as much as possible, Our Social Paper plugin will simply tweak things to better suit our full-width template. This will also allow site admins to choose which paragraph plugin they prefer. I've already added support for WP Side Comments in a previous commit and just recently added preliminary support for the Inline Comments plugin (this took less than 15 minutes!). As mentioned in other discussions, WP Side Comments (and Inline Comments) fits what we want to do UI-wise, but does not do any logic to modify the paragraph commentmeta position when a post is updated. This means that comments tied to a specific paragraph can display at the wrong paragraph after a post is edited. I have not reached out to the plugin authors about this, though it might make sense to do so. CommentPress is further along in this respect, but CP requires changing the current theme in order to function properly. This doesn't work for us, so I spent some time late last week trying to override CP templates to make things gel for our needs. I got this far (comment form doesn't show yet). To go all the way, we'd need to copy CP's JS over and adapt it to our needs. This will take time, so before I dived further, I thought I'd stop and assess things. Here is a table breakdown comparing the three plugins:
tl;dr - Should we make adjustments to support CommentPress? Or should we add support for updating the paragraph position for one of the other two plugins using a version of CP's paragraph diff code? Supporting either WP Side Comments or Inline Comments means we'll need to also add in comment permalinks of some kind. |
|
Good morning - I'm finally back after chronic HD ailments. Here are some notes on the comparisons above, in the light of testing the plugins locally:
Yep, CommentPress predates the existence of commentmeta :-) There are advantages and disadvantages to this: it means the The "hash" that is saved is composed of the first letter of each unique word in the paragraph (or commentable block) plus an auto-incremented paragraph identifier for cases where the content of two blocks produces hashes that are considered identical (or similar enough, at a 90% confidence level) by PHP's
Every unmodified hash would be
I've never come across this in practice, but then perhaps people just haven't let me know.
Not quite. Comment pagination is disabled for the site by CommentPress since it's far from clear what it means in a paragraph-level commenting context. The
I think this needs a bit more analysis and research. CommentPress implements Neither Inline Comments nor WP Side Comments accounts for possible browser caching issues on the returned data. WP Ajaxify Comments, however, does include the necessary cache-busting, but does not support the
It seems odd to me that comments are duplicated below the content and to the side of it. Clicking the "reference" link only scrolls to the appropriate selector and does not reveal the comments. Neither Inline Comments nor WP Side Comments generate "paragraph" (or whatever commentable blocks are called) permalinks. I notice that WP Side Comments has been extensively modified by others and that those changes have not been pushed upstream. I would say that an audit of these forks is probably worthwhile. Finally, it looks as though Inline Comments is no longer supported by the author. I presume that he means he only offers support via the premium plugin. |
What theme are you using, @r-a-y ? |
|
Thanks for the feedback, Christian.
Whoa!
Thanks for summarizing how the hash is calculated. Might come in handy if we decide to port over your hashing /
Thanks for clarifying. Makes sense. I wonder if we'll need to support the
I would actually prefer that we do not use WP Editor for comments as it clutters up the interface. I'm not sure if I saw an option in CP to disable this.
Good point. I didn't get far into my analysis here.
I'm using twentytwelve. But the Social Paper plugin bundles a custom full-width template and loads it only on single social paper pages to ensure that it stays separate from the current theme. I haven't pushed any of my CP support mods to this repo yet. I'll most likely push my mods to a separate branch so you can see what I'm doing. (Disclaimer: Parts of it isn't pretty 😄) |
|
This conversation is extremely helpful. Thanks @christianwach and @r-a-y. CommentPress's signature + I think that the canonical way of keeping track of comment position is going to have to be something along the lines of the CP approach. Because the WPSC and IC both use paragraph numbers in commentmeta, we'll need to have a shim for each. I'd imagine they'll work something like this: For each paper, store an array that associates paragraph numbers with paragraph signatures. Every time the paper is saved, generate an updated array, compare against the old array, and update all commentmeta as necessary. (The alternative would be to intercept commentmeta queries by these plugins, which would require no extra database overhead, but is bound to be trickier.) In any case: It is cool to provide out-of-the-box support for various commenting plugins, but for the Commons, we need to pick one and go with it. My opinion, having looked at the three options described by Ray, is that Inline Comments is the best option. It seems like it's better maintained than wp-side-comments (see @christianwach's comment above), it has (IMHO) a much better out-of-the-box interface than wp-side-comments, and it's far more lightweight than CommentPress. The main shortcoming of inline-comments seems to be that it doesn't natively post via AJAX, but we can pretty easily shim that ourselves (and pass upstream, if the author wants it). I see that there is some complication with using wp-comment-post.php plus AJAX - this is the browser-cache-busting stuff that Christian talks about. This is a pretty lousy situation. My initial thought is that wp-comment-post.php but one of many possible for WP's Comments API. It happens to be one that expects a POST request, which means that it does some browser redirects and other stuff like that. It's not well-suited at all for AJAX requests, and I don't think there's any reason we should feel obligated to use it. If there are hooks there that may be important, we can reproduce them in our own AJAX callback. But 'comment_post_redirect' is one thing that would rightly be left out of a custom client. wp-comment-post.php is 12 years old, and should not be used as a model for separation-of-concerns :) As for 'set_comment_cookies': I think that for our first rev, we're only allowing authenticated users to comment, and those comments will be immediately approved, so there's no real need for How do others feel about going forward with Inline Comments as our primary UI for now? |
I agree with this. It looks the better of the lightweight plugins. My primary concern would be the developer's statement that he's no longer supporting it. My secondary concern (but one which could be fixed during development) is that Inline Comments creates duplicate comments - both below the content and to the side of it - which confuses the UI in my opinion. Lastly, does CUNY have any accessibility requirements for CAC? If so, then it opens a number of issues with a JS-only solution. My preference (on DRY grounds and because Inline Comments already includes support for it) would be to combine it with WP Ajaxify Comments rather than duplicate the functionality of that plugin within Inline Comments. Though I have to say that the WP Ajaxify Comments code is, um, not poetry. I'll test the combination today and comment further when I've done so. |
I'm good with it.
I believe this is only regarding free support on the wp.org forums.
I agree. One thing I like about WP Side Comments is it marks its comments with a unique
Right, I think we would need some form of comment permalink support at the very least.
The WP Ajaxify Comments plugin, which Inline Comments relies on, posts with But has to do some workarounds on the It also uses PHP sessions, but doesn't close the session: This could lead to trouble with other plugins in the future, however it's the most popular wp.org plugin supporting AJAX comments... |
|
I've just noticed that the WP Ajaxify Comments plugin devs charge $19 per support request. Which I suspect we can all understand the motivation for ;-) but nevertheless would appear to be a hindrance to developing with it. |
Oh, right, we should definitely address this. Alternative strategy: we could intercept the comment query and add a
These days, reliance on JS does not, alone, pose an issue for accessibility. See http://webaim.org/techniques/javascript/ for an overview. (Requiring no-JS support is important for other reasons, but I don't think we need to hamstring ourselves about it for the purposes of CAC.) That said, I agree that we need comment permalink support at least, even if it's JS-based (an anchor + opening the relevant comment thread).
I dealt with it a few years ago, and if it hasn't changed since then, then 👍 If WPAC looks pretty bad, or like it's going to take any work at all to make it compatible with Social Paper, let's just ditch it and build our own AJAX compatibility. It is not difficult to do when you control the theme, which we will, at least on CAC.
Heh. Yeah, I don't blame them. I expect we won't need technical support from any plugin we choose, so it doesn't matter for us, but it's good to consider this when we are thinking about the viability of a plugin for being the default Social Paper interface. |
Indeed. I was enquiring about CUNY/CAC guidelines, if any. Thanks for clarifying.
Agreed. And ideally "commentable block" permalinks, but that may be less important.
I was thinking about whether we could upstream any improvements, rather than asking for help :-) |
|
Anyone want to share their Inline Comments settings? Mine aren't working that well, but I haven't had time to refine them:
And with the current setup of the theme, the ""Slide Site" Selector" needs to be:
|
Currently, only allows for paragraphs. Might potentially expand to other selectors like <blockquote>. See #1.
This will allow us to separate inline comments from the main comment loop. This commit also: - Fetches inline comments with the new 'incom' comment type - Alters the CSS comment class to bring back the 'comment' class so IC's comment toggling will still work. See #1.
- Alters the inline comment permalink to add the paragraph number. - Adds some JS to watch for our inline comment permalink and triggers IC's click action to open the inline comment block. See #1.
If the WP Ajaxify Comments (WPAC) plugin is activated, automatically load IC's WPAC module, so WPAC uses IC's custom settings. WPAC has its own settings routine, which bypasses WP's options API, so what this commit does is manually merge in IC's WPAC settings into the $wpac_options global before WPAC writes its inline JS. Oh joy! See #1.
We must also hook onto the 'default_option_X' filter in certain instances. See #1.
- Display Permalinks - checked - Display References - set to 'nowhere' See #1.
|
I've been looking at "Keeping track of comment position during document edits" and I now see why Google Docs doesn't offer paragraph-level (or other DOM element-level) commenting. It is possible to keep track of selection-based comments because the selection-start and selection-end changes can be detected as they happen if some kind of polling of their position is done or if temporary invisible markers are set when the insertion point is inside the selection range. However I am having a hard time getting my head around how DOM element-based changes can be similarly tracked since the elements can change in arbitrary ways including generating new elements - for example by hitting 'return' to create new paragraphs, or 'delete' to join previously separate ones. I'll keep plugging away. I'm also part way through a dependent task, which is to regenerate a functional Inline Comments environment when a post is updated. I've successfully intercepted the FEE save process and stripped out the Inline Comments |
|
Commit e0cc589 allows Inline Comments to remain functional after editing the content. It does not address the possibility of new relationships between the comments and the content. Nor does it address the possibility of orphaned comments when the number of selectors is reduced. However, Inline Comments itself doesn't check this either; i.e. if the corresponding element for the |
|
I've been tackling this issue, so I'll quote the relevant passage to refresh the discussion...
So far, my tests have led me to the opinion that this is not going to work unless So instead, I've been playing with a Javascript approach that attempts to track content changes so that I can trigger code when, for example, a new
or deleted:
@boonebgorges @r-a-y I'd appreciate any thoughts you may have on this before I continue down this route. |
When I first started looking into the changing nature of paragraphs at the PHP level, the following is one of the libraries I found: I think this is better than using
I think this works well if we can't figure out how to do this automatically.
I've been observing what Medium does and it appears this is what they are doing as well. They make an AJAX POST containing the relevant changes and new hash markers for new paragraphs during specific key-related events. It also appears that they are referencing the revision IDs as well. Orphaned inline comments appear to be deleted, so it looks like Medium doesn't support this either. We could do what CommentPress does and just move orphaned comments to the page comments if we do not want to lose this content. |
Thanks for this, Ray. Whilst it looks like a fine way of displaying diffs, unfortunately (as far as I can tell) it doesn't help so much in analysing or measuring changes. At least Levenshtein provides a way to analyse and assess similarity, which in turn allows us to make a decision on the results. The real problem is that once PHP is involved (i.e. the updated post content has reached the server) the text could have changed so substantially that no amount of analysis will give us enough data to make a decision. I'm going to keep pressing ahead with the Javascript approach since I'm now persuaded that the only feasible way of tracking which comments should remain where is by keeping a eye on the changes as they happen. |
|
Before I commit anything related to change-tracking, I should probably post the code that allows additional setup to be done. Beginning at line 373 of fee.js: tinymce.init( _.extend( wp.fee.tinymce, {
setup: function( editor ) {
contentEditor = editor;
window.wpActiveEditor = editor.id;
registerEditor( editor );
// Remove spaces from empty paragraphs.
editor.on( 'BeforeSetContent', function( event ) {
if ( event.content ) {
event.content = event.content.replace( /<p>(?: |\s)+<\/p>/gi, '<p><br></p>' );
}
} );
$(document).trigger( 'fee-editor-setup', [ editor ] ); // CMW: new trigger code here
}
} ) );This'll be required unless someone has an alternative idea of how to add the extra code to the TinyMCE instance. |
|
Try putting this in $(document).on( 'fee-editor-init', function( event ) {
editor = tinyMCE.get( window.wpActiveEditor );
console.log( editor );
} );Will this work, @christianwach? |
|
Thanks @r-a-y that's more elegant. |
|
FYI, I'm working on change tracking in branch 'delta'. So far, it's looking like complex project in its own right. |
|
There's a new-ish change tracking branch which I've been working on to preserve comment associations and prevent the orphaning of comments during the editing process when the paper has existing comments. What seems to be working (both with and without a selection):
When paragraphs are added (e.g. with the enter key), comments on subsequent paragraphs should remain associated with their paragraphs. The rule that I'm working with when paragraphs are removed is that their comments get attached to the previous paragraph in the editor. What's not yet been done:
@boonebgorges @r-a-y Feedback greatly appreciated as it would be really nice to put this out to wider testing via cdev. |
|
Hi @christianwach - Sorry it's taken a while, but I wanted to get a chance to give this the attention it deserves. I spent a bunch of time today going through the functionality and the code, and it is quite clever and really nicely done. I'm saddened by the fact that the TinyMCE implementation requires these weird workarounds (like the clipboard node handling, and the The ENTER functionality seems to work well. One bit of weirdness with DELETE. When backing out a paragraph one character at a time, using BACKSPACE, the unorphaning seems to take one extra keystroke. That is, I back out all the text in a para, until I get the "Add a block" placeholder, then press Backspace one more time so that I'm on the previous line (call this press "Alpha"). I'd expect the reshuffle to happen at this point, but I found the CUT/PASTE process to be a little finicky. Most of this is FEE's fault. If you highlight the text of a paragraph and cut it, the paragraph block is emptied, but it remains in the document. So, given your "change" logic, the comments don't come with. I don't know how serious a problem this will be in practice, but it seems like an upstream bug: all empty elements probably ought to disappear, not just n-1 empty elements. It's sort of a side-question, but a significant problem in my testing is that once paragraph comments have been combined, there's no way to manually uncombine them. So if Thanks for your work on this! It's really impressive. |
I noted this on Gitter. Here's a GIF displaying the problem: When I delete the I've found that switching But I'm not sure if this will break other use-cases. Like Boone said, the JS is really impressive! ⭐ 🌟 🌠
You can drag the paperclip icon for a top-level inline comment to another paragraph to move that inline comment and its children. I just noticed that I removed the paperclip icon on cdev (groan!), so I'll have to reinstate that back over there! Here's a GIF that describes this: We just need to document this to end-users. |
|
@boonebgorges @r-a-y Thank you both for the thorough testing. I will respond in full on Monday. |
It looks to me as though it's a TinyMCE issue since I can see the issue in Gecko but not in Webkit. Webkit behaves properly (i.e. it doesn't require the extra DELETE keystroke) but Gecko does not rejig the paragraphs when it is supposed to. Switching to As @r-a-y points out, the comment-reassignment system should allow comments (that have been merged into paragraphs that they shouldn't be attached to) to be reassigned to their correct paragraphs.
Yes indeed. The goal would obviously be to make the comments stick with entire paragraphs that have been cut, but I can't quite see how to identify when that happens. As my comments in the code point out, the presence of a trailing <p data-incom="P0">Fo[o</p>]
<p data-incom="P1">Bar</p>The only solution that I can think of is that the code keeps track of the content after each key press in order to discover whether a complete paragraph has been cut. This seems really clunky to me, but may be the only way forward. |
|
On a related note, I notice that Medium has abandoned paragraph-level commenting. I wonder if their decision is related to the problems associated with paragraph-tracking (as opposed to selection-tracking, where key presses inside a selection are easy to track)? |
|
Very interesting to see that Medium has gone with selection-based On Mon, Oct 26, 2015 at 9:36 AM, Christian Wach [email protected]
|
|
Interesting, indeed! On Mon, Oct 26, 2015 at 11:37 AM, mkgold [email protected] wrote:
|
|
Also interesting is that Genius (was RapGenius) are offering their annotation system to other sites. Comments become theirs, however. |
Ray, I know you've started work on this. Let's use this ticket for any technical discussion. cc @christianwach
Todos:
UX:
or add a header to the inline comment blockto let people know what paragraph the inline comment block belongs to. (commit @bad6382)Notes by Ray:
Comment AJAX support - WP Ajaxify Comments works well with Inline Comments and I have implemented support for this in commit c862518.
Christian notes the following however:
I do not think this is a problem for us since WP Ajaxify Comments only supports one type of comment form on the same page. This means that AJAX only works for Inline Comments and not regular post comments, which is fine for our needs.
I don't think Inline Comments requires comment pagination, so we should be fine. (I could be wrong and haven't tested this yet.)
The text was updated successfully, but these errors were encountered: