Pagination is plugin for Movable Type that enables you to paginate lists of entries. For example, at the bottom of your home page, you could add a "Next" link so your readers can go to "Page 2" and read previous entries. You can display a list of linked page numbers to enable visitors to jump to any page number they want.
With Pagination Pro, you can also paginate your Category, Author, and date-based archives, and even paginate your Entry archives, displaying only a small number of comments on each page. New in version 1.5: You can also paginate long entries by splitting them up into multiple pages.
New Features in Pagination 1.5
- Support for MT 4.2 (minor bug fixes that may affect some sites running MT 4.2+)
- New template tags for next / previous page numbers
- Split long entries into multiple pages by easily inserting page breaks (Pro only)
Try it Now - Live Demo
The MT4 Test Blog has the Pagination Pro plugin enabled. Scroll to the bottom of the home page to see the list of pages and follow the links. Also take a look at an example of a paginated Category archive here. Finally, take a look at a paginated version of a 300+ comment entry here.
New: Paginated Entry Example - ReadWriteWeb
The latest version of the Pagination plugin is used by the popular technology blog ReadWriteWeb. (Disclosure: I provide consulting services to RWW) In additional, using Pagination to paginate the home page, category, and monthly archives, you can click here for an example of a long entry that has been split into 2 pages.
How it Works
My goal here was to create a pagination plugin with high performance. I didn't want it to slow down rebuilds, and I wanted pages to display for readers without delay. With these goals in mind, I decided to dynamically render pages 2, 3, 4, and so on. This means that unlike the default for most pages in Movable Type, pages 2+ are not static files that get published to your blog directories. They dynamically rendered by the plugin's page viewer script. Note that this viewer script is Perl-based and does not use MT's built-in PHP-based dynamic publishing system. The benefit of this is that you can virtually any plugin template tags in your paginated templates, and you don't need to use PHP. So when someone views page 2, the script goes into action and builds the page and displays it.
Paginated URLs are clean, ending in index.html?page=2 (or similar). Pagination makes use of mod_rewrite for Apache to keep these URLs clean (most MT sites run on Apache, but there may be some alternative approaches for other web servers).
Page-Level Caching
To speed up dynamic page views and reduce CPU/memory/database usage, Pagination supports (optional) page-level caching, powered by the Cache Block plugin. This means that once the plugins generates the HTML for "page 2", it will store that in the cache for next time. And next time someone wants to see "page 2", it can be quickly fetched from the cache. In my tests, dynamic page views from the cache took about 0.04 seconds, so this is very fast. In the plugin settings you can specify how long to cache pages before refreshing the cache.
Template Tags
Pagination comes with a template module that makes it easy to implement -- in most cases you can simply include the module in your existing templates and it will 'just work'. So you may not need to learn or use the template tags below. But if you want to customize the appearance of your Pagniation links, you can use/edit the following tags:
- <mt:PaginationPages> - This is a container tag for displaying linked page numbers, previous / next page links, etc. This tag should only be placed inside the following containers: <mt:EntriesFooter>, <mt:EntriesHeader>, <mt:CommentsFooter>, and <mt:CommentsHeader>. There are several arguments:
- max_pages - (Required) The maximum number of page numbers to display at one time. Note that page numbers will roll forward as readers view higher page numbers, just like Google paginated search results.
- glue - (Optional) This should contain some text or symbols that you to display bewteen each page number. For example, if you want 1 - 2 - 3, then use glue=" - ".
- lastn - (Required) The number of items shown on each page. This must match the lastn argument of the parent <mt:Entries> or <mt:PaginatedComments> tag.
- archive_type - (Optional) For advanced use, you can use this tag to override the archive_type used to calculate the page numbers and links. If omitted, the plugin will use the archive_type of the page being built.
- class_type - (Optional) For advanced use, this tag will override the type of MT object being counted to determine the number of pages.
- <mt:PaginationPageNumber> - Used inside a <mt:PaginationPages> container, this tag will display the page number being processed in the loop (not the current page number that is being published/viewed).
- <mt:PaginationPageLink> - Used inside a <mt:PaginationPages> container, this tag will display the URL to page number being processed in the loop.
- <mt:IfPreviousPage> - Conditional tag that is true if the page being displayed is 2 or higher.
- <mt:PaginationPreviousPageLink> - The URL to the previous page.
- <mt:IfNextPage> - Conditional tag that is true if the currently viewed page is not the last page.
- <mt:IfNotLastPage> - Conditional tag that is relative to the page being processed, not the page being viewed - returns true if the page being processed is not the final page.
- <mt:LastPageLink> - The URL to the last page.
- <mt:LastPageNumber> - The number of the last page.
- <mt:NextPageNumber> - The number of the next page.
- <mt:PreviousPageNumber> - The number of the previous page.
- <mt:PaginatedComments> - (Pro only) This is replacement container tag for <mt:Comments>. If you want to paginate the list of comments on an Entry archive, you should use <mt:PaginatedComments> instead of <mt:Comments>. You can use all the same <mt:Comment_____> tags inside the container. Arguments include:
- show - The number of comments to show per page. (Note that you can also use 'lastn' for this argument)
- offset - The offset for the page of comments. This should always be set to "$pagination_offset".
Template Tags for Entry Pagination
A new feature in Pagination Pro enables you to split long entries into multiple pages by adding <!--nextpage--> (on a line by iteself) when writing the entry, in either the main "Body" or "Extended" fields. Then, using the following template tag modifer or tags, you display only the current "part" of the entry, along with pagination links. Note: in order to differentiate this type of pagination, the term "part" is used instead of "page" -- think of it as splitting an entry into multiple parts.
(Note that using <!--nextpage--> for page breaks is consistent with the built-in feature of Wordpress. This consistency may come in handy for sites migrating from WP to MT, as the existing page breaks should "just work".)
The easy way to use this feature is to use a new modifier called paginate on the tag that you want to split into parts for example:
<mt:EntryBody paginate="1">
or
<mt:EntryMore paginate="1"> (if your page breaks are added to the "Extended" field)
Simply add the paginate="1" argument to your existing tags in your Entry archives and MT will display only the relevant part of the field, along with pagination links at the bottom.
If you want more flexibility, instead of using the modifier described above, you can use the following template tags to control the display of the parts and page numbers:
- <mt:PaginatedTag> - This container is designed to container the part(s) and page links for a paginated Entry Field. There is one required argument:
- tag - The tag with the page breaks, without the "mt:" prefix. Valid values are 'EntryBody' and 'EntryMore'. Example: <mt:PaginatedTag tag="EntryBody">
- <mt:CurrentPart> - This tag displays the current part of the tag (part 1 on page 1, part 2 on page 2, etc.). This tag must be used inside a <mt:PaginatedTag> container.
- <mt:Parts> - This container tag list the pages and page links for each part, if page breaks exist in the specified tag. This tag must be used inside an <mt:PaginatedTag> container. There is one optional argument:
- glue - the value of glue will act as a separator between each part number. Example: <mt:Parts glue=" | ">
- <mt:PartNumber> - Displays the part number.
- <mt:PartLink> - Displays the URL that links to page for the part.
- <mt:IfPreviousPart> - Conditional tag that is true if the part being displayed is 2 or higher.
- <mt:PreviousPartLink> - The URL to the previous part.
- <mt:IfNextPart> - Conditional tag that is true if the currently viewed part is not the last part.
- <mt:NextPartLink> - The URL to the next part.
Variables: For advanced usage, several variables are set by the plugin. A global variable called 'current_part_number' will be assigned to the value of currently displayed part on pages 2+, but remains undefined on page 1. Within an <mt:Parts> container, a local variable called 'current_part' is assigned to a value of 1 if the part being processed is the currently displayed part. Finally, standard loop variables such as __first__, __last__, etc. are assigned and can be used inside <mt:Parts>
Complete Example:
<mt:PaginatedTag tag="EntryMore">
<mt:CurrentPart>
<mt:Parts glue=" ">
<mt:If name="__first__">
<div class="partination"><p><strong>Page:
<mt:IfPreviousPart>
<a href="<mt:PreviousPartLink>">« Prev</a>
</mt:IfPreviousPart>
</mt:If>
<mt:If name="current_part">
<mt:PartNumber>
<mt:Else>
<a href="<mt:PartURL>"><mt:PartNumber></a>
</mt:If>
<mt:If name="__last__">
<mt:IfNextPart>
<a href="<mt:NextPartLink>"> Next »</a>
</mt:IfNextPart>
</strong></p></div>
</mt:If>
</mt:Parts>
</mt:PaginatedTag>
Note: the template tags above will only work on templates published using MT's default "static" publishing system. The tags will generate an error if used on dynamically published templates.
Templates Set
Pagination comes with two templates:
- Pagination - A template module that can be included in other templates to display page links.
- HTACCESS for Pagination - An index template that builds the required mod_rewrite rules. Important: The output file for this template has been set to "htaccess.txt" on purpose. Some sites have already have a ".htaccess" file and you want to be careful not to overwrite the existing one (for example, if you use MT's PHP dynamic publishing, with my Fast Search plugin or otherwise). Check to see if you already have an .htaccess file and if you do, you may want build this template as "htaccess.txt" and then copy and paste the rules into the appropriate place in your .htaccess file (if using MT's dynamic publishing, paste before the existing rules.) If you want to use this template to build your .htaccess file, you will need to change the output file to ".htaccess".
Requirements
Note: while not required, the Cache Block plugin is needed if you want to use the Pagination caching features (highly recommended).
Installation
- Download the zip file and upload the contents of the 'plugins' folder to the 'plugins' directory of your MT installation.
- Change the permissions of the /plugins/Pagination/pages.cgi script to 755 (CHMOD 755).
- Go to the blog you want and then to Preferences > Plugins and then open the settings for the Pagination plugin. Enable the caching settings if desired, then Save.
- Return to the settings and click the "Install Templates" button. This will install the templates mentioned above.
- Setup your .htaccess file with the Pagination rules, as described above.
- Edit your Main Index template and add the following before the </MTEntries> tag:
<mt:EntriesFooter>
<mt:Include module="Pagination">
</mt:EntriesFooter>
- Modify your <MTEntries tag to include the argument offset="$pagination_offset". This is important. Example: <MTEntries lastn="10" offset="$pagination_offset">
- (Pro only) Do the same for your "Entry Listing" archive template, for both MTEntries containers.
- (Pro only) If you want to paginate your comment listings on your Entry archives, edit the "Comments" template module to replace the <MTComments> container with the MTPaginatedComments container, as discussed above. Be sure to include show="10 offset="$pagination_offset".
- (Pro only) If you want to paginate long entries on your Entry archives, edit your Entry archive (or relevant template module) to replace or modify the EntryBody or EntryMore tags, as described above.
Get Pagination Pro
Commercial License for 1 to 10 blogs - $97
">
Blog Network License for 10+ blogs - $249
">
Personal License for 1 to 4 blogs - $33
">
Get Pagination
Pagination is free for personal or commercial use, but you must leave the "powered by" link, which is added automatically below the paginations links.
Download Now
,<$MTAjaxRatingVoteCount type="paginationdownloads" id="1"$>,0);">
Downloads: <$MTAjaxRatingVoteCount id="1" type="paginationdownloads"$>
As always, comments, questions, and suggestions are welcome.
]]>
Follow @mthacks on Twitter for updates and other MT and Twitter hacks.
