In most cases lists are too long to be displayed on a single page. In such cases lists are splited into many small pages. We call this pagination.

Pager - is a bunch of links that allow visitors to jump to other pages of displayed list. Pager can come in different forms: it can be just two links «next page» and «previous page», a complete number of available pages or any other variant.

MACRO has number of tools to simplify pagination.

Pagination has two tasks:

• display a pager.
• limit paginated list to display only a certain number of items that is corresponding to selected (or current) page of a pager. For database queries this means to specify limit and offset.

To display a pager you can user macro PagerTags.

There is an example:

{{pager id="my_pager" items="10" total_items="$#total_items_in_list"}}
 
Show items: from <b>{$begin_item_number}</b> to <b>{$end_item_number}</b>
 
{{pager:first}}<a href="{$href}">First page </a>{{/pager:first}}
 
{{pager:list}}
 
{{pager:current}}<b><a href="{$href}">{$number}</a></b>{{/pager:current}}
{{pager:number}}<a href="{$href}">{$number}</a>{{/limb:pager:number}}
 
{{/pager:list}}
 
{{pager:last}}<a href="{$href}">Last page</a>{{/pager:last}}
 
Total items: <b>{$total_items}</b>
{{/pager}}

The main pager tag is tag {{pager}} that limits pager. items attribute of pager tag sets maximum number of items that can be displayed on a single page. total_items attribute allows to set total number of items in paginated list. pager takes currently displayed page number from predefined PHP $_GET variable automatically.

Tag {{pager:list}} renders links to pages including current page.

Other tags that we used in the example above are:

• Tags {{pager:prev}}, {{pager:first}}, {{pager:next}}, {{pager:last}} - output links to previous, first, next and last pages of pager.
• Tag {{pager:current}} - outputs link to or just a number of current page,
• Tag {{pager:number}} - outputs link to some particular pager page.

Each tag creates a local available variable $href that contains an URL of corresponding page. $href value has the following form: CURRENT_URI[?|&]pager_id_pager=$page_number. Tag number and current also generate and fill $number variable with corresponding page number.

There also several variables available inside pager tag:

• {$total_items} - total number of items in paginated list,
• {$total_pages} - total number of pages,
• {$begin_item_number} - number of item that is starting current page,
• {$end_item_number} - number of item that is finishing current page.

It's a common practice to create one or more pagers and include them near lists with tag {{include}}.

pager tag actually creates a helper object of lmbMacroPagerHelper class at runtime that performs all pagination logic. You can always access this object right in macro template by {$this→pager_PAGER_ID} wDhere PAGER_I is value of id attribute of pager tag.

Here is list of method you may need:

• setTotalItems($number) - sets a total number of items in a paginated list
• setItemsPerPage($number) - sets a maximum number of items that can be displayed on a single page
• getItemsPerPage() - returns a maximum number of items that can be displayed on a single page. Can be used as a limit for a paginated list.
• prepare() - should be called after setTotalItems() or setItemsPerPage() to recalculate a pager.
• getCurrentPageOffset() - returns a value that can be used as an offset for a paginated list (not available in 2007.4, for 2007.4 consider using getCurrentPageBeginItem())
• getCurrentPageBeginItem() - returns a number of first item to be displayed on the current page (you need to extract 1 from this value for positive values since this value is not zero based).

There is also tag {{paginate}} that can greatly simplify limitation of paginated list. paginate tag has only one condition: paginated list should be an object that supports lmbCollectionInterface interface (see Limb3 CORE package).

Let's consider the following macro template:

{{paginate iterator='$#modules' pager='my_pager'/}}
 
{{pager id="my_pager" items="5"}}
    {{pager:first}}<a href='{$href}'>First</a>{{/pager:first}} {{pager:prev}}<a href='{$href}'>Prev</a>{{/pager:prev}}
    {{pager:list}}
     [...]
    {{/pager:list}}
    {{pager:next}}<a href='{$href}'>Next</a>{{/pager:next}} {{pager:last}}<a href='{$href}'>Last</a>{{/pager:last}}
{{/pager}}
 
{{list using='$#modules'>
  <TABLE width="100%" BORDER="1" ALIGN="CENTER">
    {{list:item}}
      <TR>
        <TD>{$item.name}</TD>
        <TD>{$item.description|default:"&nbsp;"}</TD>
      </TR>
    {{/list:item}}
  </TABLE>
{{/list}}

Note iterator attribute value of paginate tag and using attribute of list tag. They point at the same variable. pager attribute of paginate tag has the same value as id attribute of pager tag. You should also make sure that iterator is filled (or simply created) before paginate tag is executed. That means you need to perform pull-data operations (if so) BEFORE paginate tag.

P.S. You can you use macro with other framework and it's easy to implement an analog of paginate tag.

If you have really long list with too many pages in pager to display there are two available workarounds:

• Use elipses (or gaps) - in this case only certain number of pages in pager will be diplayed: some at the beginning, some in the middle and some at the end of pager. Pager with elipses looks approximately like this: 1-2-3…7-8-9-10-11…17-18-19
• Use sections (or blocks of pages) - is this case pager will display only a small portion of pages (current section) and other blocks (section) will be collapsed. Pager with sections looks approximately like this: [1-5]6-7-8-9-10[11-15][16-19].

See only tag{{pager}} description.

Tag {{pager:elipses}} is used to render elipses. You may also need a couple of extra attributes for pager tags: * pages_in_middle * pages_in_sides.

For example:

{{pager id="pager" items="5" pages_in_middle="5" pages_in_sides="3"}}
 
{{pager:list}}
{{pager:current}}<b><a href="{$href}">{$number}</a></b>{{/pager:current}}
{{pager:number}}<a href="{$href}">{$number}</a>{{/pager:number}}
{{pager:ELIPSES}}...{{/pager:ELIPSES}}
{{pager:separator}}-{{/pager:separator}}
{{/pager:list}}
 
{{/pager}}

Will produce:

 1-2-3...6-7-8-9-10...15-16-17

Tag {{pager:section}} is used to render blocks of pages. Also pages_per_section attribute of pager tag is used.

Example:

{{pager id="pager" items="5" pages_per_section="5"}}
 
{{pager:list}}
{{pager:section}}<a href="{$href}">[{$section_begin_number}..{$section_end_number}]</a>{{/pager:section}}
{{pager:current}}<b><a href="{$href}">{$number}</a></b>{{/pager:current}}
{{pager:number}}<a href="{$href}">{$number}</a>{{/pager:number}}
{{pager:separator}}-{{/pager:separator}}
{{/pager:list}}
 
{{/pager}}

Tag section also creates $section_begin_number and $section_end_number variables.

The example above will produce the following pager:

[1..5][6..10]11-12-13-14-15[16..17]

• See more examples at tag {{pager}} tag.