/tbxforms

Primary LanguagePythonOtherNOASSERTION

PyPI npm PyPI downloads Build status Coverage Status Total alerts

Torchbox Forms

A Torchbox-flavoured template pack for django-crispy-forms, adapted from crispy-forms-gds.

Contents

Installation

You must install both a Python package and an NPM package.

Install the Python package

Install using pip:

pip install tbxforms

Add django-crispy-forms and tbxforms to your installed apps:

INSTALLED_APPS = [
  ...
  'crispy_forms',  # django-crispy-forms
  'tbxforms',
]

Now add the following settings to tell django-crispy-forms to use this theme:

CRISPY_ALLOWED_TEMPLATE_PACKS = ["tbx"]
CRISPY_TEMPLATE_PACK = "tbx"

Install the NPM package

Install using NPM:

npm install tbxforms

Instantiate your forms:

import TbxForms from '@tbxforms/tbxforms';

document.addEventListener('DOMContentLoaded', () => {
    for (const form of document.querySelectorAll(TbxForms.selector())) {
        new TbxForms(form);
    }
});

Import the styles into your project:

@import 'node_modules/@tbxforms/tbxforms/static/sass/tbxforms';

Usage

Creating a Django form

from tbxforms.forms import BaseForm as TbxFormsBaseForm

class ExampleForm(TbxFormsBaseForm, forms.Form):
    # < Your field definitions >

    # Although not required, it is recommended to add a helper:
    @property
    def helper(self):
        fh = super().helper
        fh.html5_required = True
        fh.label_size = Size.MEDIUM
        fh.legend_size = Size.MEDIUM
        fh.form_error_title = _("There is a problem with your submission")
        return fh

class ExampleModelForm(TbxFormsBaseForm, forms.ModelForm):
    # < Your field definitions and ModelForm config >

    # Although not required, it is recommended to add a helper:
    @property
    def helper(self):
        fh = super().helper
        fh.html5_required = True
        fh.label_size = Size.MEDIUM
        fh.legend_size = Size.MEDIUM
        fh.form_error_title = _("There is a problem with your submission")
        return fh

Creating a Wagtail form

Two parts are required for this to work:

  1. Add a helper property to the Wagtail form
  2. Instruct a Wagtail Page model to use the newly created form

Add a helper property to the Wagtail form

from wagtail.contrib.forms.forms import BaseForm as WagtailBaseForm
from tbxforms.forms import BaseForm as TbxFormsBaseForm

class ExampleWagtailForm(TbxFormsBaseForm, WagtailBaseForm):
    @property
    def helper(self):
        fh = super().helper
        fh.html5_required = True
        fh.label_size = Size.MEDIUM
        fh.legend_size = Size.MEDIUM
        fh.form_error_title = _("There is a problem with your submission")
        fh.add_input(
            Button.primary(
                name="submit",
                type="submit",
                value=_("Submit"),
            )
        )
        return fh

Instruct a Wagtail Page model to use the newly created form

# in your forms definitions (e.g. forms.py)

from tbxforms.forms import BaseWagtailFormBuilder as TbxFormsBaseWagtailFormBuilder
from path.to.your.forms import ExampleWagtailForm

class WagtailFormBuilder(TbxFormsBaseWagtailFormBuilder):
    def get_form_class(self):
        return type(str("WagtailForm"), (ExampleWagtailForm,), self.formfields)

# in your page models (e.g. models.py)

from path.to.your.forms import WagtailFormBuilder

class ExampleFormPage(...):
    ...
    form_builder = WagtailFormBuilder
    ...

Render a form

Just like Django Crispy Forms, you need to pass your form object to the {% crispy ... %} template tag, e.g.:

{% load crispy_forms_tags %}
{% crispy your_form %}

Conditionally-required fields

TODO: add instructions.

Customising form styles

Out of the box, forms created with tbxforms will look like the GOV.UK Design System, though many variables can be customised.

To customise a variable, define it in your project. See tbxforms/static/sass/abstracts/_variables.scss for options.

Further reading