A comment traverser to help manage conversations on web pages.
JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
demo
javascript/jquery
stylesheets
README.textile
demo.html

README.textile

Encouraged Commentary

This is the source code for an approach to managing comments which was evangelized and demonstrated on my blog DontTrustThisGuy.com.

Usage

Include the Script and Dependencies

If you’re not using jQuery already you will need to add it to your project. You will also need to include the jQuery ScrollTo plugin as well. Finally, I recommend using the minimized version of the encouraged commentary script which reduces the file size to only 5.8kb. You should include these scripts in the following order, and also embed them in your HTML just before you close the body tag in your template file. This ensures faster loading of your page.

   
      <script type="text/javascript" charset="utf-8" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js"></script>
      <script src="javascript/jquery/jquery.scrollTo-min.js" type="text/javascript"></script>
      <script src="javascript/jquery/encouraged-commentary-min.js" type="text/javascript"></script>
   </code>
   .../body>

Quotable Content

Using this script is easy. Simply add the class ‘quotable’ to any containing element in your markup that should be quotable. As an example, if your blog post is in a div with an id of ‘entry’ simply add the ‘quotable’ class to that div. Now users can highlight text to quote your article!

Example

This:

   <body...
<code>
   <h2>My Blog Article</h2>
   <div id="blog-entry">
      <p>The content of this article is as follows.</p>
      ...
   </div>
   <ol id="comments">
</code>
   ../body>

Becomes:

   <body...
<code>
   <h2>My Blog Article</h2>
   <div id="blog-entry" class="quotable">
      <p>The content of this article is as follows.</p>
      ...
   </div>
   <h3 id="comments">3 Comments</h3>
   <ol>
</code>
   .../body>

Designate Comment Textarea with id=“comment”

This step is very important! You will need to give the target textarea an ID ‘comment’.

This:

   <body...
<code>
   <form method="post" id="commentform">
      <h3>Leave a Reply</h3>
      ...
      <p><textarea name="comment"></textarea></p>
      <p><input name="submit" type="submit" id="submit" value="Submit Comment" />
      </p>
   </form>
</code>
   .../body>

Becomes:

   <body...
<code>
   <form method="post" id="commentform">
      <h3>Leave a Reply</h3>
      ...
      <p><textarea name="comment" id="comment"></textarea></p>
      <p><input name="submit" type="submit" id="submit" value="Submit Comment" />
      </p>
   </form>
</code>
   .../body>

[NEW FEATURE] Get a lightbox, live preview, and generate HTML on the fly instead of the TextArea

To get form enhancements on your site all you need to do is add the class ‘encouraged-form’ for your comment form. Once you do this users will no longer be forced to the bottom of your page. Instead, your form will be temporarily transported into a lightbox and then put back if the user cancels out. Additionally, the directive and quote are stored in javascript and the user is given a manner to remove the quote / directive from their comment if they’d like. This is validated / communicated to the user as they will see a live preview of their comment, generated for them as they type! Any of these features can be toggled off and if you don’t add the encouraged-form class everything behaves as it once did before.

This:

   <body...
<code>
   <form method="post" id="commentform">
      <h3>Leave a Reply</h3>
      ...
   </form>
</code>
   .../body>

Becomes:

   <body...
<code>
   <form method="post" id="commentform" class="encouraged-form">
      <h3>Leave a Reply</h3>
      ...
   </form>
</code>
   .../body>

Quotable Comments

For quotable comments things are a little different. Here you must refrain from using the quotable class and instead follow some basic conventions in your comment markup. First, give the HTML object that contains all of your comments the class ‘commentlist’ then make sure every individual comment has the class ‘comment’ applied to it.

Setup the Comment List Container

In many blogging systems you may have a heading for your comments. This traditionally has the id of comments. Somewhere below that is a list of responses to your article. This can either be a ol, ul, or div. Wordpress, for example, traditionally uses an ol in most cases. To designate your comment container just add the class ‘commentlist’ to this element.

This:

   <body...
<code>
   <div id="blog-entry" class="quotable">
      ...
   </div>
   <h3 id="comments">3 Comments</h3>
   <ol>
      <li id="comment-35">
      ...
      </li>
   </ol>
</code>
   .../body>

Becomes:

   <body...
<code>
   <div id="blog-entry" class="quotable">
      ...
   </div>
   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist">
      <li id="comment-35">
      ...
      </li>
   </ol>
</code>
   .../body>

Designate Your Comments

You will need to ensure that every individual comment is contained in an element with a unique ID and has the class ‘comment’.

This:

   <body...
<code>
   <ol class="commentlist">
      <li id="comment-35">
      ...
      </li>
      <li id="comment-36">
      ...
      </li>
   </ol>
</code>
   .../body>

Becomes:

   <body...
<code>
   <ol class="commentlist">
      <li id="comment-35" class="comment">
      ...
      </li>
      <li id="comment-36" class="comment">
      ...
      </li>
   </ol>
</code>
   .../body>

Designate Comment Permalinks

Now we need to add a class to each permalink for an individual comment. Simply add the class ‘comment-permalink’ to the anchor of the permalink for that individual comment.

This:

   <body...
<code>
   <ol class="commentlist">
      <li id="comment-35" class="comment">
      ...
      <div class="comment-meta commentmetadata">
         <a href="#comment-35">January 4, 2009 at 4:27 pm</a>
      </div>
      ...
      </li>
   </ol>
</code>
   .../body>

Becomes:

   <body...
<code>
   <ol class="commentlist">
      <li id="comment-35" class="comment">
      ...
      <div class="comment-meta commentmetadata">
         <a href="#comment-35" class="comment-permalink">January 4, 2009 at 4:27 pm</a>
      </div>
      ...
      </li>
   </ol>
</code>
   .../body>

Designate Comment Authors

Next, you will need to designate the element in your HTML containing the comment’s author name. Simply add the class ‘comment-author-name’ to this element.

This:

   <body...
<code>
   <ol class="commentlist">
      ...
      <div class="vcard">
         <cite class="fn">
            <a href='http://example.com' rel='external' class='url'>Jon Doe</a>
         </cite> <span class="says">says:</span>      
      </div>
      ...
      </li>
   </ol>
</code>
   .../body>

Becomes:

   <body...
<code>
   <ol class="commentlist">
      ...
      <li id="comment-35" class="comment">
      <div class="vcard">
         <cite class="fn">
            <a href='http://example.com' rel='external' class='url comment-author-name'>Jon Doe</a>
         </cite> <span class="says">says:</span>      
      </div>
      ...
      </li>
   </ol>
</code>
   .../body>

Designate Comment Entry Content

Last but not least, you will need to wrap the body of your comment’s text in an with the class ‘entry-content’.

This:

   <body...
<code>
   <ol class="commentlist">
      ...
      <li id="comment-35" class="comment">
         <p>My comment is full of useful advice...</p>
         <p>And it goes on and on and on..</p>
         ...
         <p>Yeah it was a lengthy comment.</p>
         ...
      </li>
   </ol>
</code>
   .../body>

Becomes:

   <body...
<code>
   <ol class="commentlist">
      ...
      <li id="comment-35" class="comment">
         <div class="entry-content">
            <p>My comment is full of useful advice...</p>
            <p>And it goes on and on and on..</p>
            ...
            <p>Yeah it was a lengthy comment.</p>
         </div>
         ...
      </li>
   </ol>
</code>
   .../body>

Toggling Functionality

Sorted Commentary

To turn this feature on add the class “sorted-commentary” to the comment list container in your HTML.

This:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist">

Becomes:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist sorted-commentary">

Disable Related Comments:

To turn this feature off add the class “no-relatives” to the comment list container in your HTML.

This:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist">

Becomes:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist no-relatives">

Disable Related Replies:

To toggle this feature off add the class “no-replies” to the comment list container in your HTML.

This:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist">

Becomes:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist no-replies">

Disable Comment Quote Button:

To toggle this feature off add the class “no-quote-control” to the comment list container in your HTML.

This:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist">

Becomes:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist no-quote-control">

Disable Comment Reply Button:

To toggle this feature off add the class “no-reply-control” to the comment list container in your HTML.

This:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist">

Becomes:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist no-reply-control">

Disable Comment Lightbox:

To turn this feature off add the class “no-lightbox” to the comment list container in your HTML.

This:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist">

Becomes:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist no-lightbox">

Disable Comment Preview:

To turn this feature off add the class “no-preview” to the comment list container in your HTML.

This:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist">

Becomes:


   <h3 id="comments">3 Comments</h3>
   <ol class="commentlist no-preview">

Dependencies

This project relies on jQuery and the jQuery ScrollTo plugin.

Next Steps / Ideas

IE6/7/8 Support: It looks like there is an error with the text highlight functionality in IE. If a user highlights some text in IE7 and responds to a comment the directive is not caught. I believe it has something to do with the target that is being captured from the onMouseUp listener.

Build Quote HTML on Submit: Instead of embedding straight HTML, add a user control to the comment form showing the quote and target author. This will allow the user to enter their comment in as normal while having the HTML output created on form submit.

Add live preview support: Allow the user to see a live preview of their comment with response and target author as they type their comment. This will provide the user better feedback as to what has happened now that they have utilized this advanced commenting system.

Lightbox Form: Users are not anticipating the page scroll to the bottom of the page. Instead it may be more applicable to present the comment form in a lightbox.

Looser coupling: The code in my example is very tightly coupled to my markup. It would be better to provide a good convention which would allow others to incorporate this functionality into their site without overhauling their markup.

Toggling functionality: For this proof of concept I wanted to incorporate all of my ideas. Text highlighting, related comments, related replies, and basic quote/reply buttons. It would be better if authors could easily adjust the script to toggle any of that functionality on or off should they only prefer to utilize some of these ideas.

Improved demo CSS: Right now I’m linking to my site’s stylesheet in the demo.html file. It would be better to provide a basic custom CSS file with the minimal rules so that folks can easily see what styling is involved to customize the presentation of these utilities.