WordPress V3.xTemplate Tag Reference Guide as of Version 3.x
Presented by:
Comment Tags
Allowed Tagsallowed_tags();
Display all of the allowed tags in HTML format with attributes. This is useful for displaying in the comment area which elements and attributes are supported. Also helpful for any plugins which want to display it.
<?php allowed_tags(); ?>
No parameters.
Cancel Comment Reply Linkcancel_comment_reply_link();
Displays a link which cancels the replying to a previous comment (a nested comment) and resets the comment form back to the default state.
<?php cancel_comment_reply_link($text); ?>
$text
String • Default: 'Click here to cancel reply.'
(Optional) Text to display as a link.
Comment Authorcomment_author();
Displays the comment author name; that is, the one supplied by the commenter. If no name is provided (and "User must fill out name and email" is not enabled under Discussion Options), WordPress will assign "Anonymous" as comment author.
<?php comment_author($comment_ID); ?>
$comment_ID
Integer • Default: 0 (uses the current comment)
(Optional) The ID of the comment for which to print the author.
Comment Author Emailcomment_author_email();
Displays the comment author's email address, not linked. An email address must be provided if "User must fill out name and email" is enabled under Discussion Options.
<?php comment_author_email($comment_ID); ?>
$comment_ID
Integer • Default: 0 (uses the current domment)
(Optional) The ID of the comment for which to print the author's email.
Comment Author Email Linkcomment_author_email_link();
Displays the comment author's email address, as a mailto link. An email address must be provided if "User must fill out name and email" is enabled under Discussion Options. This tag must be within The Loop, or a comment loop. Note: Displaying email addresses is not recommended, as it provides spam collection tools the opportunity to cull them from your site. Use get_comment_author_email_link() to retrieve the value.
<?php comment_author_email_link($linktext, $before, $after); ?>
$linktext
String • Default: comment author's email address
(Optional) Link text for the email link.
$before
String • Default: ''
(Optional) Text to display before the link.
$after
String • Default: ''
(Optional) Text to display after the link.
Comment Author IPcomment_author_IP();
Displays the comment author's IP address. This tag must be within The Loop, or a comment loop.
<?php comment_author_IP($comment_ID); ?>
$comment_ID
Integer • Default: 0 (the current comment)
(Optional) The ID of the comment for which to print the author's IP address.
Comment Author Linkcomment_author_link();
Displays the comment author's name linked to his/her URL, if one was provided. Use get_comment_author_link() to retrieve the value.
<?php comment_author_link($comment_ID); ?>
$comment_ID
Integer • Default: 0 (the current comment)
(Optional) The ID of the comment for which to print the author's link.
Comment Author RSScomment_author_rss();
Display the current comment author in the feed.
<?php comment_author_rss(); ?>
No parameters.
Comment Author URLcomment_author_url();
Displays the comment author's URL (usually their web site), not linked. If the author provided no URL, this will display the URL of the current page instead. The tag get_comment_author_url returns an empty string in this case.
<?php comment_author_url($comment_ID); ?>
$comment_ID
Integer • Default: 0 (the current comment)
The ID of the comment for which to print the author's URL.
Comment Author URL Linkcomment_author_url_link();
Displays the comment author's URL (usually their web site), linked, if one was provided. This tag must be within The Loop, or a comment loop. Use get_comment_author_url_link() to retrieve the value.
<?php comment_author_url_link($linktext, $before, $after); ?>
$linktext
String • Default: comment author's URL
Link text for the link.
$before
String • Default: ''
Text to display before the link.
$after
String • Default: ''
Text to display after the link.
Comment Classcomment_class();
The comment_class() outputs the class="whatever" piece for that div. This includes several different classes of value: comment, even (or odd), thread-even, depth-1, etc. These make it easy to style different parts of the theme in different ways.
<?php comment_class($class); ?>
$class
String • Default: ''
(Optional) Adds a custom class to the class list.
Default Values
Specifically, it will apply the following classes, based on the following conditions:
comment_type:
For normal comments, adds class "comment". For all other types, it adds the value of the comment_type as the class.
user_id:
If the comment was made by a registered user, then adds class "byuser" and "comment-author-" + the user_nicename
sanitized (i.e. spaces removed). Also, if the comment is by the original author of the post, the class "bypostauthor" is added.
Odd/Even:
If the comment number is even, adds class "even". Otherwise, adds class "alt" and "odd".
Comment Depth:
The class "depth=" + the comment depth is always added.
Top-level Comments:
If comment depth is top level (1), then adds "thread-even" or "thread-alt" and "thread-odd"
depending on whether the comment number is even or odd.
Optional Class Parameter
If the optional class parameter is passed to comment_class(), then that class gets added to all the others.
This is useful for defining your own custom comment class.
Comment Datecomment_date();
Displays the date a comment was posted. Use get_comment_date() to retrieve the value.
<?php comment_date($d, $comment_ID); ?>
$d
String • Default: The date format set in WordPress
(Optional) Formatting for the date.
$comment_ID
Integer • Default: 0 (the current comment).
(Optional) The ID of the comment for which to print the date.
Comment Excerptcomment_excerpt();
Displays an excerpt (maximum of 20 words) of a comment's text. Use get_comment_excerpt() to retrieve the value.
<?php comment_excerpt($comment_ID); ?>
$comment_ID
Integer • Default: 0 (the current comment)
(Optional) The ID of the comment for which to print the excerpt.
Comment Form Titlecomment_form_title();
Displays text based on comment reply status. This only affects users with Javascript disabled or pages without the comment-reply.js JavaScript loaded. This tag is normally used directly below <div id="respond"> and before the comment form.
<?php comment_form_title($noreplytext, $replytext, $linktoparent); ?>
$noreplytext
String • Default: 'Leave a Reply'
(Optional) Text to display when not replying to a comment.
$replytext
String • Default: 'Leave a Reply to %s'
(Optional) Text to display when replying to a comment. Accepts "%s" for the author of the comment being replied to.
$linktoparent
Boolean • Default: true
(Optional) Boolean to control making the author's name a link to their comment.
Comment Formcomment_form();
This tag outputs a complete commenting form for use within a template. Most strings and form fields may be controlled through the $args array passed into the function, while you may also choose to use the comment_form_default_fields filter to modify the array of default fields if you'd just like to add a new one or remove a single field. All fields are also individually passed through a filter of the form comments_form_field_$name where $name is the key used in the array of fields.
<?php comment_form($args, $post_id); ?>
$args
Array
(Optional) Options for strings, fields etc in the form. Defaults:
| <?php $args = array( | ||
| 'fields' | => | apply_filters( 'comment_form_default_fields', $fields ), |
| 'comment_field' | => | '<p class="comment-form-comment"><label for="comment">' . _x( 'Comment', 'noun' ) . '</label><textarea id="comment" name="comment" cols="45" rows="8" aria-required="true"></textarea></p>', |
| 'must_log_in' | => | '<p class="must-log-in">' . sprintf( __( 'You must be <a href="%s">logged in</a> to post a comment.' ), wp_login_url( apply_filters( 'the_permalink', get_permalink( $post_id ) ) ) ) . '</p>', |
| 'logged_in_as' | => | '<p class="logged-in-as">' . sprintf( __( 'Logged in as <a href="%1$s">%2$s</a>. <a href="%3$s" title="Log out of this account">Log out?</a>' ), admin_url( 'profile.php' ), $user_identity, wp_logout_url( apply_filters( 'the_permalink', get_permalink( $post_id ) ) ) ) . '</p>', |
| 'comment_notes_before' | => | '<p class="comment-notes">' . __( 'Your email address will not be published.' ) . ( $req ? $required_text : '' ) . '</p>', |
| 'comment_notes_after' | => | '<p class="form-allowed-tags">' . sprintf( __( 'You may use these <abbr title="HyperText Markup Language">HTML</abbr> tags and attributes: %s' ), ' <code>' . allowed_tags() . '</code>' ) . '</p>', |
| 'id_form' | => | 'commentform', |
| 'id_submit' | => | 'submit', |
| 'title_reply' | => | __( 'Leave a Reply' ), |
| 'title_reply_to' | => | __( 'Leave a Reply to %s' ), |
| 'cancel_reply_link' | => | __( 'Cancel reply' ), |
| 'label_submit' | => | __( 'Post Comment' ), |
| ); | ||
| ?> |
$post_id
Mixed • Default: null (the current post)
(Optional) Post ID to generate the form for, uses the current post if null.
Comment IDcomment_ID();
Displays the numeric ID of the current comment. This tag must be within The Loop, or a comment loop. Use get_comment_ID to retrieve the value.
<?php comment_ID(); ?>
No parameters.
Comment ID Fieldscomment_id_fields();
Generates two hidden inputs for the comment form to identify the comment_post_ID and comment_parent for threaded comments. This tag must be within the <form> section of comments.php. New since WordPress version 2.7.
<?php comment_id_fields(); ?>
No parameters.
Comment Reply Linkcomment_reply_link();
Displays a link that lets users post a comment in reply to a specific comment. If JavaScript is enabled and the comment-reply.js JavaScript is loaded the link moves the comment form to just below the comment.
<?php comment_reply_link($args, $comment, $post); ?>
$args
Array
(Optional) Associative array of options. See below.
$comment
Integer • Default: null
(Optional) ID of comment being replied to.
$post
Integer • Default: null
(Optional) ID of post that comment is going to be displayed on.
Arguments for $args:
add_below
String • Defaults to 'post'
For the JavaScript moveAddCommentForm() function parameters.
respond_id
Integer • Defaults to 'respond'
For the JavaScript moveAddCommentForm() function parameters.
reply_text
String • Defaults to 'Reply'
Only used if they can post a reply.
login_text
String • Defaults to 'Log in to leave a comment'
Only used if the user must log in or register first before posting a comment.
depth
Integer
Comment Textcomment_text();
Displays the text of a comment. Use get_comment_text to retrieve the value.
<?php comment_text($comment_ID); ?>
$comment_ID
Integer • Default: 0 (the current comment)
(Optional) The ID of the comment for which to print the text.
Comment Text RSScomment_text_rss();
Display the current comment content for use in the feeds.
<?php comment_text_rss(); ?>
No parameters.
Comment Timecomment_time();
Displays the time a comment was posted. This tag must be within The Loop, or a comment loop.
<?php comment_time(d); ?>
d
String • Defaults to the time format set in WordPress.
Formatting for the time.
Comment Typecomment_type();
Displays the type of comment (regular comment, Trackback or Pingback) a comment entry is. This tag must be within The Loop, or a comment loop. Use get_comment_type to retrieve the value.
<?php comment_type('comment', 'trackback', 'pingback'); ?>
comment
String • Defaults to 'Comment'
Text to describe a comment type comment.
trackback
String • Defaults to 'Trackback'
Text to describe a Trackback type comment.
pingback
String • Defaults to 'Pingback'
Text to describe a Pingback type comment.
Comments Linkcomments_link();
The comments_link template tag displays the URL to the current post's comments. This tag must be within The Loop, or the loop set up for comments. Use get_comments_link to retrieve the value.
<?php comments_link(); ?>
No parameters.
Comments Numbercomments_number();
Displays the total number of comments, Trackbacks, and Pingbacks for the current post. This tag must be within The Loop. Use get_comments_number to retrieve the value.
<?php comments_number($zero, $one, $more); ?>
$zero
String • Default: 'No Comments'
Text to display when there are no comments.
$one
String • Default: '1 Comments'
Text to display when there is one comment.
$more
String • Default: '% Comments'
Text to display when there is more than one comment. % is replaced by the number of comments, so '% so far' is displayed as "5 so far" when there are five comments.
Comments Popup Linkcomments_popup_link();
Displays a link to the comments popup window if comments_popup_script() is used, otherwise it displays a normal link to comments. This tag must be within The Loop, or a comment loop, and it does nothing if is_single() or is_page() is true (even when within The Loop).
<?php comments_popup_link('zero', 'one', 'more', 'CSSclass', 'none'); ?>
zero
String • Defaults to 'No Comments'
Text to display when there are no comments.
one
String • Defaults to '1 Comments'
Text to display when there are no comments.
more
String • Defaults to '% Comments'
Text to display when there is more than one comment. % is replaced by the number of comments, so '% so far' is displayed as "5 so far" when there are five comments.
CSSclass
String • Default: none
CSS (stylesheet) class for the link.
none
String • Default: 'Comments Off'
Text to display when comments are disabled.
Comments Popup Scriptcomments_popup_script();
Outputs the JavaScript code for a comments popup window. Used in tandem with comments_popup_link(), this tag can be used anywhere within a template, though is typically placed within the <head> portion of a page.
<?php comments_popup_script(width, height, 'file'); ?>
width
Integer • Default: 400 (pixels)
(Optional) The width of the popup window in pixels.
height
Integer • Default: 400 (pixels)
(Optional) The height of the popup window in pixels.
file
String • Default: none
(Optional) Sets the location of the popup window.
Get Avatar get_avatar();
Retrieve the avatar for a user who provided a user ID or email address. Most commonly used in the comments section. This function is pluggable, however plugin authors wishing to change the gravatar output should use the get_avatar filter instead, for compatibility purposes.
<?php get_avatar($id_or_email, $size, $default, $alt); ?>
$id_or_email
Integer/String • Default: none
Author's User ID (an integer or string), an E-mail Address (a string) or the comment object from the comment loop. Note: with most comment templates you can use $comment here, in order to display the gravatar of the commenter. In other templates within The Loop, you can use get_the_author_meta('user_email').
$size
Integer • Default: 96
(Optional) Size of Gravatar to return (max is 512).
$default
String • Default: none
(Optional) URL for an image, defaults to the "Mystery Man".
$alt
String • Default: none
(Optional) Alternate text for the avatar.
Next Comments Linknext_comments_link();
Display link to the next comments pages.
<?php next_comments_link($label, $max_page); ?>
$label
String • Default: ''
Label for link text.
$max_page
Integer • Default: 0
(Optional) Max page.
Paginate Comments Linknext_comments_link();
Create pagination links for the comments on the current post. Basically this is a macro to paginate_links() which sets the functional options of paginate_links() to make it work for comments. But you may use all the parameters of paginate_links() to style the output of paginate_comments_links().
<?php paginate_comments_link($args); ?>
$args
String | Array
(Optional) Optional arguments. See paginate_links(). Defaults:
| <?php $args = array( | ||
| 'base' | => | add_query_arg( 'cpage', '%#%' ), |
| 'format' | => | , |
| 'total' | => | $max_page, |
| 'current' | => | $page, |
| 'echo' | => | true, |
| 'add_fragment' | => | '#comments' |
| ); | ||
| ?> |
These arguments are mostly to make the call of paginate_links() work, so be careful if you change them.
Peramlink Comments RSSpermalink_comments_rss();
Displays the permalink to the post to which a comment belongs, formatted for RSS. Typically used in the RSS comment feed template. This tag must be within The Loop, or a comment loop.
<?php permalink_comments_rss(); ?>
No parameters.
Previous Comments Linkprevious_comments_link();
Display the previous comments page link.
<?php previous_comments_link(); ?>
$label
String • Default: ''
(Optional) Label for comments link text.
WP List Commentswp_list_comments();
Displays all comments for a post or Page based on a variety of parameters including ones set in the administration area. Arguments are passed in as either an array or a query string.
| $args = array( | ||||
| 'walker' | => | null, | ||
| 'max_depth' | => | , | ||
| 'style' | => | 'ul', | ||
| 'callback' | => | null, | ||
| 'end-callback' | => | null, | ||
| 'type' | => | 'all', | ||
| 'page' | => | , | ||
| 'per_page' | => | , | ||
| 'avatar_size' | => | 32, | ||
| 'reverse_top_level' | => | null, | ||
| 'reverse_children' | => | false, | ||
| 'hierarchical' | => | null | ||
| ); | ||||
<?php wp_list_comments($args); ?>
avatar_size
Integer • Default: 32
(Optional) Size that the avatar should be shown as, in pixels. http://gravatar.com/ supports sizes between 1 and 512.
style
String • Default: 'ul'
(Optional) Can be either 'div', 'ol', or 'ul', to display comments using divs, ordered, or unordered lists. Note that there are containing tags that must be written explicitly such as <div class="commentlist"><?php wp_list_comments(array('style' => 'div')); ?></div> or <ol class="commentlist"><?php wp_list_comments(array('style' => 'ol')); ?></ol>
type
String • Default: 'all'
(Optional) The type of comment(s) to display. Can be 'all', 'comment', 'trackback', 'pingback', or 'pings'. 'pings' is 'trackback' and 'pingback' together.
reply_text
String • Default: 'Reply'
(Optional) Text to display in each comment as a reply link. (This isn't an argument of this function but it gets passed to the get_comment_reply_link function.)
login_text
String • Default: 'Log in to Reply'
(Optional) Text to display in each comment if users must be registered and logged in to comment. (This isn't an argument of this function but it gets passed to the get_comment_reply_link function.)
callback
String • Default: null
(Optional) The name of a custom function to use to display each comment. Using this will make your custom function get called to display each comment, bypassing all internal WordPress functionality in this respect. Use to customize comments display for extreme changes to the HTML layout. Use with caution.
reverse_top_level
Boolean • Default: null
(Optional) Setting this to true will display the most recent comment first then going back in order.
reverse_children
Boolean • Default: null
(Optional) Setting this to true will display the children (reply level comments) with the most recent ones first, then going back in order.