Skip to main content
Join the official Python Developers Survey 2018 and win valuable prizes: Start the survey!

Form rendering for Django

Project description

https://travis-ci.org/matthiask/django-fineforms.png?branch=master

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.

{% 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
django_fineforms-0.3.1-py2.py3-none-any.whl (10.0 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Sep 5, 2017
django-fineforms-0.3.1.tar.gz (7.6 kB) Copy SHA256 hash SHA256 Source None Sep 5, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page