Skip to main content

Template based form rendering for Django

Project description

Build Status Codecov Version License

Template based form rendering for Django


Overview

Django 1.11 recently introduced template-based widget rendering to allow easier customization of widgets by users. django-template-forms is the logical extension of this feature, implementing template-based rendering for fields and forms.

At this point, simple block forms are supported for Bootstrap 3 & 4. Horizontal forms and check/radio field layouts are inbound.

Requirements

  • Python: 3.4, 3.5, 3.6
  • Django: 1.11, 2.0b

Install with pip:

$ pip install django-template-forms

Configuration

Once installed, add 'template_forms' to your INSTALLED_APPS.

INSTALLED_APPS = [
    ...
    'template_forms',
]

Usage

All template_forms form classes inherit from django.forms.BaseForm and are intended to be mixed with a concrete forms.Form or froms.ModelForm. Example usage:

from django import forms
from template_forms import bs3

from .models import Article


class ArticleForm(bs3.BlockForm, forms.ModelForm):
    class Meta:
        model = Article
        fields = ['title', 'author', 'published_date', ...]

In the view template:

<form method="post" action="">
    {% csrf_token %}
    {{ form }}
    <button class="btn btn-primary" type="submit">Save</button>
</form>

TODO: Document creation of custom TemplateForm subclass.

Overriding Templates

django-template-forms provides a default set of templates. To override these, you first need to consider the `FORM_RENDERER <https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-FORM_RENDERER>`__ setting, then override the relevant template files. By default, FORM_RENDERER uses the `DjangoTemplates <https://docs.djangoproject.com/en/1.11/ref/forms/renderers/#djangotemplates>`__ renderer, which loads templates from your installed apps.

If you want more control over template loading, you can use the `TemplatesSetting <https://docs.djangoproject.com/en/1.11/ref/forms/renderers/#templatessetting>`__ renderer, which loads templates from using your configured TEMPLATES setting. If you use this renderer, you may need to add 'django.forms' to your INSTALLED_APPS. See the renderer docs for more information.

INSTALLED_APPS = [
    ...
    'django.forms',
    'template_forms',
]

FORM_RENDERER = 'django.forms.renderers.TemplatesSetting'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [...],
        'APP_DIRS': True,
        ...
    },
]

Templates are provided for each supported CSS framework.

Note: - horizontal layouts do not exist yet for BS 4. - check & radio field templates do not exist yet.

BS3:

  • template_forms/bs3/forms/block.html
  • template_forms/bs3/forms/horizontal.html
  • template_forms/bs3/fields/block.html
  • template_forms/bs3/fields/block_checkbox.html
  • [STRIKEOUT:template_forms/bs3/fields/block_check_inline.html]
  • [STRIKEOUT:template_forms/bs3/fields/block_check_stacked.html]
  • [STRIKEOUT:template_forms/bs3/fields/block_radio_inline.html]
  • [STRIKEOUT:template_forms/bs3/fields/block_radio_stacked.html]
  • template_forms/bs3/fields/horizontal.html
  • template_forms/bs3/fields/horizontal_checkbox.html
  • [STRIKEOUT:template_forms/bs3/fields/horizontal_check_inline.html]
  • [STRIKEOUT:template_forms/bs3/fields/horizontal_check_stacked.html]
  • [STRIKEOUT:template_forms/bs3/fields/horizontal_radio_inline.html]
  • [STRIKEOUT:template_forms/bs3/fields/horizontal_radio_stacked.html]

BS4:

  • template_forms/bs4/forms/block.html
  • [STRIKEOUT:template_forms/bs4/forms/horizontal.html]
  • template_forms/bs4/fields/block.html
  • [STRIKEOUT:template_forms/bs4/fields/block_checkbox.html]
  • [STRIKEOUT:template_forms/bs4/fields/block_check_inline.html]
  • [STRIKEOUT:template_forms/bs4/fields/block_check_stacked.html]
  • [STRIKEOUT:template_forms/bs4/fields/horizontal.html]
  • [STRIKEOUT:template_forms/bs4/fields/horizontal_checkbox.html]
  • [STRIKEOUT:template_forms/bs4/fields/horizontal_check_inline.html]
  • [STRIKEOUT:template_forms/bs4/fields/horizontal_check_stacked.html]

Running the tests

The test suite requires tox and tox-venv. The full list of builds is viewable with tox -l.

$ pip install tox tox-venv
$ tox -e py36-django111
$ tox -e lint,isort

Release Process

  • Update package version in setup.py
  • Create git tag for version
  • Upload release to PyPI sh   $ pip install -U setuptools wheel pypandoc   $ rm -rf dist/ build/   $ python setup.py bdist_wheel upload

Project details


Download files

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

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page