Add rel links template and Twig function (#782)

* Add rel links template and Twig function * Un-remove sortable templates from README And also put the "rel links" notes with the "pagination" notes, as they are connected. * Add usage notes to readme --------- Co-authored-by: Jon Green <[email protected]>
KnpLabs · Mar 18, 2024 · 708764c · 708764c
1 parent f59d000
commit 708764c
Show file tree

Hide file tree

Showing 13 changed files with 72 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -86,6 +86,7 @@ knp_paginator:
         filter_value_name: filterValue  # filter value query parameter name
     template:
         pagination: '@KnpPaginator/Pagination/sliding.html.twig'     # sliding pagination controls template
+        rel_links: '@KnpPaginator/Pagination/rel_links.html.twig'     # <link rel=...> tags template
         sortable: '@KnpPaginator/Pagination/sortable_link.html.twig' # sort link template
         filtration: '@KnpPaginator/Pagination/filtration.html.twig'  # filters template
 ```
@@ -111,6 +112,7 @@ return static function (ContainerConfigurator $configurator): void
         ],
         'template' => [
             'pagination' => '@KnpPaginator/Pagination/sliding.html.twig',     // sliding pagination controls template
+            'pagination' => '@KnpPaginator/Pagination/rel_links.html.twig',     // <link rel=...> tags template
             'sortable' => '@KnpPaginator/Pagination/sortable_link.html.twig', // sort link template
             'filtration' => '@KnpPaginator/Pagination/filtration.html.twig'   // filters template
         ]
@@ -134,6 +136,11 @@ That could be used out of the box in `knp_paginator.template.pagination` key:
 * `@KnpPaginator/Pagination/tailwindcss_pagination.html.twig`
 * `@KnpPaginator/Pagination/uikit_v3_pagination.html.twig`
 
+#### Sample rel link tag template
+That could be used out of the box in `knp_paginator.template.rel_links` key:
+
+* `@KnpPaginator/Pagination/rel_links.html.twig` (by default)
+
 #### Additional sortable templates
 That could be used out of the box in `knp_paginator.template.sortable` key:
 
@@ -193,6 +200,15 @@ public function listAction(EntityManagerInterface $em, PaginatorInterface $pagin
 
 ### View
 
+#### In `<head>`:
+
+```twig
+{# rel links for pagination #}
+{{ knp_pagination_rel_links(pagination) }}
+```
+
+#### In `<body>`:
+
 ```twig
 {# total items count #}
 <div class="count">
@@ -322,6 +338,8 @@ label_next: Next
 label_previous: Previous
 ```
 
+- Note that `<rel>` links are only meaningful when using pagination, they are not relevant to sorting or filtering.
+
 ## Maintainers
 
 Please read [this post](https://knplabs.com/en/blog/news-for-our-foss-projects-maintenance) first.

diff --git a/config/paginator.xml b/config/paginator.xml
@@ -34,6 +34,7 @@
         <service id="knp_paginator.subscriber.sliding_pagination" class="Knp\Bundle\PaginatorBundle\Subscriber\SlidingPaginationSubscriber">
             <argument type="collection">
                 <argument key="defaultPaginationTemplate">%knp_paginator.template.pagination%</argument>
+                <argument key="defaultRelLinksTemplate">%knp_paginator.template.rel_links%</argument>
                 <argument key="defaultSortableTemplate">%knp_paginator.template.sortable%</argument>
                 <argument key="defaultFiltrationTemplate">%knp_paginator.template.filtration%</argument>
                 <argument key="defaultPageRange">%knp_paginator.page_range%</argument>

diff --git a/docs/paginator_configuration.md b/docs/paginator_configuration.md
@@ -20,6 +20,7 @@ knp_paginator:
         default_limit: 10              # default number of items per page
     template:
         pagination: @KnpPaginator/Pagination/sliding.html.twig     # sliding pagination controls template
+        rel_links: @KnpPaginator/Pagination/rel_links.html.twig     # <link rel=...> tags template
         sortable: @KnpPaginator/Pagination/sortable_link.html.twig # sort link template
 ```
 

diff --git a/docs/templates.md b/docs/templates.md
@@ -29,6 +29,7 @@ Same for sorting link template:
 $paginator = $this->get('knp_paginator');
 $pagination = $paginator->paginate($target, $page);
 $pagination->setTemplate('my_pagination.html.twig');
+$pagination->setRelLinksTemplate('my_rel_links.html.twig');
 $pagination->setSortableTemplate('my_sortable.html.twig');
 ```
 

diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
@@ -35,6 +35,9 @@ public function getConfigTreeBuilder(): TreeBuilder
                         ->scalarNode('pagination')
                         ->defaultValue('@KnpPaginator/Pagination/sliding.html.twig')
                         ->end()
+                        ->scalarNode('rel_links')
+                        ->defaultValue('@KnpPaginator/Pagination/rel_links.html.twig')
+                        ->end()
                         ->scalarNode('filtration')
                         ->defaultValue('@KnpPaginator/Pagination/filtration.html.twig')
                         ->end()

diff --git a/src/DependencyInjection/KnpPaginatorExtension.php b/src/DependencyInjection/KnpPaginatorExtension.php
@@ -36,6 +36,7 @@ public function load(array $configs, ContainerBuilder $container): void
         $config = $processor->processConfiguration($configuration, $configs);
 
         $container->setParameter('knp_paginator.template.pagination', $config['template']['pagination']);
+        $container->setParameter('knp_paginator.template.rel_links', $config['template']['rel_links']);
         $container->setParameter('knp_paginator.template.filtration', $config['template']['filtration']);
         $container->setParameter('knp_paginator.template.sortable', $config['template']['sortable']);
         $container->setParameter('knp_paginator.page_range', $config['page_range']);

diff --git a/src/Pagination/SlidingPagination.php b/src/Pagination/SlidingPagination.php
@@ -25,6 +25,8 @@ final class SlidingPagination extends AbstractPagination implements SlidingPagin
 
     private ?string $template = null;
 
+    private ?string $relLinksTemplate = null;
+
     private ?string $sortableTemplate = null;
 
     private ?string $filtrationTemplate = null;
@@ -87,6 +89,16 @@ public function getTemplate(): ?string
         return $this->template;
     }
 
+    public function setRelLinksTemplate(string $relLinksTemplate): void
+    {
+        $this->relLinksTemplate = $relLinksTemplate;
+    }
+
+    public function getRelLinksTemplate(): ?string
+    {
+        return $this->relLinksTemplate;
+    }
+
     public function setPageRange(int $range): void
     {
         $this->pageRange = \abs($range);

diff --git a/src/Subscriber/SlidingPaginationSubscriber.php b/src/Subscriber/SlidingPaginationSubscriber.php
@@ -74,6 +74,7 @@ public function pagination(PaginationEvent $event): void
 
         $pagination->setUsedRoute($this->route);
         $pagination->setTemplate($this->options['defaultPaginationTemplate']);
+        $pagination->setRelLinksTemplate($this->options['defaultRelLinksTemplate']);
         $pagination->setSortableTemplate($this->options['defaultSortableTemplate']);
         $pagination->setFiltrationTemplate($this->options['defaultFiltrationTemplate']);
         $pagination->setPageRange($this->options['defaultPageRange']);

diff --git a/src/Twig/Extension/PaginationExtension.php b/src/Twig/Extension/PaginationExtension.php
@@ -13,6 +13,7 @@ public function getFunctions(): array
 
         return [
             new TwigFunction('knp_pagination_render', [PaginationRuntime::class, 'render'], $options),
+            new TwigFunction('knp_pagination_rel_links', [PaginationRuntime::class, 'rel_links'], $options),
             new TwigFunction('knp_pagination_sortable', [PaginationRuntime::class, 'sortable'], $options),
             new TwigFunction('knp_pagination_filter', [PaginationRuntime::class, 'filter'], $options),
         ];

diff --git a/src/Twig/Extension/PaginationRuntime.php b/src/Twig/Extension/PaginationRuntime.php
@@ -36,6 +36,28 @@ public function render(
         );
     }
 
+    /**
+     * Renders the <link> tags.
+     *
+     * @param \Knp\Bundle\PaginatorBundle\Pagination\SlidingPagination<mixed, mixed> $pagination
+     * @param array<string, mixed>                                                   $queryParams
+     * @param array<string, mixed>                                                   $viewParams
+     */
+    public function rel_links(
+        Environment $env,
+        SlidingPaginationInterface $pagination,
+        ?string $template = null,
+        ?array $queryParams = [],
+        ?array $viewParams = [],
+    ): string {
+        dump($template ?: $pagination->getRelLinksTemplate());
+        dump($this->processor->render($pagination, $queryParams ?? [], $viewParams ?? []));
+        return $env->render(
+            $template ?: $pagination->getRelLinksTemplate(),
+            $this->processor->render($pagination, $queryParams ?? [], $viewParams ?? [])
+        );
+    }
+
     /**
      * Create a sort url for the field named $title and identified by $key which consists of
      * alias and field. $options holds all link parameters like "alt, class" and so on.

diff --git a/templates/Pagination/rel_links.html.twig b/templates/Pagination/rel_links.html.twig
@@ -0,0 +1,9 @@
+{% if pageCount > 1 %}
+    {% if previous is defined %}
+        <link rel="prev" href="{{ path(route, query|merge({(pageParameterName): previous})) }}" />
+    {% endif %}
+
+    {% if next is defined %}
+        <link rel="next" href="{{ path(route, query|merge({(pageParameterName): next})) }}" />
+    {% endif %}
+{% endif %}
diff --git a/tests/DependencyInjection/ConfigurationTest.php b/tests/DependencyInjection/ConfigurationTest.php
@@ -44,6 +44,7 @@ public function testDefaultConfig(): void
             ],
             'template' => [
                 'pagination' => '@KnpPaginator/Pagination/sliding.html.twig',
+                'rel_links' => '@KnpPaginator/Pagination/rel_links.html.twig',
                 'filtration' => '@KnpPaginator/Pagination/filtration.html.twig',
                 'sortable' => '@KnpPaginator/Pagination/sortable_link.html.twig',
             ],

diff --git a/tests/SlidingPaginationSubscriberTest.php b/tests/SlidingPaginationSubscriberTest.php
@@ -37,6 +37,7 @@ protected function setUp(): void
         $options = \array_merge($defaultOptions, $options);
         $subscriberOptions = [
             'defaultPaginationTemplate' => '@KnpPaginator/Pagination/foo.html.twig',
+            'defaultRelLinksTemplate' => '@KnpPaginator/Pagination/qux.html.twig',
             'defaultSortableTemplate' => '@KnpPaginator/Pagination/baz.html.twig',
             'defaultFiltrationTemplate' => '@KnpPaginator/Pagination/bar.html.twig',
             'defaultPageRange' => 5,