{"id":125239,"date":"2014-02-13T07:30:00","date_gmt":"2014-02-13T12:30:00","guid":{"rendered":"http:\/\/premium.wpmudev.org\/blog\/?p=125239"},"modified":"2014-04-02T18:25:48","modified_gmt":"2014-04-02T22:25:48","slug":"how-to-have-paragraph-commenting-just-like-medium","status":"publish","type":"post","link":"https:\/\/wpmudev.com\/blog\/how-to-have-paragraph-commenting-just-like-medium\/","title":{"rendered":"How To Have Paragraph Commenting Just Like Medium"},"content":{"rendered":"

Paragraph commenting, or annotations is not exactly new. Readers have been scribbling in the margins of books, magazines and uni assignments for years.<\/p>\n

The online world has been slow to adopt this approach which is perhaps why Medium caused a stir and no shortage of admiring looks when it went the annotation route.<\/p>\n

Well, admire forlornly no more because I’m going to show you how to add paragraph commenting to your WordPress site.<\/p>\n

\"Photo
Leonardo’s model for Mona Lisa was a margin-scribbler way back in 1503<\/figcaption><\/figure>\n

There are existing annotation solutions for WordPress but they are generally theme dependent, or in the case of CommentPress actually provide a theme.<\/p>\n

I wanted to make this solution work on as many different themes as possible so I actually ditched the requirement to have margins to scribble in. That said, if your template does have margins then you’ll just need to do tweak the CSS to achieve Medium-esque commenting.<\/p>\n

Solution Overview<\/h2>\n
\"Screenshot
Each paragraph has an and a comment count<\/figcaption><\/figure>\n

Annotations, by their very nature, are ajax-based as page reloads would kill the user-experience.<\/p>\n

Obviously, for paragraph commenting to work, each comment has to be tied to the paragraph which means that the paragraph has to have a unique ID. Determining what is a paragraph is quite difficult within WordPress as post content is generally stored unfiltered.<\/p>\n

With no HTML it’s also difficult to assign ids to a paragraph, so I decided that the simpler solution was to do that processing on the client-side, when WordPress has converted the content to HTML.<\/p>\n

What this means is that WordPress has no notion of paragraph ids – the browser handles everything. It also means that the ids are calculated each time the post is loaded and because I’ve used hashing to ensure a unique ID, if the text changes, the hashcode changes and comments can become orphaned.<\/p>\n

At first, I thought this would be a problem but on reflection, this is actually a logical outcome. If you are allowing comments on individual paragraphs then it seems that changing the paragraph text is “cheating”.<\/p>\n

\"Screenshot
Changing the text of a paragraph will orphan its comments<\/figcaption><\/figure>\n

The upside, though, is that paragraphs can change position in a post (either moved, or content is added or removed) without impacting on associated comments. Paragraphs with no comments can also be safely edited.<\/p>\n

When the Post Loads…<\/h3>\n
    \n
  1. When the post is displayed, client-side code generates a hashcode for each paragraph (p<\/em> tag) by hashing the paragraph text<\/li>\n
  2. The comments are searched for matches on the hashcode (the template for the comment display is altered to grab the hashcode from comment meta) and a total count is displayed at the end of the paragraph. An on-click event is attached to the count to toggle the display of the relevant comments.<\/li>\n
  3. As the comments are matched, they are hidden.<\/li>\n
  4. Any unmatched comments (orphans) are moved to a new div for permanent display at the bottom of the post.<\/li>\n<\/ol>\n

    When the Reader Clicks On A Paragraph’s Comment Count…<\/h3>\n
      \n
    1. The div containing all the comments is moved to sit under the relevant paragraph and its z-index<\/em> changed so that it sits “on top” of the post<\/li>\n
    2. All comments are hidden by default, so those comments attached to the paragraph are switched to display<\/li>\n
    3. The add new comment form is also displayed<\/li>\n<\/ol>\n

      The net effect here is that only the comments for the paragraph (if there are any) along with the new comment form are displayed under the appropriate paragraph.<\/p>\n

      \"Screenshot
      All comments for this paragraph only<\/figcaption><\/figure>\n

      When the Reader Adds A New Comment…<\/h3>\n
        \n
      1. When the Reader hits return and there’s text in the comment field, the hashcode for the paragraph is determined and added to the call to admin-ajax.php<\/em> to create a new comment<\/li>\n
      2. The server-side function that creates the new comment keeps the ID of the new comment and uses this and the paragraph hashcode to create a new entry in comment_meta<\/em><\/li>\n
      3. When the server-side function completes, the comment count for the paragraph is updated and the new comment displayed<\/li>\n<\/ol>\n

        Clicking on the comment count closes the comments list.<\/p>\n

        As you can see it’s a combination of client-side functions and server-side functions but predominantly client-side. The hashcodes are all generated on the client-side and WordPress is really oblivious to them apart from when creating the comment meta for a new comment.<\/p>\n

        Standing On Shoulders<\/h2>\n

        As is often the way in WordPress hacking, I didn’t create this solution from scratch but took an existing plugin, the excellent Inline Ajax Comments<\/a> which although only has compatibility to 3.6.1, happily works with 3.8.1.<\/p>\n

        This plugin already handled the listing and creation of new comments using ajax, so it was a matter of building on Zane Matthew’s<\/a> easy-to-follow and well-written code to get the behavior outlined above.<\/p>\n

        Whilst I’m not going to step through the whole plugin, I’ll just be highlighting my updates, it’s worth looking at Zane’s code, especially if you are not familiar with using WordPress’ admin-ajax functionality.<\/p>\n

        Creating Comment Meta, Adding Paragraph Hashcode To Comments Template<\/h3>\n

        Despite admin-ajax.php<\/em> being located in the wp-admin<\/em> folder, it’s a technique that can be used from the front-end and is preferred by many developers over APIs such as JSON due to its tighter integration with WordPress.<\/p>\n

        The basic approach is that the browser makes an ajax request to admin-ajax.php<\/em> requesting a particular action. WordPress checks a list of pre-registered actions and if a match is found calls the associated function. It is the functions job to build the response which is passed back to the browser.<\/p>\n

        Zane keeps all his action functions in the template-tags.php<\/code> file and two actions, inline_comments_load_template<\/code> and inline_comments_add_comment<\/code> need small updates.<\/p>\n

        At the bottom of the inline_comments_add_comment<\/em>, I amended the call to wp_insert_comment<\/em> to capture the new comment’s ID, and then add comment meta using the captured ID and the passed paragraph hashcode.<\/p>\n


        \n\/\/ ck - catch the new comment id for updating comment meta
        \n$comment_id = wp_insert_comment( $data );<\/code><\/p>\n

        \/\/ ck – now add the para-id to the comment meta
        \nadd_comment_meta( $comment_id, ‘para_id’ , $_POST[‘para_id’] );<\/p>\n

        Further down the script, in the inline_comments_load_template function, I made two small changes. The first is to get the related paragraph hashcode:<\/p>\n


        \n$para_id = get_comment_meta( $comment->comment_ID, 'para_id', true );
        \n<\/code><\/p>\n

        The second is simply to add orphan-comment<\/em> and comment-para-id<\/em> classes to the comment’s container div<\/em>.<\/p>\n

        The comment-para-id<\/em> has the paragraph hashcode added to it. This makes it possible to do jQuery searching using CSS selectors which is more efficient than using a non-standard attribute.<\/p>\n

        The orphan-comment<\/em> class is added to every comment because there are no hashcodes assigned anywhere in WordPress. Client-side processing removes the class if a match is found with an existing paragraph after it has calculated the paragraph hashcodes.<\/p>\n

        Kicking Off Paragraph Hashcode Calculations<\/h3>\n

        I only needed to make four small changes to the Zane’s existing client-side script (script.js<\/em>). Two were to ensure that the paragraph hashcode calculation got kicked-off, achieved by adding a call to set_up_para_comments<\/em> in the inline_comments_ajax_load_template<\/em> and load<\/em> functions.<\/p>\n

        I tried for quite some time to avoid this but I couldn’t seem to hook into the done()<\/em> action of the right event to be able to leave Zane’s script untouched. I’d be grateful if anyone has any suggestions as to how this could done.<\/p>\n

        Add New Comment – Including The Hashcode, Updating the Comment Count<\/h3>\n

        The other two changes are concerned with adding a new comment and takes place in the function that is kicked off by the onsubmit event for the comment form.<\/p>\n

        The first change is to simply to add the paragraph hashcode as a parameter on the ajax call to the inline_comments_add_comment<\/em> action. The hashcode is actually stored in a global variable that is assigned when the comment count link is clicked and the comments and comment form are displayed.<\/p>\n

        The second change is new code to update the comment count if the add is successful:<\/p>\n


        \nvar comment_count_holder = $('p[data-para-id=\"' + current_para_id + '\"] > span > a');
        \nvar comment_count = parseInt( comment_count_holder.text() );
        \ncomment_count_holder.text( comment_count + 1 );
        \n<\/code><\/p>\n

        The comment count is contained in an a<\/em> tag. This is retrieved, the number is incremented and then reassigned.<\/p>\n

        The rest of the solution is new client-side scripting.<\/p>\n

        Calculating a Paragraph’s Hashcode<\/h3>\n

        I wanted to be able to generate a unique code for each paragraph, so I decided that hashing the text would be a good way to do this.<\/p>\n

        The function to do this, borrowed from werxltd.com is actually added as a method to the javascript string<\/em> object:<\/p>\n

        Loading gist <\/p>\n

        Setting Up Paragraphs and Comments<\/h3>\n

        When the page is loaded in the browser, or when a new comment is made, the set_up_para_comments<\/em> function is called.<\/p>\n

        [gist id=\"8969845\" file=\"set_up_para_comments.js\"]<\/p>\n

        This function grabs all the paragraphs on the page for each:<\/p>\n

          \n
        1. Calculates a hashcode which is used to generate a class and the custom data-para-id<\/em> attribute.<\/li>\n
        2. Finds all the comments which have the same hashcode, counts them, removes the orphan-comment class and hides them<\/li>\n
        3. Adds a comment count to the end of the paragraph contained in an a tag<\/li>\n<\/ol>\n

          After processing each paragraph, any remaining comments (they will still have the orphan-comment class) are moved to their own container div<\/em>.<\/p>\n

          If this function is called after a new comment has been added then it simply shows the related comments and the add new comment form.<\/p>\n

          Displaying and Hiding A Paragraphs Comments<\/h3>\n

          This functionality is activated by the onclick<\/em> action on the comment count link (class of .toggle-comments<\/em>).<\/p>\n

          It first checks to see if the comments are visible and if they are then it just hides them.<\/p>\n

          If the comments are not visible then we need to filter the list for the paragraph concerned – remember, all the post’s comments are in the one container – and then display them.<\/p>\n

          [gist file=\"toggle_comments.js\"]8969845<\/a>

          Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n\n

          <\/p>\n

          Go Scribble in the Margins<\/h2>\n

          Okay, so it’s not exactly scribbling in the margins but it is paragraph commenting (or annotations) and it can be applied to almost any theme.<\/p>\n

          Of course, whether you want to apply this style of commenting to your site will depend on your content and primarily it’s length. Certainly, if you find your commenters are frequently trying to pull quotes from your posts then annotations may well be the way to go.<\/p>\n

          Photo Credit: Wikimedia<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"

          Are you a forlorn admirer of Medium’s paragraph commenting? Well, forlorn no more because here’s how to add paragraph commenting to your WordPress site.<\/p>\n","protected":false},"author":262394,"featured_media":126089,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"blog_reading_time":"","wds_primary_category":0,"wds_primary_tutorials_categories":0,"footnotes":""},"categories":[263],"tags":[1256,264,9812],"tutorials_categories":[],"class_list":["post-125239","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tutorials","tag-ajax","tag-comments","tag-medium"],"_links":{"self":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/125239","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/users\/262394"}],"replies":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/comments?post=125239"}],"version-history":[{"count":3,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/125239\/revisions"}],"predecessor-version":[{"id":193728,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/125239\/revisions\/193728"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media\/126089"}],"wp:attachment":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media?parent=125239"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/categories?post=125239"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tags?post=125239"},{"taxonomy":"tutorials_categories","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tutorials_categories?post=125239"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}