django-fineforms 0.7.0
Form rendering for Django
License: BSD-3-Clause
Requires Python: >=3.8

============================================
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.