A form templating app for Django
Project description
paper-forms
A form templating app for Django
Compatibility
python
>= 3.5django
>= 1.11
Installation
Install the latest release with pip:
pip install paper-forms
Add paper_forms
to your INSTALLED_APPS in settings.py
:
INSTALLED_APPS = (
# other apps
"paper_forms",
)
Features
- Jinja2 support.
- django-jinja support.
- Add or replace attributes to form fields using a template tag.
Usage
Let’s create our first Django paper form.
from django import forms
class ExampleForm(forms.Form):
name = forms.CharField()
age = forms.IntegerField()
Yeap. No mixins, no base classes. Just a simple Django form.
Now, let’s render our form:
{% load paper_forms %}
<form method="post">
{% field form.name %}
{% field form.age %}
</form>
This is exactly the html that you would get:
<form method="post">
<input type="text" name="name" id="id_name" required />
<input type="number" name="age" id="id_age" required />
</form>
As you can see, a {% field form.field %}
template tag behaves
exactly like {{ form.field }}
.
Now, let's add some customization.
Customization
The simplest thing you can do is to add (or replace) attributes to the widget:
{% load paper_forms %}
<form method="post">
{% field form.name placeholder="Enter your name" %}
{% field form.age placeholder="Enter your age" title=form.age.label %}
</form>
Result:
<form method="post">
<input type="text" name="name" id="id_name" placeholder="Enter your name" required />
<input type="number" name="age" title="Age" required placeholder="Enter your age" id="id_age" />
</form>
Note that you cannot specify an attribute with a dashes, like data-src
.
This is because @simple_tag
is quite restrictive and doesn't allow dashes
in kwargs names.
A way to get around this limitation is to use double-underscore.
All double-underscore in {% field %}
arguments are replaced with single dash:
{% field form.name data__original__name="Name" %}
<!-- would render to something like -->
<input ... data-original-name="Name" />
Write your own field templates
Example:
<div class="form-field">
<label for="{{ widget.attrs.id }}">{{ label }}</label>
<!-- include default widget template -->
{% include widget.template_name %}
<!-- show field errors -->
{% if errors %}
<ul>
{% for error in errors %}
<li>{{ error }}</li>
{% endfor %}
</ul>
{% endif %}
<!-- show help text -->
{% if help_text %}
<small>{{ help_text }}</small>
{% endif %}
</div>
The paper_forms
not only makes it possible to override widget templates,
but also extends them to form field templates.
Override widget template with Composer
Composer is a tool which gives you full control over form field rendering.
Example:
from django import forms
from paper_forms.composers.base import BaseComposer
class ExampleForm(forms.Form):
name = forms.CharField()
password = forms.CharField()
class Composer(BaseComposer):
widgets = {
"password": forms.PasswordInput
}
template_names = {
"password": "path/to/field_template.html"
}
labels = {
"password": "Enter your password"
}
help_texts = {
"password": "Your password must be 8-20 characters long, "
"contain letters and numbers, and must not contain "
"spaces, special characters, or emoji."
}
As you can see, attributes such as widgets
, labels
and help_texts
are very similar to those
of the ModelForm
's Meta
class.
The data specified in the composer fields have the highest priority.
Create your own Composer
subclass for web frameworks
Example:
from django.forms import widgets
from paper_forms.composers.base import BaseComposer
class Bootstrap4(BaseComposer):
def get_default_template_name(self, widget):
# Overrides the widget template, but has a lower priority
# than the 'template_names' field.
if isinstance(widget, widgets.CheckboxInput):
return "paper_forms/bootstrap4/checkbox.html"
else:
return "paper_forms/bootstrap4/input.html"
def get_default_css_classes(self, widget):
# Adds default CSS classes that can be overridden
# in the {% field %} template tag.
if isinstance(widget, widgets.CheckboxInput):
return "form-check-input"
else:
return "form-control"
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for paper_forms-0.0.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3ef82544a206d63edfc4b952772ece1ed4704600626bdc1827b39088fa7df19e |
|
MD5 | 579d7236975a560b05207ba09321be6e |
|
BLAKE2b-256 | 69b68ca3919a8b4fceb2c237e8de078696ded629a829a0d07f0d95eaf36c1900 |