Improve wp_list_comments() comment markup

[lancewillett]

The default comment markup generated by wp_list_comments() needs a small revamp. This will potentially help theme authors avoid using their own comment callback functions by incorporating a structure popularized by the last two default themes.

Twenty Twelve, for example, could almost drop the custom comments callback in functions.php with these improvements, with the exception of not being able to use HTML5 semantic elements instead of divs.

Patch has code cleanup and improvements to the comment-template.php file, including:

start_lvl()

• Use double quotes for HTML output

end_lvl()

• Add in .children end element HTML comments

start_el()

• Add switch statement for handling pingback/trackback first, to run before "other" types of comments
• Add pingback/trackback HTML output based on Twenty Ten / Eleven: much simpler than normal comments
• Wrap comment_text() in a div element so it can be styled separately
• Change comment-awaiting-moderation to be wrapped in a paragraph element, removing presentational line break
• Use updated comment-meta data based on Twenty Ten / Eleven: include an author link (if it exists), better time/date formatting, and use esc_url instead of htmlspecialchars
• Add in several end element HTML comments
• Fix spacing around parens
• Better indenting for PHP and HTML code throughout

end_el()

• Fix spacing around parens
• Add in #comment-## end element HTML comments

[nacin]

comment-awaiting-moderation was added in #15206. I agree that the <br/> is lame.

Curious to hear about any backwards compatibility concerns and considerations.

[lancewillett]

Back compat concerns are class and ID name changes, which I considered and tried to keep as minimal as possible.

If themes are not currently using a custom callback they might need small CSS tweaks to selectors for .comment-body.

[lancewillett]

Also, if this lands in trunk soonish, I could test it out with all the WP.com themes to see if there are serious back compat issues.

[lancewillett]

Second pass, revert changes to existing class values and markup

[lancewillett]

I redid my changes after a bunch of testing on WP.com, with themes that do not have a custom comment callback.

The patch now is back to simply improving code quality, and only adding in classes and markup, not changing existing markup and styles.

[lancewillett]

Better back compat markup for pingback/trackback case

[lancewillett]

New patch handles back compat for pingbacks/trackbacks.

Found a small issue for back compat: the pingback element should be a div with class of "comment-body" so that previous styles won't break.

Props chellycat (Michelle Langston) for help in testing and for catching the pingback class issue.

Tested with themes that don't use a custom comments callback: Brand New Day, Chunk, Clean Home, Contempt, Dusk to Dawn, Fleur, Greyzed, Grid Focus, Manifest, Oulipo, Quintus, Retro Mac OS, Selecta, Structure, and Wu Wei.

[kobenland]

Out of curiosity (in 20088.3.diff):

• Is there a reason you used esc_html() rather than esc_url() on line 1374?
• Would it make sense to use wp_parse_args() on line 1388?

[lancewillett]

Use esc_url properly, props kobenland

[lancewillett]

Replying to kobenland:

• Is there a reason you used esc_html() rather than esc_url() on line 1374?

Good eye, fixed in new patch.

• Would it make sense to use wp_parse_args() on line 1388?

I don't think it helps in this case. What do you think is the benefit?

[kobenland]

I thought for consistency with how merging arguments in WP is handled. But you're right, it'll use array_merge() anyway at some point.

[nacin]

We need this to not change any existing themes. That means new arguments for wp_list_comments().

Thoughts:

• You can currently specify 'style' => div, ol, or ul. You should also be able to specify tags and wrappers to the point where you can re-create the markup in Twenty Twelve.

• Repositioning the body inside a div might require a wrapper => false by default.

• For pingbacks, you should be able to specify 'ping_style' => 'concise' or something along those lines.

• We may be able to get away with converting <em class="comment-awaiting-moderation"></em><br /> to <p class="comment-awaiting-moderation"></p>. May.

Beyond those rough guidelines put together in about 5 minutes, I'd just see what you can come up with.

[lancewillett]

Added #22005 for Twenty Twelve compatibility. It's really close to freeze for 1.0 (today!) so we might need to punt.

[obenland]

Built 20088.5.diff​ off of Lance's patch and I think I hit four out of four on Nacin's guidelines. :)

Two things I'm not completely happy with yet:

• Naming of the new arguments for wp_list_comments()
• Switch of the old and new way of displaying the comment meta part

I'd love to hear you opinions!

[obenland]

New patch, introducing protected methods for better back/forward compat.

[lancewillett]

See also #23128 for retrofitting Twenty Twelve a bit, for better "bypostauthor" comment markup.

[georgestephanis]

RE: #15080 and [23667] we may want to change the default $format from an empty string to 'xhtml' for clarity's sake.

[georgestephanis]

(Patch attached changed 'markup' argument default from empty string to xhtml and tweaked the comment a touch.

No functional changes.

[obenland]

Latest patch switches to 'format' as designation for HTML5 support, to be in line with #15080 and #15081. Also adopts the 'div-comment-##' in HTML5 comments for the reply form to be added inside the <li>.

[markjaquith]

In 23694:

Improve wp_list_comments() markup.

• Whitespace cleanup
• Accepts format=html5 which uses some of the HTML5 elements
• Some helpful HTML comments to help untangle the HTML
• Other misc code cleanup

props lancewillett, obenland, georgestephanis. fixes #20088.

[lancewillett]

In 23696:

Twenty Thirteen: remove custom comment callback in favor of core comment_form() defaults. Props obenland, closes #22005. See #20088.

[SergeyBiryukov]

#14697 was marked as a duplicate.