django-fineforms - Form rendering for Django¶
This library offers an improved replacement for Django’s own form
rendering methods (as_p
, as_table
etc.) while staying simple
and extensible but without introducing a whole new framework.
django-fineforms consists of a template tag library and a few opinionated default templates.
Goals¶
- Stay simple and extensible
- Avoid options, settings and customizability as much as possible
Non-goals¶
- Compete with django-crispy-forms or any of the more flexible libraries out there
Installation¶
Simply pip install django-fineforms
, and add fineforms
to your
INSTALLED_APPS
.
High-level overview¶
The template tags mostly wrap their arguments in wrapper classes that do
the real work. For example, {% ff_field %}
simply wraps the passed
field in a wrapper defined in the FINEFORMS_WRAPPERS
setting. All
wrappers use a template to render their output. The default wrapper
types are as follows:
{
'errors': ErrorsWrapper,
'field': FieldWrapper,
'field-plain': PlainFieldWrapper,
'fields': FieldsWrapper,
}
The wrappers themselves mostly aren’t configurable, but you can replace
individual wrappers (or all of them) by adding a FINEFORMS_WRAPPERS
setting. You do not have to override all of them; if you only want to
add another wrapper for a specific field type you could just set:
FINEFORMS_WRAPPERS = {
'specific': 'app.wrappers.SpecificWrapper',
}
… and use this wrapper as {% ff_field some_field type='specific' %}
somewhere in your templates.
Template tags¶
All template tags are contained in the fineforms
library.
{% ff_field field [type=field] %}
¶
Template: fineforms/field.html
Render a single field. The wrapper can be optionally overridden by
passing a different type. The key has to exist in the
FINEFORMS_WRAPPERS
dictionary.
The default implementation renders the label, the widget, help text and
errors related to the field. It is recommended to also set the
error_css_class
and required_css_class
form attributes; those
classes are also added to the output.
The field-plain
type can be used if the widget should be rendered
alone. A wrapping <span>
tag still contains the CSS classes
mentioned above.
{% ff_fields form [fields='a,b,c' | exclude='a,b,c'] %}
¶
Template: fineforms/fields.html
Render fields of a form. fields
and exclude
are
comma-separated strings that can be used to only render a selection of
fields. The fields
parameter takes precedence if both are given.
Hidden fields are rendered separately at the end, all other fields are
wrapped using FINEFORMS_WRAPPERS['field']
and rendered as well.
{% ff_errors form1 [form2 ...] %}
¶
Template: fineforms/errors.html
Render form errors at the top. The default implementation renders all
non-field errors, and all errors from hidden fields. Falsy parameters
(i.e. None
) are filtered out for you. If there aren’t any errors at
all nothing is rendered.
Change log¶
Next version¶
- Added
forms
to the context offineforms/errors.html
,form
to the context offineforms/fields.html
.
0.5 (2019-02-13)¶
- Added a
ff_submit
tag for showing submit buttons. - All defaults are arbitrary. Arbitrarily changed the default for the
foundation_xy_grid
package to only show fields and labels in one line for large screend.
0.4 (2018-12-26)¶
- Added CSS classes to the default
ff_errors
template’s top level element and also to the error list. - Moved all wrappers into
fineforms.wrappers
. - Reformatted the code using black.
- Modified template tags to pass on keyword arguments to the wrappers they instantiate.
- Added a template package using Foundation’s XY-grid, usable by
adding
fineforms.pacakges.foundation_xy_grid
beforefineforms
toINSTALLED_APPS
.
0.3 (2017-09-04)¶
- Django also adds
required_css_class
to the label tag; do the same (and also adderror
because it simplifies the code). - Parametrize the CSS classes used for
error_css_class
andrequired_css_class
. - Add an additional wrapping
div
to the defaultwidget_then_label
field template to avoid flex children layout. - Add the widget class name as a
widget--$name
CSS class to the output. This makes styling radio selects more straightforward (use a.widget--radioselect ...
CSS selector)
0.2 (2017-05-25)¶
- Documentation work.
- Allow specifying additional wrappers as dotted Python paths to avoid problems with circular imports.
- The
FieldWrapper
now passeslabel_tag
andcss_classes
into the template;label_tag
usesFieldWrapper.label_suffix
(defaulting to''
), andcss_classes
containsrequired
anderror
if fitting and ifForm.required_css_class
andForm.error_css_class
are undefined.