Add demo of using context modifiers to render forms and form fields (#146)

Author: thibaudcolas

docs/guides/defining-template-context.md

@@ -58,7 +58,6 @@ context:
 
 You can define a list or a dict or anything that [`PyYAML`](http://pyyaml.org/wiki/PyYAMLDocumentation) allows you to create in YAML format without creating a custom objects.
 
-
 ## Modifying template contexts with Python
 
 While most objects can be faked with YAML, Django has a few common constructs that are difficult to replicate. For example: `Form` and `Paginator` instances. To help with this, django-pattern-library allows you to register any number of 'context modifiers'. Context modifiers are simply Python functions that accept the `context` dictionary generated from the YAML file, and can make additions or updates to it as necessary. For convenience, they also receive the current `HttpRequest` as `request`.
@@ -135,7 +134,7 @@ def replicate_pagination(context, request):
 
 ### Registering a context modifier for a specific template
 
-By default, context modifiers are applied to all pattern library templates. If you only wish for a context modifier to be applied to a specific pattern, you can use the ``template`` parameter to indicate this. For example:
+By default, context modifiers are applied to all pattern library templates. If you only wish for a context modifier to be applied to a specific pattern, you can use the `template` parameter to indicate this. For example:
 
 ```python
 
@@ -166,9 +165,9 @@ def add_invalid_subscribe_form(context, request):
 
 ### Controlling the order in which context modifiers are applied
 
-By default, context modifiers are applied in the order they were registered (which can be difficult to predict accross multiple apps), with generic context modifiers being applied first, followed by template-specific ones. If you need to control the order in which a series of context modifiers are applied, you can use the `order` parameter to do this.
+By default, context modifiers are applied in the order they were registered (which can be difficult to predict across multiple apps), with generic context modifiers being applied first, followed by template-specific ones. If you need to control the order in which a series of context modifiers are applied, you can use the `order` parameter to do this.
 
-In the following example, a generic context modifier is registered with an `order` value of `1`, while others recieve the default value of `0`. Because `1` is higher than `0`, the generic context modifier will be applied **after** the others.
+In the following example, a generic context modifier is registered with an `order` value of `1`, while others receive the default value of `0`. Because `1` is higher than `0`, the generic context modifier will be applied **after** the others.
 
 ```python
 

docs/recipes/forms-and-fields.md

@@ -0,0 +1,63 @@
+# Forms and fields
+
+Basic Django form definition:
+
+```python
+from django import forms
+
+
+class ExampleForm(forms.Form):
+    single_line_text = forms.CharField(
+        max_length=255, help_text="This is some help text"
+    )
+    choices = (("one", "One"), ("two", "Two"), ("three", "Three"), ("four", "Four"))
+    select = forms.ChoiceField(choices=choices)
+```
+
+Rendered as:
+
+```jinja2
+{% extends "patterns/base.html" %}
+
+{% block content %}
+<form method="post" class="form">
+    {% csrf_token %}
+    <div class="form__container">
+        {% for hidden_field in form.hidden_fields %}
+            {{ hidden_field }}
+        {% endfor %}
+
+        {% for field in form.visible_fields %}
+            {% include "patterns/molecules/field/field.html" with field=field %}
+        {% endfor %}
+
+        <button class="form__submit button" type="submit">Submit</button>
+    </div>
+</form>
+{% endblock %}
+```
+
+Context overrides when rendering the whole form:
+
+```python
+from pattern_library import register_context_modifier
+from .forms import ExampleForm
+
+
+@register_context_modifier
+def add_common_forms(context, request):
+    context['form'] = ExampleForm()
+```
+
+Context overrides for `field.html`:
+
+```python
+from pattern_library import register_context_modifier
+from .forms import ExampleForm
+
+
+@register_context_modifier(template='patterns/molecules/field/field.html')
+def add_field(context, request):
+    form = ExampleForm()
+    context['field'] = form['single_line_text']
+```

docs/reference/api.md

@@ -27,7 +27,7 @@ context:
 tags:
   error_tag:
     include:
-      template_name: 'non-patterns/include.html'
+      template_name: "non-patterns/include.html"
 ```
 
 ## Templates
@@ -121,20 +121,36 @@ PATTERN_LIBRARY = {
 
 ### `override_tag`
 
-This function tells the pattern library which Django tags to override, and optionally supports providing a default value. See [../guides/overriding-template-tags.md] for more information.
+This function tells the pattern library which Django tags to override, and optionally supports providing a default value. See [Overriding template tags](../guides/overriding-template-tags.md) for more information.
 
 ```python
 from pattern_library.monkey_utils import override_tag
 
 override_tag(register, 'a_tag_name', default_html="https://example.com/")
 ```
 
+## `register_context_modifier`
+
+This decorator makes it possible to override or create additional context data with Django / Python code, rather than being limited to YAML. It has to be called from within a `pattern_contexts` module, which can be at the root of any Django app. See [Modifying template contexts with Python](../guides/defining-template-context.md#modifying-template-contexts-with-python) for more information.
+
+```python
+# myproject/core/pattern_contexts.py
+
+from pattern_library import register_context_modifier
+from myproject.core.forms import SearchForm, SignupForm
+
+@register_context_modifier
+def add_common_forms(context, request):
+    if 'search_form' not in context:
+        context["search_form"] = SearchForm()
+```
+
 ## Commands
 
 ### `render_patterns`
 
 Renders all django-pattern-library patterns to HTML files, in a directory
-structure. This can be useful for [automated tests](../guides/automated-tests.md)
+structure. This can be useful for [automated tests](../guides/automated-tests.md).
 
 Usage:
 

mkdocs.yml

@@ -43,6 +43,7 @@ nav:
   - 'Recipes':
     - 'Inclusion tags': 'recipes/inclusion-tags.md'
     - 'Looping for tags': 'recipes/looping-for-tags.md'
+    - 'Forms and fields': 'recipes/forms-and-fields.md'
     - 'Image include': 'recipes/image-include.md'
     - 'Image lazyload': 'recipes/image-lazyload.md'
   - 'Reference':

tests/forms.py

@@ -0,0 +1,9 @@
+from django import forms
+
+
+class ExampleForm(forms.Form):
+    single_line_text = forms.CharField(
+        max_length=255, help_text="This is some help text"
+    )
+    choices = (("one", "One"), ("two", "Two"), ("three", "Three"), ("four", "Four"))
+    select = forms.ChoiceField(choices=choices)

tests/pattern_contexts.py

@@ -0,0 +1,14 @@
+from pattern_library import register_context_modifier
+
+from .forms import ExampleForm
+
+
+@register_context_modifier
+def add_common_forms(context, request):
+    context['form'] = ExampleForm()
+
+
+@register_context_modifier(template='patterns/molecules/field/field.html')
+def add_field(context, request):
+    form = ExampleForm()
+    context['field'] = form['single_line_text']

tests/static/main.css

@@ -1,3 +1,13 @@
+html {
+    box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+    box-sizing: inherit;
+}
+
 .icon {
     fill: currentColor;
 }
@@ -61,3 +71,51 @@
     max-width: 768px;
     padding-bottom: 5px;
 }
+
+.field {
+    margin-bottom: 20px;
+}
+
+.field--errors {
+    padding: 20px;
+    margin-bottom: 20px;
+    border: 1px dotted #f00;
+}
+
+.field__required {
+    color: #f00;
+}
+.field__label,
+.field__label--multiple {
+    display: block;
+    margin-bottom: 5px;
+    font-weight: 700;
+}
+.field__errors {
+    margin-bottom: 10px;
+    font-weight: 700;
+    color: #f00;
+}
+.field__help {
+    margin-top: 5px;
+}
+.field input:not([type="checkbox"]):not([type="radio"]):not([type="submit"]),
+.field textarea,
+.field select {
+    width: 100%;
+    padding: 10px;
+    border: 1px solid #141414;
+}
+
+.field select:not([multiple]) {
+    background-color: #fff;
+    padding: 0.5em 3.5em 0.5em 1em;
+    appearance: none;
+    background-image: linear-gradient(45deg, transparent 50%, #444 50%),
+        linear-gradient(135deg, #444 50%, transparent 50%),
+        linear-gradient(to right, rgba(20, 20, 20, 0.2), rgba(20, 20, 20, 0.2));
+    background-position: calc(100% - 20px) calc(1em + 2px),
+        calc(100% - 15px) calc(1em + 2px), calc(100% - 2.5em) 0.5em;
+    background-size: 5px 5px, 5px 5px, 1px 1.5em;
+    background-repeat: no-repeat;
+}

tests/templates/patterns/molecules/field/field.html

@@ -0,0 +1,51 @@
+{% load test_tags %}
+{% with widget_type=field|widget_type %}
+<div class="field {% if widget_type %}field--{{ widget_type }}{% endif %} {% if field.errors %}field--errors{% endif %}">
+
+    {% if field.errors %}
+        <div class="field__errors">
+            {{ field.errors }}
+        </div>
+    {% endif %}
+
+    {% if widget_type == 'checkbox-select-multiple' or widget_type == 'radio-select' %}
+        <fieldset class="field__fieldset">
+            <legend class="field__label field__label--multiple">
+                {{ field.label }}
+                {% if field.field.required %}<span class="field__required" aria-hidden="true">*</span>{% endif %}
+            </legend>
+
+            <ul>
+                {% for boundwidget in field %}
+                    <li class="field__radio-checkbox">
+                        <input id="{{ boundwidget.id_for_label }}" type="{{ boundwidget.data.type }}" name="{{ boundwidget.data.name }}" value="{{ boundwidget.data.value }}"{% if boundwidget.data.selected %} checked{% endif %}>
+                        <label for="{{ boundwidget.id_for_label }}" class="field__label">{{ boundwidget.data.label }}</label>
+                    </li>
+                {% endfor %}
+            </ul>
+        </fieldset>
+
+    {% elif widget_type == 'checkbox-input' %}
+
+        <div class="field__radio-checkbox">
+            {{ field }}
+            <label for="{{ field.id_for_label }}" class="field__label">
+                {{ field.label }}
+                {% if field.field.required %}<span class="field__required" aria-hidden="true">*</span>{% endif %}
+            </label>
+        </div>
+
+    {% else %}
+
+        <label for="{{ field.id_for_label }}" class="field__label">
+            {{ field.label }}
+            {% if field.field.required %}<span class="field__required" aria-hidden="true">*</span>{% endif %}
+        </label>
+        {{ field }}
+
+    {% endif %}
+
+    {% if field.help_text %}<div class="field__help">{{ field.help_text }}</div>{% endif %}
+
+</div>
+{% endwith %}

tests/templates/patterns/pages/forms/example_form.html

@@ -0,0 +1,32 @@
+{% extends "patterns/base.html" %}
+
+{% block content %}
+<form method="post" class="form">
+    {% csrf_token %}
+    <div class="form__container">
+        {% if form.errors %}
+            <div class="form__errors">
+                There were some errors with your form. Please amend the fields highlighted below.
+
+                {% if form.non_field_errors %}
+                    <ul>
+                    {% for error in form.non_field_errors %}
+                        <li>{{ error }}</li>
+                    {% endfor %}
+                    </ul>
+                {% endif %}
+            </div>
+        {% endif %}
+
+        {% for hidden_field in form.hidden_fields %}
+            {{ hidden_field }}
+        {% endfor %}
+
+        {% for field in form.visible_fields %}
+            {% include "patterns/molecules/field/field.html" with field=field %}
+        {% endfor %}
+
+        <button class="form__submit button" type="submit">Submit</button>
+    </div>
+</form>
+{% endblock %}

tests/templatetags/test_tags.py

@@ -1,4 +1,5 @@
 from django import template
+from django.utils.text import camel_case_to_spaces, slugify
 
 from pattern_library.monkey_utils import override_tag
 
@@ -26,6 +27,12 @@ def default_html_tag_falsey(arg=None):
     raise Exception("default_tag raised an exception")
 
 
+# Get widget type of a field
+@register.filter(name="widget_type")
+def widget_type(bound_field):
+    return slugify(camel_case_to_spaces(bound_field.field.widget.__class__.__name__))
+
+
 override_tag(register, 'error_tag')
 override_tag(register, 'default_html_tag', default_html="https://potato.com")
 override_tag(register, 'default_html_tag_falsey', default_html=None)