README.textile

March 23, 2015 · View on GitHub

h1. rah_comments

"Download":https://github.com/gocom/rah_comments/releases | "Packagist":https://packagist.org/packages/rah/rah_comments | "Issues":https://github.com/gocom/rah_comments/issues | "Support forum":http://forum.textpattern.com/viewtopic.php?id=26126 | "Donate":http://rahforum.biz/donate/rah_comments

Rah_comments lets you to paginate "Textpattern CMS'":http://textpattern.com "comment lists":http://www.textpattern.net/wiki/index.php?title=comments, splitting the long endless list of comments into multiple pages with fully customisable navigation.

The plugin is a module for "etc_pagination":https://github.com/bloatware/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.

h2. Install

Using "Composer":https://getcomposer.org:

bc. $ composer require rah/rah_comments:*

Or "download":https://github.com/gocom/rah_comments/releases a plugin package.

h2. Requirements

h2. 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":http://www.textpattern.net/wiki/index.php?title=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":http://www.textpattern.net/wiki/index.php?title=comments tag with a correct @offset@ attribute passed to it:

bc. <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@.

h2. Tags and attributes

h3. rah_comments_numpages

bc. <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.

h4. Attributes

limit Number of comments displayed per page. This value should be identical to the @limit@ you are using on the "comments":http://www.textpattern.net/wiki/index.php?title=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":http://www.textpattern.net/wiki/index.php?title=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"@

h3. rah_comment_permlink

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

Renders comment permlink, used as "comment_permlink":http://www.textpattern.net/wiki/index.php?title=comment_permlink tag's replacement.

h4. 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"@

h2. Examples

h3. Basic pagination

bc. <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.

h3. Recent comments

bc. <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.

h2. Changelog

h3. Version 0.5.0 - upcoming

  • Rewritten as "etc_pagination":https://github.com/bloatware/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":http://getcomposer.org package.

h3. Version 0.4 - 2008/09/14

  • Added @<txp:rah_recent_comments />@ tag.

h3. 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.

h3. Version 0.2 - 2008/02/17

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

h3. Version 0.1 - 2008/02/16

  • First release.