twig pagination function

[gigago]

Adds twig function paginate($collection, $limit, $ignore_url_params) to paginate arbitrary collections, e.g. list items. A working example can be seen at http://ami-web.nl/events

$collection - the collection $limit - max # of items per page $ignore_url_params - set to true if page parameters cause trouble (default false). In this case one may need to handle url parameters manually.

[Sogl]

nice :+1:

[Sogl]

@rhukster ping :wink:

[gigago]

Any action or comments on this?

[flaviocopes]

Can you provide an example of how you use it in your Twig? Thanks

[gigago]

Previous commit adds url param array, fixes broken default argument and removes unnecessary yaml property.

The argument _$ignore_urlparams has been replaced by the optional argument _$ignore_url_paramarray, which can be given an array of url parameters to ignore.

Summary

paginate( $collection, $limit [, $ignore_url_param_array] )

• $collection - Required. The collection to be paginated.
• $limit - Required. Max number of items per page.
• _$ignore_url_paramarray - Optional. Array of url parameter keys to ignore when creating page links.

Basic usage

{% set collection = << your favourite collection >> %}
{% set limit = << your favourite number >> %}
{% do paginate(collection, limit) %}

This creates a paginated collection with << limit >> items per page. As usual, any url parameters - except the page parameter, which is recreated - are passed on to the pagination bar's links.

Extended usage

{% set collection = page.find('/other/_events').children %}
{% set limit = 5 %}
{% set ignore_url_param_array = ['event'] %}
{% do paginate(collection, limit, ignore_url_param_array) %}

The above example is taken from this website. This code creates a paginated collection with 5 items per page. In this case, the url parameters 'page' and 'event' have a one-to-many relationship, each event occurring uniquely in just one page. Consequently, the url parameter 'event' should be filtered out so it does not show up in the pagination bar's links, preventing inconsistencies with different page parameters. Any other url parameters are passed through unaffected. The requested page contains logic to pick a sensible default event.

[gigago]

Sorry for having had trouble making up my mind here, resulting in some superfluous and wordy comments. With the recent functional change the code is both more flexible and easier to explain. I expect no need for further functional changes in this area.

[gigago]

OK - at this time I have both pagination scenarios tested, via twig and via onCollectionProcessed event. Both should work without errors now.

[gigago]

Twig pagination function

Creating the paginated collection

Basic usage

{% set collection = << some collection >> %}
{% set limit = << number of items per page >> %}
{% do paginate( collection, limit ) %}

This creates a paginated collection with << limit >> items per page. As usual, any url parameters - except the page parameter, which is recreated - are passed on to the pagination bar's links.

Extended usage

{% set collection = page.find( '/other/_events' ).children %}
{% set limit = 5 %}
{% set ignore_url_param_array = [ 'event' ] %}
{% do paginate( collection, limit, ignore_url_param_array ) %}

The above example is taken from this website. This code creates a paginated collection with 5 items per page (the event summary list) which is presented together with an active event. The active event appears in only one of the summary pages. Consequently, the url parameter 'event' should be filtered out so it does not show up in the pagination bar's links, preventing inconsistencies with different page parameters. Any non listed url parameters (except the page parameter) are passed through unaffected. The requested page contains logic to pick a sensible default event.

Rendering the paginated collection

The rest is in fact completely identical to the standard procedure.

{# create list of items #}
{% for item in collection %}
   ...
{% endfor %}

{# include the pagination bar #}
{% if config.plugins.pagination.enabled and collection.params.pagination %}
    {% include 'partials/pagination.html.twig' with {'base_url':page.url, 'pagination':collection.params.pagination} %}
{% endif %}

[Sogl]

@flaviocopes Any changes on this? I'm still waiting because it needed in my project.

[gigago]

As far as I'm concerned this is finished. Please let me know if there's any questions or actions I need to take to finalize this PR.

[rhukster]

Would you mind adding your Twig pagination help/guide to the README? After that is done, i'll merge this PR.

Thanks!

[gigago]

Done. Thank you!

[Sogl]

@gigago Something strange with your markdown: https://github.com/getgrav/grav-plugin-pagination/pull/22/commits/e0dabd3c4b8b7cd08cd6d642d83f0c4e90144672?short_path=04c6e90#diff-04c6e90faac2675aa89e2176d2eec7d8

Remove + sign first.

Sorry I have no rights to change your commit directly.

[Sogl]

@gigago Previous link show your changes, it's ok. That's how it looks finally: https://github.com/gigago/grav-plugin-pagination/blob/14dd65d9b5299e494e85ee5a205e255c5e016f06/README.md

[gigago]

Ok, thanks. Apparently empty lines are needed around the code block markup.

[Sogl]

You can also enable highlighting for your code adding ```twig.

Before:

{% set collection = page.find( '/other/_events' ).children %}
{% set limit = 5 %}

After:

{% set collection = page.find( '/other/_events' ).children %}
{% set limit = 5 %}

[gigago]

Cool, thanks a lot!

[rhukster]

Thanks for this handy improvement!

[gigago]

You're more than welcome! Thanks for an awesome platform!