|
This page last changed on May 17, 2012 by adam.kane@involver.com.
Overview
The paginate tag delineates a section of sml as automatically re-renderable. Markup enclosed by the paginate block will be automatically refreshed with a new page of data when a user clicks one of the generated pagination links.
Caching Considerations
This tag has no caching considerations.
Attributes
| name |
type |
required |
description |
| per_page |
int |
no |
The number of collection items to display per page. The default is 10. |
| page |
int |
no |
The initial page to display. Default is page 1.
|
| order |
string |
no |
The ordering of the items specified by the following syntax:
(created_at | updated_at | view_count | vote_count | fb_like_count) ASC or DESC .
Example: order: "created_at DESC"
|
| previous_label |
string |
no |
text/html to use as the pagination previous link label. Default is
« Previous |
| next_label |
string |
no |
text/html to use as the pagination next link label. Default is
Next » |
| page_links |
boolean |
no |
Set to true if page link numbers should be displayed. Default is true |
| inner_window |
int |
no |
Number of links are around the current page number. Default is 4. |
| outer_window |
int |
no |
Number of links are shown around the first and last pages. Default is 1. |
| gap_marker |
string |
no |
text/html to display between page link gaps. The default is "..." |
| loading_image |
string |
no |
The URL of an image to display during page load. A value of "true" can also be specified, in which case a default loading image will be displayed. No loading image will be displayed if this attribute is not present or is "false".
|
| before_send |
string |
no |
Javascript code to execute before an ajax call for the next page is sent.
|
| on_page_load |
string |
no |
Javascript code to execute after a new page has been rendered. |
| on_error |
string |
no |
Javascript code to execute if an ajax error occurs. The default handler will display an error dialog. |
| keywords |
string |
no |
Comma separated list of keywords. Checks the content item for whether the keyword is present. When multiple keywords are specified it will call content items that use any of them. Note: You may also specify the literal * to show all entries. |
Context Variables
| name |
type |
description |
| current_page |
int |
The current page number |
| total_pages |
int |
The total number of pages |
| total_entries |
int |
The total number of entries. (eg. the sum of all entries on each page over all pages.)
|
| pagination_links |
html |
The page links pre-rendered as html.
|
| <collection_name> |
array |
The name of the collection that is declared in the paginate tag is available as an array in the tag body. For example: {% paginate poll.poll_items %}
will insert a poll_items context variable that can be iterated over using a {% for %} block. e.g. {% for poll in poll_items %}
|
HTML Rendered by pagination_links Tag (Example):
<div class="paginate-links">
<span class="paginate-previous disabled">« Previous</span>
<span class="paginate-number paginate-current">1</span>
<span class="paginate-number"><a href="">2</a></span>
<span class="paginate-gap">...</span>
<span class="paginate-number"><a href="">11</a></span>
<span class="paginate-number"><a href="">12</a></span>
<span class="paginate-next"><a href="">Next »</a></span>
</div>
There is a default space between each span. You can easily customize this if you wish. You can also customize the alignment of page numbers and the visual appearance.
NOTE: Previously the HTML structure applied the classnames "paginate-previous" and "paginate-next" directly to anchor tags instead of to span tags wrapping the anchor tags for previous and next link elements. This change may require you to update styles used in tabs created previously to this structural change. Other styles and classnames should work as before however. These HTML changes were made in order to make the structure of pagination elements more consistent and thus easier to style,
Custom CSS Examples:
Make space between numbers a bit wider:
.paginate-links span {margin-left: 10px;}
Align page numbers in center:
.paginate-links {text-align: center;}
Align previous and next links to right and left with page numbers in the middle:
.paginate-links {text-align: center;}
.paginate-previous, .paginate-next
{position: absolute;
top: 0;}
.paginate-previous {left: 0;}
.paginate-next {right: 0;}
Examples
A basic pagination block that displays 10 poll items per page and the pagination links.
{% poll %}
{% paginate poll.poll_items per_page: 10 %}
<ul>
{% for poll in poll_items %}
<li>
{{ poll.title }}
</li>
{% endfor %}
</ul>
{{ pagination_links }}
{% endpaginate %}
{% endpoll %}
Using the order option
{% twitter_feed %}
{% paginate twitter_feed.tweets per_page:3 order:'published_at DESC, created_at DESC' %}
<ul>
{% for tweet in tweets %}
<li>
{{ tweet.title | twitter_link | auto_link }}
<span class="timestamp">{{ tweet.published_relative_time }}</span>
</li>
{% endfor %}
</ul>
{{pagination_links}}
{% endpaginate %}
{% endtwitter_feed %}
Using a custom Javascript function to show/hide a progress bar.
<script type="text/javascript">
function showCustomSpinner() {
}
function hideCustomSpinner() {
}
</script>
{% poll %}
{% paginate poll.poll_items per_page: 10 before_send: 'showCustomSpinner();' on_page_load: 'hideCustomSpinner();' %}
<ul>
{% for poll in poll_items %}
<li>{{ poll.title }}</li>
{% endfor %}
</ul>
{{ pagination_links }}
{% endpaginate %}
{% endpoll %}
Hiding the next/previous labels
You can hide the next and previous labels by setting the labels to single-space strings.
{% paginate rss_feed.feed_items next_label: " " previous_label: " " %}
...
{{ pagination_links }} <!-- Will only show page numbers -->
{% endpaginate %}
FAQ
There are currently no FAQ questions for this tag.
|
