Render Comments
The method renderComments() enables you to output your Blog Posts' comments.
<?php /** * Render a list of comments. * * If page is editable, then non-approved comments will be included (and identified) in the list. * * @access public * @param CommentArray $comments * @param int $limit Optional limit of maximum comments to show * @param array $options Optional text describing a post's commenting status (e.g. 'comments not allowed') * @return $out string * */ public function renderComments(CommentArray $comments, $limit = 0, Array $options = null)
The method accepts three arguments, $comments, $limit and $options.
The first argument $comments is required and has to be an array of comments (i.e. CommentArray). This type of array is returned when you query a ProcessWire comments field.
The second argument $limit is optional and if set, will limit the number of comments that will be shown. If set, it has to be an integer. The default value is set to 0, meaning show all available comments.
The third argument $options is also an optional array. Using this argument, users can customise the text ouput to describe a Post's commenting status. For instance, if you wanted to disallow the posting of new comments on a particular Blog Post, your site visitors could be greeted by the message 'Comments not allowed for this post.' at the bottom of the Post. However, note that the descriptive texts about commenting status of a Blog Post are just that; They do not determine the status itself. So, if you needed to lock down commenting or close commenting after a certain number of comments, etc, you have to do that via the Blog Manager itself. Such can be done both on a Blog-wide basis or on a Post by Post-basis. Additionally, using the $options argument, you can enable the requirement that users need to be logged in in order to comment on a Blog Post. In such a case, the comments' form will be hidden until the user is logged in. The default is not to require a login before users can comment on a Post. If you wish to use the argument $options, it must be an array formatted as depicted in the following code. The code shows the default 'key'=>'value' pairs that will be used by renderComments() in case you haven't set custom values. Your custom array $options, if used, must have identical 'keys' to the ones below.
<?php
$defaultOptions = array(
'comments_closed' => $this->_('Comments closed for this post.'),//string: message when comments closed
'comments_disallowed' => $this->_('Comments not allowed for this post.'),//string: message when comments not allowed for post
'comments_empty' => $this->_('Be the first to comment'),//string: message when there are no comments for post
'comments_login' => $this->_('You need to log in to comment.'),//string: message when comment form hidden until user logs in
'comments_login_required' => false,//bool: if user needs to login before commenting [default is false - they don't need to log in first]
);
Let's now look at a couple of examples of using renderComments().
Outputing comments on a Blog Post is as simple as doing the following. Please note, you only have to call the MarkupBlog module once per Template File! Once called, it will be available to you to ouput Posts, Comments, Categories, Tags, etc. In the code below, a call to MarkupBlog is included for completeness. If renderComments() is called in your blog-post.php Template File (or your equivalent Template File for the Template 'blog-post'), the current Blog Post's comments will be output together with the comments' form. This supposes that you haven't overriden comments visibility as mentioned above. In case there are no comments yet, an appropriate descriptive message (either from the default $options values or your custom one) will be displayed instead.
<?php
//first we call MarkupBlog ONLY IF WE HAVEN'T ALREADY
$blog = $modules->get("MarkupBlog");
//we pass the required first argument $comments to renderComments().
//In this case, it is a CommentArray built from the comments field called 'blog_comments' found on the current page
echo $blog->renderComments($page->blog_comments);//If comments found, echo them out
We can also easily grab comments from any other page as shown below. In this case though, a comment form will not be displayed. A comment form is only displayed when on a Blog Post page where commenting is not disallowed. MarkupBlog also has a related method to display summarised comments' meta information from other Blog Posts that is especially useful as side content on your Blog. We will look at this method, findRecentComments(), in a subsequent lesson.
<?php
//first we call MarkupBlog ONLY IF WE HAVEN'T ALREADY
$blog = $modules->get("MarkupBlog");
//we pass the required first argument $comments to renderComments().
//In this case, it is a CommentArray built from the comments field called 'blog_comments' found on the page titled 'Web Technology'
$p = $pages->get('template=blog-post, title=Web Technology');
if (count($p->blog_comments)) {
echo $blog->renderComments($p->blog_comments);//If comments found, echo them out
}
The argument $limit when set to anything other than the default 0 works best when renderComments() is used in conjunction with the method findRecentComments(). In such a case, the Template of the page from which the combination of these two methods is called must be set to allow page numbers as the comments found, if greater than the value of $limit set will result in the comments being paginated. As mentioned, we will look at findRecentComments() in a follow-up lesson so we will revisit the argument $limit. Note however, that currently, using $limit with a value greater than 0 on a Blog Post (i.e. on a page using the Template blog-post) will not produce expected results. At the moment, it is not possible to paginate the comments when viewing an individual Blog Post.
When it comes to the argument $options, if you want to customise the descriptive texts, you do not have to customise all the available values in $options. You may decide to use some of the defaults and customise others. This is best shown by an example. In the code below, we have changed a couple of the commenting status description texts as well as require a user to be logged in before they can comment. Where we haven't specified a 'key'=>'value' pair, the default (as was shown above) will stand. We then passed the array $options as a third argument to renderComments(). Note that because we are passing a third argument, we need to specify the second argument also otherwise our $options will be pass as the second argument to renderComments() and that will have no desired effect. To do this properly as well as let the method use the default $limit setting, we specify the second argument as null as seen in the code below.
<?php
//out custom comments descriptive texts where we wish the defaults to be overriden
$options = array(
'comments_closed' => 'Sorry. Comments are now closed.',//message when comments closed
'comments_empty' => 'No comments found.',//message when there are no comments for post
'comments_login' => 'Log in first to comment.',//message when comment form hidden until user logs in
'comments_login_required' => true,//we require user to log in before they can comment
);
//we call MarkupBlog
$blog = $modules->get("MarkupBlog");
//we pass the 2nd argument as null since we want to use the default value
//we pass our custom 3rd argument $options. Only stated values will override the corresponding default key values
//we render comments found on this Blog Post page
echo $blog->renderComments($page->blog_comments, null, $options);
Next, we look at the HTML output of renderComments().
renderComments() HTML output
This sample code shows the typical HTML output of renderComments(). As mentioned previously, the comments form will only be output depending on the comments visibility settings. The descpritive comments status texts are wrapped in <h4> tags with IDs (see renderComments() CSS below).
<div id="comments">
<!-- icon showing number of comments found -->
<span class="num-comments-icon">2</span>
<!-- comments title -->
<h4>Comments</h4>
<ul class="comments CommentList">
<!-- 1st comment -->
<li class="comment CommentListItem" id="comment1">
<!-- comment author, date and time -->
<p class="comment-head CommentHeader">Comment by kongondo on 13 April 2014 11:16 pm</p>
<!-- comment body/text -->
<div class="comment-body CommentText">
<p>Simply the best CMS out there. Beauty and simplicity! ProcessWire is designed to have an approachable simplicity that is retained regardless of scale. Simplicity often implies reduced capability, and this is not the case with ProcessWire. From the surface, there is very little complexity and the application requires no training. Learn more about what makes ProcessWire unique.</p>
</div>
</li>
<!-- 2nd comment, etc -->
<li class="comment CommentListItem" id="comment10">
<!-- comment author, date and time -->
<p class="comment-head CommentHeader">Comment by kongondo on 23 May 2014 2:42 pm</p>
<!-- comment body/text -->
<div class="comment-body CommentText">
<p>The best CMS! ProcessWire rocks, yeah!</p>
</div>
</li>
</ul>
<div id="CommentForm" class="CommentForm_new">
<h4>Post a comment</h4>
<!-- the comments form -->
<form id="CommentForm_form" action="./#CommentForm" method="post">
<p class="CommentForm_cite">
<label for="CommentForm_cite">Your Name</label>
<input type="text" name="cite" class="required" required="required" id="CommentForm_cite" value="kongondo" maxlength="128">
</p>
<p class="CommentForm_email">
<label for="CommentForm_email">Your E-Mail</label>
<input type="text" name="email" class="required email" required="required" id="CommentForm_email" value="kongondo@gmail.com" maxlength="255">
</p>
<p class="CommentForm_text">
<label for="CommentForm_text">Comments</label>
<textarea name="text" class="required" required="required" id="CommentForm_text" rows="5" cols="50"></textarea>
</p>
<p class="CommentForm_submit">
<button type="submit" name="CommentForm_submit" id="CommentForm_submit" value="1">Submit</button>
<input type="hidden" name="page_id" value="2488">
</p>
</form>
</div><!--/CommentForm-->
</div><!--/#comments-->
After a successful comments form submission, the following HTML replaces the above comments <form>. Clicking on the title of the Post restores the form.
<div id="CommentForm_success" class="CommentForm_success_success"> <p class="success pending">Your comment has been submitted and will appear once approved by the moderator.</p> </div>
renderComments() CSS IDs and Classes
The following are all the CSS IDs and Classes that are output by renderComments(). Please note that some tags have multiple classes.
div#comments {}
span.num-comments-icon {}
ul.comments, li.CommentList {}
li#comment1 {} /*note: the class itself is 'comment'. The number appended is the comment number*/
li.comment, li.CommentListItem {}
p.comment-head, p.CommentHeader {}
div.comment-body, div.CommentText {}
li#comment10 {} /*similar to above note - the comment number is appended to the class*/
li.comment, li.CommentListItem {}
p.comment-head, p.CommentHeader {}
div.comment-body, div.CommentText {}
div#CommentForm {}
div.CommentForm_new {}
form#CommentForm_form {}
p.CommentForm_cite {}
input#CommentForm_cite {}
input.required {}
p.CommentForm_email {}
input#CommentForm_email {}
input.required input.email {}
p.CommentForm_text {}
textarea#CommentForm_text {}
textarea.required {}
p.CommentForm_submit {}
button#CommentForm_submit {}
/*Comments status descriptive text tags*/
h4#comments-disallowed, h4#comments-closed, h4#comments-login, h4#comments-empty {}
/*Temporarily output after comments form submission*/
div#CommentForm_success {}
div.CommentForm_success_success {}
p.success, p.pending {}
Summary
This lesson focused on renderComments($comments, $limit=0, $options=null), the method used by MarkupBlog to render a Blog Post's comments. In conjunction with other methods, the function can also be used to render summarised, paginated comments, for instance, on a Blog comments page. See you in the next lesson.