Django forms at warp speed¶
Django Formaldehyde is a small reusable unobtrusive Django app that leverage forms.
- Home page: https://github.com/kunitoki/django-formaldehyde
- Documentation: http://django-formaldehyde.readthedocs.org
- Pypi: https://pypi.python.org/pypi/django-formaldehyde
- Example app on Github: https://github.com/kunitoki/django-formaldehyde/example
- Changelog: Changelog.rst
- License: The MIT License (MIT)
- Supports: Django 1.6, 1.7, 1.8 - Python 2.7, 3.2, 3.3, 3.4
Getting started¶
You can get Django Formaldehyde by using pip:
pip install django-formaldehyde
You will need to add the
'formaldehyde'
application to theINSTALLED_APPS
setting of your Django projectsettings.py
file.:INSTALLED_APPS = ( ... 'formaldehyde', )
Configuration¶
It is possible to configure by using in settings.py
.:
FORMALDEHYDE_SETTINGS = {
'GRID_COLUMN_NUMBER': 12,
'DEFAULT_FIELD_COLUMN_SIZE': 1,
'DEFAULT_LABEL_COLUMN_SIZE': 1,
'FIRST_LABEL_COLUMN_SIZE': 2
}
Classes and Mixins¶
django-formaldehyde provides a series of django.forms.Form mixins to help the handling of forms in applications.
FieldsetFormMixin¶
The mixin add fieldsets with fieldlines to forms. It also add the concept of layout of the fields, so it is possible to place fields and labels in the grid space. Everything is used inside an inner class called MetaForm:
from django import forms
from formaldehyde.fieldsets import FieldsetFormMixin
class ExampleFieldsetForm(FieldsetFormMixin, forms.Form):
first_name = forms.CharField(label='First name', max_length=100)
last_name = forms.CharField(label='Last name', max_length=100)
nick_name = forms.CharField(label='Nick name', max_length=100)
avatar = forms.IntegerField()
photo = forms.ImageField()
class Meta:
fields = '__all__'
class MetaForm:
fieldsets = (
(None, {
'fields': (
('first_name', 'last_name'),
'nick_name',
),
'layout': (
(4, 6),
2
),
'labels': (
(2, 1),
1
),
'classes': 'form-control'
}),
('Social', {
'fields': (
'avatar',
'photo'
)
}),
)
An example template (for bootstrap grid system) for rendering the form looks like:
{% if form.fieldsets %}
{% for fieldset in form.fieldsets %}
<fieldset class="{{ fieldset.classes }}">
{% if fieldset.legend %}
<legend>{{ fieldset.legend }}</legend>
{% endif %}
{% if fieldset.description %}
<p class="description">{{ fieldset.description }}</p>
{% endif %}
{% for fieldline in fieldset %}
<div class="form-group">
{% for field, layout in fieldline %}
{% if field.is_hidden %}
{{ field }}
{% else %}
<label class="col-sm-{% if forloop.first %}2{% else %}1{% endif %} control-label">
{{ field.label }}
</label>
<div class="col-sm-{{ layout|default:10 }}">
{{ field }}
</div>
{% endif %}
{% endfor %}
</div>
{% endfor %}
</fieldset>
{% endfor %}
{% else %}
{% for hidden in form.hidden_fields %}
{{ hidden }}
{% endfor %}
{% for field in form.visible_fields %}
<div class="form-group{% if field.errors %} has-error{% endif %}">
<label class="col-sm-{% if forloop.first %}2{% else %}1{% endif %} control-label">
{{ field.label }}
</label>
<div class="col-sm-{{ field_size|default:10 }}">
{{ field }}
</div>
</div>
{% endfor %}
{% endif %}
ReadonlyFormMixin¶
StripWhitespaceFormMixin¶
Support¶
- Github: Use django-formaldehyde github issues, if you have any problems using Django Formaldehyde.
Changelog¶
Only important changes are mentioned below.
v0.4 (unreleased)¶
- refactored field line iteration (backward incompatible)
- fieldsets in MetaForm take both ‘labels’ and ‘layout’ to specify labels size in grid
- fixed a problem with immutable MergeDict in StripWhitespaceFormMixin
- updated docs
v0.3 (2015-01-30)¶
- fieldsets in MetaForm can be avoided if preferred
v0.2 (2015-01-30)¶
- Fixed problem with assertion on django.forms.ModelForm
v0.1 (2015-01-21)¶
- First version released