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 <jon+wsl.ubuntu@tjs.co.uk>
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,