Add docs of pagination context with context modifiers (#148)

Author: thibaudcolas

docs/recipes/forms-and-fields.md

@@ -1,5 +1,7 @@
 # Forms and fields
 
+We can define context for forms and fields in Python, with [context modifiers](../guides/defining-template-context.md#modifying-template-contexts-with-python).
+
 Basic Django form definition:
 
 ```python

docs/recipes/pagination.md

@@ -0,0 +1,58 @@
+# Pagination
+
+The Django paginator API is impossible to fully recreate in YAML. Instead, we can define context in Python, with [context modifiers](../guides/defining-template-context.md#modifying-template-contexts-with-python). Take a template like:
+
+```jinja2
+{% with count=search_results.paginator.count %}
+    {{ count }} result{{ count|pluralize }} found.
+{% endwith %}
+
+{% for result in search_results %}
+    <h4>{{ result.title }}</h4>
+{% endfor %}
+
+{% if search_results.paginator.num_pages > 1 %}
+    <nav aria-label="Pagination">
+        <ul>
+            {% if search_results.has_previous %}
+                <li><a href="?page={{ search_results.previous_page_number }}{% if search_query %}&amp;query={{ search_query|urlencode }}{% endif %}">previous</a></li>
+            {% endif %}
+
+            <li>{{ search_results.number }}/{{ search_results.paginator.num_pages }}</li>
+
+            {% if search_results.has_next %}
+                <li><a href="?page={{ search_results.next_page_number }}{% if search_query %}&amp;query={{ search_query|urlencode }}{% endif %}">next</a></li>
+            {% endif %}
+        </ul>
+    </nav>
+{% endif %}
+```
+
+We can create the needed context by using Django’s [`Paginator` API](https://docs.djangoproject.com/en/3.2/topics/pagination/).
+
+```python
+from django.core.paginator import Paginator
+
+from pattern_library import register_context_modifier
+
+
+@register_context_modifier(template='patterns/pages/search/search.html')
+def replicate_pagination(context, request):
+    object_list = context.pop('search_results', None)
+    if object_list is None:
+        return
+
+    original_length = len(object_list)
+
+    # add dummy items to force pagination
+    for i in range(50):
+        object_list.append(None)
+
+    paginator = Paginator(object_list, original_length)
+    context.update(
+        paginator=paginator,
+        search_results=paginator.page(10),
+        is_paginated=True,
+        object_list=object_list
+    )
+```

tests/pattern_contexts.py

@@ -1,3 +1,5 @@
+from django.core.paginator import Paginator
+
 from pattern_library import register_context_modifier
 
 from .forms import ExampleForm
@@ -12,3 +14,30 @@ def add_common_forms(context, request):
 def add_field(context, request):
     form = ExampleForm()
     context['field'] = form['single_line_text']
+
+
+@register_context_modifier(template='patterns/pages/search/search.html')
+def replicate_pagination(context, request):
+    """
+    Replace lists of items using the 'page_obj.object_list' key
+    with a real Paginator page, and add a few other pagination-related
+    things to the context (like Django's `ListView` does).
+    """
+    object_list = context.pop('search_results', None)
+    if object_list is None:
+        return
+
+    original_length = len(object_list)
+
+    # add dummy items to force pagination
+    for i in range(50):
+        object_list.append(None)
+
+    # paginate and add ListView-like values
+    paginator = Paginator(object_list, original_length)
+    context.update(
+        paginator=paginator,
+        search_results=paginator.page(10),
+        is_paginated=True,
+        object_list=object_list
+    )

tests/templates/patterns/pages/search/search.html

@@ -0,0 +1,34 @@
+{% extends "patterns/base.html" %}
+
+{% block content %}
+    <h1>{% if search_query %}Search results for “{{ search_query }}”{% else %}Search{% endif %}</h1>
+
+    {% if search_results %}
+        {% with count=search_results.paginator.count %}
+            {{ count }} result{{ count|pluralize }} found.
+        {% endwith %}
+
+        {% for result in search_results %}
+            <h4>{{ result.title }}</h4>
+        {% endfor %}
+
+        {% if search_results.paginator.num_pages > 1 %}
+            <nav aria-label="Pagination">
+                <ul>
+                    {% if search_results.has_previous %}
+                        <li><a href="#page={{ search_results.previous_page_number }}{% if search_query %}&amp;query={{ search_query|urlencode }}{% endif %}">previous</a></li>
+                    {% endif %}
+
+                    <li>{{ search_results.number }}/{{ search_results.paginator.num_pages }}</li>
+
+                    {% if search_results.has_next %}
+                        <li><a href="#page={{ search_results.next_page_number }}{% if search_query %}&amp;query={{ search_query|urlencode }}{% endif %}">next</a></li>
+                    {% endif %}
+                </ul>
+            </nav>
+        {% endif %}
+
+    {% elif search_query %}
+        No results found.
+    {% endif %}
+{% endblock %}

tests/templates/patterns/pages/search/search.yaml

@@ -0,0 +1,5 @@
+context:
+  search_query: test query
+  search_results:
+    - title: First result
+    - title: Second result