README

Download | Packagist | Issues | Support forum | Donate

Rah_comments lets you to paginate Textpattern CMS’ comment lists, splitting the long endless list of comments into multiple pages with fully customisable navigation.

The plugin is a module for etc_pagination, extending the core comment system and letting etc_pagination to work with it. Rah_comments does the background work such as URL routing and comment calculation, while etc_pagination takes care of rendering the pagination.

Install

Using Composer:

$ composer require rah/rah_comments:*

Or download a plugin package.

Requirements

• Textpattern 4.4.1 or newer.
• etc_pagination
• PHP 5.3.0 or newer.

Basics

Rah_comments is used together with etc_pagination to generate pagination for article comments, and comes with few tags that make core comment system and etc_pagination fully compatible.

All-in-all, rah_comments takes care of providing etc_pagination page count it uses to figure out what it needs to render, rewrites and reroutes comment URLs and smoothens the comment submissions process.

Two tags are included; rah_comments_numpages – the main that which acts as the etc_pagination glue and rah_comment_permlink, a replacement tag for comment_permlink.

The most basic usage case would involve calculating the number of pages using rah_comments, passing the value to etc_pagination and then using the core comments tag with a correct offset attribute passed to it:

<txp:variable name="numPages" value='<txp:rah_comments_numpages limit="10" />' />
<txp:etc_pagination pages='<txp:variable name="numPages" />' />
<txp:comments offset='<txp:etc_offset pageby="10" />' limit="10" />

The above is similar to any etc_pagination use case, but instead of using it’s etc_numpages, we’re using rah_comments_numpages.

Tags and attributes

rah_comments_numpages

<txp:rah_comments_numpages limit="10" />

Calculates and returns the number of comment pages, while doing some necessary background tasks. The number of pages is calculated based on the provided offset and limit attributes, and the resulting value should be passed to etc_pagination or similar pagination generator.

To the pagination to work properly, the tag needs that two attributes, limit and sort, are identically mirrored to match the values used in the paginated comments tag.

Attributes

limit
Number of comments displayed per page. This value should be identical to the limit you are using on the comments tag.
Default: "10" Example: limit="5"

sort
Comment sorting criteria. This value should be identical to the sort attribute you are using on the comments tag, if you are using any.
Default: "posted asc" Example: sort="posted desc"

offset
Number of comments skipped.
Default: "0" Example: offset="5"

parameter
The query string parameter the page number is passed in. This value should be set to match the parameter, pg_counter, you are using with etc_pagination.
Default: "pg" Example: parameter="pg"

rah_comment_permlink

<txp:rah_comment_permlink>
    ...contained statement...
</txp:rah_comment_permlink>

Renders comment permlink, used as comment_permlink tag’s replacement.

Attributes

anchor
Whether to apply the comment’s id to the hyperlink tag (as the id attribute), setting this comment permanent link as the comment page anchor.
Default: "1" Example: anchor="0"

Examples

Basic pagination

<txp:variable name="numPages" value='<txp:rah_comments_numpages limit="10" />' />
<txp:etc_pagination pages='<txp:variable name="numPages" />' />
<txp:comments offset='<txp:etc_offset pageby="10" />' limit="10" />

The above renders 10 comments per page and displays page numbers above the comment list.

Recent comments

<txp:recent_comments limit="10" wraptag="ul" break="li">
    <txp:rah_comment_permlink><txp:comment_name link="0" /> (<txp:title />)</txp:rah_comment_permlink>
</txp:recent_comments>

The above renders last 10 comments on the website.

Changelog

Version 0.5.0 – upcoming

• Rewritten as etc_pagination module.
• Removed: rah_comments tag.
• Removed: rah_recent_comments tag.
• Added: rah_comments_numpages tag.
• Added: rah_comment_permlink tag.
• Updated: now shows the correct comment page after new comment submissions.
• Performance optimisations.
• Released as Composer package.

Version 0.4 – 2008/09/14

• Added <txp:rah_recent_comments /> tag.

Version 0.3 – 2008/09/03

• Removed attributes: break_nav and break_pages.
• Fixed messy url mode’s error: now works fully on messy.
• Added attributes: pg_break, pg_break_class, prepend and append.
• Now works in article lists, same way like <txp:comments />.
• Better documentation.

Version 0.2 – 2008/02/17

• Some minor bug fixes.
• Removed some typos from documentation.

Version 0.1 – 2008/02/16

• First release.