Difference between revisions of "Liquid Paginate Tag"
From Spiffy Stores Knowledge Base
(New page: The '''paginate''' tag is responsible for pagination within a Spiffy Stores template. It's currently applicable to collections, products and blog articles. By default the default limit of ...) |
m (→Usage) |
||
(9 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | The '''paginate''' tag is responsible for pagination within a Spiffy Stores template. It's currently applicable to collections, products and blog articles. By default the | + | The '''paginate''' tag is responsible for pagination within a Spiffy Stores template. It's currently applicable to collections, products and blog articles. By default the number of items that can be shown is 50, so if you want to show more, then you'll need to use the '''paginate''' tag. |
The built-in themes automatically use paginate for collections and blog pages. | The built-in themes automatically use paginate for collections and blog pages. | ||
− | ==Usage== | + | == Usage == |
− | To use pagination you have to wrap | + | <gallery heights="200px" widths="200px" class="right"> |
+ | File:Paginate1.jpg|Pagination | ||
+ | </gallery> | ||
+ | |||
+ | To use pagination you have to wrap a '''paginate''' tag around the '''for''' loop which iterates over your collection. The '''paginate''' tag will figure out all the calculations by itself and make sure that further calls to the collection will return with the correct items in the correct order. | ||
+ | |||
+ | Specify the number if items in each pagination after the '''by''' keyword. In the following example, the products are shown in groups of 6. The number of items in each pagination group cannot be more than 50. | ||
<pre> | <pre> | ||
− | {% paginate collection.products by 5 %} | + | {% paginate collection.products by 6 %} |
+ | {% for product in collection.products %} | ||
+ | {{ product.title }} | ||
+ | {% endfor %} | ||
+ | {% endpaginate %} | ||
+ | </pre> | ||
+ | |||
+ | By default, the '''paginate''' tag uses a window size of 3 for the page number display. If the pagination creates a large number of pages, then only the first and last pages will be shown for selection and the size of each of these groups will be determined by the window size. | ||
+ | |||
+ | The default window size can be changed by including a '''window_size''' tag attribute on the '''paginate''' tag. | ||
+ | |||
+ | <pre> | ||
+ | {% paginate collection.products by 6 window_size: 5 %} | ||
{% for product in collection.products %} | {% for product in collection.products %} | ||
{{ product.title }} | {{ product.title }} | ||
{% endfor %} | {% endfor %} | ||
− | + | {% endpaginate %} | |
</pre> | </pre> | ||
=== The Paginate Object === | === The Paginate Object === | ||
− | Within the paginate block you have access to the paginate object which | + | Within the '''paginate''' block you have access to the paginate object which contains the following information: |
− | + | * paginate.page_size - The number of items displayed on each page. | |
− | + | * paginate.current_page - The page currently being displayed. | |
− | + | * paginate.current_offset - The number of items skipped so far. | |
− | + | * paginate.pages - Total number of pages. | |
− | + | * paginate.items - Total number of items in this collection. | |
− | + | * paginate.previous - The previous page, if it exists. | |
− | + | ** paginate.previous.title - Title of the previous link. | |
− | + | ** paginate.previous.url - URL of the previous link. | |
− | + | * paginate.next - The next page, if it exists. | |
− | + | ** paginate.next.title - Title of the next link. | |
− | + | ** paginate.next.url - URL of the next link. | |
− | + | * paginate.parts - An array of all the parts which make up the navigation for this pagination. Each element will have these three elements: | |
− | + | ** part.is_link - Is this part a link? | |
− | + | ** part.title - Link Title. | |
− | + | ** part.url - Link URL. | |
== Displaying the pagination navigation == | == Displaying the pagination navigation == | ||
Line 45: | Line 63: | ||
{% for part in paginate.parts %} | {% for part in paginate.parts %} | ||
− | |||
{% if part.is_link %} | {% if part.is_link %} | ||
{{ part.title | link_to: part.url }} | {{ part.title | link_to: part.url }} | ||
Line 51: | Line 68: | ||
{{ part.title }} | {{ part.title }} | ||
{% endif %} | {% endif %} | ||
− | |||
{% endfor %} | {% endfor %} | ||
Line 60: | Line 76: | ||
</pre> | </pre> | ||
− | === The easy way | + | === The easy way === |
− | The paginate tag will add a new paginate variable to your view from which all | + | The '''paginate''' tag will add a new paginate variable to your view from which all important parameters for pagination can be extracted. If you just want to get a good standard pagination going you can take this paginate variable and pipe it into the filter '''default_pagination''' which will leave you with an attractive looking and fully functional pagination. |
<pre> | <pre> | ||
Line 70: | Line 86: | ||
{% endfor %} | {% endfor %} | ||
− | <div id="pagination"> | + | <div id="pagination">{{ paginate | default_pagination }}</div> |
− | |||
− | |||
{% endpaginate %} | {% endpaginate %} | ||
</pre> | </pre> | ||
+ | |||
+ | == Further Reference == | ||
+ | |||
+ | * [[Liquid Basics]] | ||
+ | * [[Liquid Tag Reference]] | ||
+ | * [[Liquid Variable Reference ]] | ||
+ | * [[Liquid Filter Reference]] |
Latest revision as of 14:34, 17 September 2015
The paginate tag is responsible for pagination within a Spiffy Stores template. It's currently applicable to collections, products and blog articles. By default the number of items that can be shown is 50, so if you want to show more, then you'll need to use the paginate tag.
The built-in themes automatically use paginate for collections and blog pages.
Contents
Usage
To use pagination you have to wrap a paginate tag around the for loop which iterates over your collection. The paginate tag will figure out all the calculations by itself and make sure that further calls to the collection will return with the correct items in the correct order.
Specify the number if items in each pagination after the by keyword. In the following example, the products are shown in groups of 6. The number of items in each pagination group cannot be more than 50.
{% paginate collection.products by 6 %} {% for product in collection.products %} {{ product.title }} {% endfor %} {% endpaginate %}
By default, the paginate tag uses a window size of 3 for the page number display. If the pagination creates a large number of pages, then only the first and last pages will be shown for selection and the size of each of these groups will be determined by the window size.
The default window size can be changed by including a window_size tag attribute on the paginate tag.
{% paginate collection.products by 6 window_size: 5 %} {% for product in collection.products %} {{ product.title }} {% endfor %} {% endpaginate %}
The Paginate Object
Within the paginate block you have access to the paginate object which contains the following information:
- paginate.page_size - The number of items displayed on each page.
- paginate.current_page - The page currently being displayed.
- paginate.current_offset - The number of items skipped so far.
- paginate.pages - Total number of pages.
- paginate.items - Total number of items in this collection.
- paginate.previous - The previous page, if it exists.
- paginate.previous.title - Title of the previous link.
- paginate.previous.url - URL of the previous link.
- paginate.next - The next page, if it exists.
- paginate.next.title - Title of the next link.
- paginate.next.url - URL of the next link.
- paginate.parts - An array of all the parts which make up the navigation for this pagination. Each element will have these three elements:
- part.is_link - Is this part a link?
- part.title - Link Title.
- part.url - Link URL.
Manually using pagination
<div id="pagination"> {% if paginate.previous %} {{ paginate.previous.title | link_to: paginate.previous.url }} {% endif %} {% for part in paginate.parts %} {% if part.is_link %} {{ part.title | link_to: part.url }} {% else %} {{ part.title }} {% endif %} {% endfor %} {% if paginate.next %} {{ paginate.next.title | link_to: paginate.next.url }} {% endif %} </div>
The easy way
The paginate tag will add a new paginate variable to your view from which all important parameters for pagination can be extracted. If you just want to get a good standard pagination going you can take this paginate variable and pipe it into the filter default_pagination which will leave you with an attractive looking and fully functional pagination.
{% paginate collection.products by 5 %} {% for product in collection.products %} {{ product.title }} {% endfor %} <div id="pagination">{{ paginate | default_pagination }}</div> {% endpaginate %}