Template library
Pagination of article lists
Pagination means dividing content into discrete pages, each displaying a page number. When a long list of search results is divided into more than one page, allowing the reader to proceed from page to page, that's pagination.
This chapter will introduce an easy way for pagination in the beginning. If you run a larger site, you should use the method explained further down in this chapter.
Pagination of a long article list
Usually you might want to split a long list of articles into pages. You might do this on Section pages to show all articles in that particular section, without requiring the reader to scroll down too much.
The simplest pagination with "next" and "previous" buttons will look like this:
{{list_articles length="10"}}
...
<!-- we want to have pagination at the end of article list -->
{{if $gimme->current_list->at_end}}
<!-- let's make sure that there are more articles-->
{{ if $gimme->current_list->count > $gimme->current_list->length }}
{{ if $gimme->current_list->has_previous_elements }}
<a href="{{ url options="previous_items" }}" title="">previous</a>
{{/if}}
{{ if $gimme->current_list->has_next_elements }}
<a href="{{ url options="next_items" }}" title="">next</a>
{{/if}}
{{/if}}
{{/if}}
{{/list_articles}}
Pagination with page numbers
To get this kind of pagination we need to dig into smarty code a little bit more. Please read the code. It is clear enough to get general idea how it works.
{{list_articles length="10"}}
...
<!-- we want to have pagination at the end of article list -->
{{if $gimme->current_list->at_end}}
{{ if $gimme->current_list->count > $gimme->current_list->length }}
{{ $page=intval($gimme->url->get_parameter($gimme->current_list_id())) }}
{{ $list_id=$gimme->current_list_id() }}
<!-- sets the length of article list -->
{{$listLength=10}}
{{assign var="allPages" value=($gimme->current_list->count/$listLength)|ceil }}
{{assign var="currentPage" value=$page/$listLength}}
{{assign var="firstToShow" value=$currentPage-2}}
{{assign var="lastToShow" value=$currentPage+5}}
{{if $firstToShow < 1 }}
{{assign var="firstToShow" value=1}}
{{assign var="lastToShow" value=$lastToShow+3}}
{{/if}}
{{if $lastToShow > $allPages }}
{{assign var="lastToShow" value=$allPages+1}}
{{/if}}
<nav class="bottom_nav pagination">
<!-- we are unsetting article to make sure that is not going to affect url -->
{{ unset_article }}
{{ if $gimme->current_list->has_previous_elements }}
<a href="{{ url options="previous_items" }}" class="float_left nav_button prev" title="">previous
</a>
{{/if}}
{{if $lastToShow-$firstToShow>0}}
<div class="numbers">
<ul>
{{if $firstToShow>1}}
<li class="firstlast"><a href="{{ url options="section" }}{{if $gimme->topic->identifier}}?tpid={{$gimme->topic->identifier}}{{/if}}">1</a></li>
<li class="firstlast">...</li>
{{/if}}
{{section name=foo start=$firstToShow loop=$lastToShow}}
{{if $smarty.section.foo.index-1==$currentPage}}
<li class="current">{{ $smarty.section.foo.index }}</li>
{{else}}
<li><a href="{{ url options="section" }}?{{$list_id}}={{ ($smarty.section.foo.index-1)*$listLength }}{{if $gimme->topic->identifier}}&tpid={{$gimme->topic->identifier}}{{/if}}">
{{ $smarty.section.foo.index }} </a></li>
{{/if}}
{{/section}}
{{if $lastToShow-1<$allPages}}
<li class="firstlast">...</li>
<li class="firstlast"><a href="{{ url options="section" }}?{{$list_id}}={{ ($allPages-1)*$listLength }}{{if $gimme->topic->identifier}}&tpid={{$gimme->topic->identifier}}{{/if}}">{{$allPages}}</a></li>
{{/if}}
</ul>
</div>
{{/if}}
{{ if $gimme->current_list->has_next_elements }}
<a href="{{ url options="next_items" }}" class="float_right nav_button next" title="">{{ if $gimme->language->english_name == "Georgian" }}შემდეგი{{elseif $gimme->language->english_name == "Russian"}}следующий{{else}}next{{/if}} »</a>
{{ /if }}
</nav>
{{ /if }}
{{/if}}
{{/list_articles}}
REALLY Advanced Pagination
Well it's not that advanced really but…
Consider a case where you may have differing numbers of articles in different parts of your section article lists. In the example below we have a section page that comes from our Rockstar theme where there are two lead articles before the standard listing begins.
{{ $listLength = 9 }}
{{ list_articles length=$listLength }}
{{ if $gimme->current_list->at_beginning }}
{{ if $gimme->current_list->index lte 2 }}
<section class="grid-2">
{{ else }}
<section class="grid-3">
{{ /if }}
{{ /if }}
{{ if $gimme->current_list->index lte 2 }}
<article>
{{ include file="_tpl/img/img_onehalf.tpl" }}
<small><a href="{{ url options='section' }}">{{ $gimme->section->name }}</a></small>
<h3><a href="{{ url options='article' }}">{{ $gimme->article->name }}</a></h3>
<p><span class="time">{{ $gimme->article->publish_date }}</span> /
{{ list_article_authors }}
{{ if $gimme->author->user->defined }}<a href="{{ $view->url(['username' => $gimme->author->user->uname], 'user') }}">{{ /if }}by {{ $gimme->author->name }}{{ if $gimme->author->user->defined }}</a>{{ /if }}
{{ /list_article_authors }}
</p>
<p>{{ include file="_tpl/_edit-article.tpl" }}{{ $gimme->article->deck|truncate:360 }}</p>
<span class="more"><a href="{{ url options='article' }}">+ {{ #readMore# }}</a> or <a href="{{ url options='article' }}#comments">{{ #addComment# }} ({{ $gimme->article->comment_count }})</a></span>
</article>
{{ /if }}
{{ if $gimme->current_list->index == 2 || ($gimme->current_list->at_end && $gimme->current_list->index lte 2) }}
</section><!-- / 2 article grid -->
{{ /if }}
{{ if $gimme->current_list->index == 3 }}
… do the rest of your code after this point
As you can see we're setting a list limit of 9 but the first page has 8 items due to the two proceeding lead articles.
To combat this we need to set the index back by one so that there's no gap in articles when we go from 8 to 9 elements.
This is as simple as altering this line in your pagination:
<li><a href="{{ url options="section" }}?{{$list_id}}={{ ($smarty.section.foo.index-1)*($listLength)-1 }}{{if $gimme->topic->identifier}}&tpid={{$gimme->topic->identifier}}{{/if}}">{{ $smarty.section.foo.index }}</a>
Of course your mileage may vary if you have rolled your own solution but the lesson to take away from this is that you can specify where the pagination index starts from but not reset the index programatically.
Good luck and happy paginating!