============================================
django-fineforms - Form rendering for Django
============================================
.. image:: https://github.com/matthiask/django-fineforms/workflows/Tests/badge.svg
:target: https://github.com/matthiask/django-fineforms
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:
.. code-block:: python
{
"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:
.. code-block:: python
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.
``{% ff_hidden_fields form1 [form2 ...] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This template tag is the outlier in that it does not use a template at
all. The return value is the concatenated result of rendering all hidden
fields of all passed forms. Falsy parameters (i.e. ``None``) are
filtered out for you.
Please note that ``{% ff_fields %}`` adds hidden fields to the output
automatically.
``{% ff_submit [_("label")] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Template: ``fineforms/submit.html``
Show a submit button.