API reference¶
Template tags¶
Important
This section is for projects using Django’s default
DjangoTemplates
backend. For
projects using Jinja2, see the Jinja2 functions section.
To use the following template tags, you’ll need to load this package’s custom template tag set in your templates like so:
{% load uswds_forms %}
fieldset
¶
The {% fieldset %}
tag can be used to render a form field using
the <fieldset>
element. The field’s label is also rendered,
along with any associated form errors and help text.
Markup is also added to ensure that screen reader users will have an easy time navigating grouped lists of options.
Sample usage:
{% fieldset my_form.name %}
{% fieldset my_form.address %}
{% fieldset my_form.birthday %}
Jinja2 functions¶
Important
This section is for projects using Django’s
Jinja2
backend. For
projects using Django templates, see the Template tags section.
For details on how to register any of these functions with your Jinja2 environment, see Jinja2 setup (optional).
-
uswds_forms.
fieldset
(field)[source]¶ Render the given bound field as a
<fieldset>
. The field’s label is also rendered, along with any associated form errors and help text.Once added to a Jinja2 environment, this function can be used from Jinja2 templates like so:
{{ fieldset(my_form.name) }} {{ fieldset(my_form.address) }} {{ fieldset(my_form.birthday) }}
Form¶
-
class
uswds_forms.
UswdsForm
[source]¶ This is a subclass of
django.forms.Form
that provides some functionality for rendering USWDS forms. Its constructor takes the exact same arguments, but some defaults are changed:error_class
defaults touswds_forms.UswdsErrorList
, so that errors are formatted nicely.label_suffix
defaults to the empty string, since none of the USWDS example forms have colons after the label names.
-
as_fieldsets
()[source]¶ Like other convenience methods such as
as_p()
andas_table()
, this method renders all the form’s fields as a series of<fieldset>
elements.Under the hood, this just iterates over the form’s fields and renders them via the fieldset template tag, so you can use that if you need more granular control over rendering.
Form fields¶
These fields use the same core field arguments as core Django.
-
class
uswds_forms.
UswdsDateField
(**kwargs)[source]¶ A
django.forms.MultiValueField
for a USWDS-style date. Its value normalizes to a Pythondatetime.date
object.For an example of how this looks in practice, see the USWDS date input example.
-
class
uswds_forms.
UswdsMultipleChoiceField
(**kwargs)[source]¶ This is just a
django.forms.MultipleChoiceField
that uses theUswdsCheckboxSelectMultiple
widget.We’ve provided this field for convenience because the usability of the default
django.forms.SelectMultiple
is so terrible that you’ll probably never want to use it. Burn your select tags!
Widgets¶
All of the following widgets work with
the DjangoTemplates
and
Jinja2
form renderers.
-
class
uswds_forms.
UswdsCheckboxSelectMultiple
[source]¶ This subclass of
django.forms.CheckboxSelectMultiple
styles grouped checkboxes appropriately for USWDS.You can use this in a
django.forms.MultipleChoiceField
to get a list of checkboxes instead of a<select multiple>
element for your choices.For an example of how this looks in practice, see the USWDS checkboxes example.
-
class
uswds_forms.
UswdsDateWidget
[source]¶ A
django.forms.MultiWidget
for a USWDS-style date, with separate number fields for date, month, and year.This widget is used automatically by
uswds_forms.UswdsDateField
, so you probably won’t need to use it directly. However, it can be subclassed in case you need to customize it.-
get_context
(name, value, attrs)[source]¶ Returns the context for the widget’s template. This returns a superset of what’s provided by its superclass’
get_context()
implementation, adding the following keys towidget
:'hint_id'
: The unique id of some hint text showing users an example of what they can enter.'subwidgets'
: This has the same iterable value described in the superclass documentation, but it has been enhanced such that itsyear
,month
, andday
properties are aliases to its entries. Using these aliases can potentially make templates more readable.
-
template_name
= 'uswds_forms/date.html'¶ This is the default template used by the widget, which can be overridden if needed.
-
-
class
uswds_forms.
UswdsRadioSelect
[source]¶ This subclass of
django.forms.RadioSelect
styles radio buttons appropriately for USWDS.You can use this in a
django.forms.ChoiceField
to get a list of radio buttons instead of a<select>
element for your choices.For an example of how this looks in practice, see the USWDS radio buttons example.
Other utilities¶
-
class
uswds_forms.
UswdsErrorList
[source]¶ This is an error list formatter that renders errors in the style used by USWDS forms. For an example of how this makes errors look in practice, see the USWDS text inputs example.
Note that you probably don’t need to use this class directly, as
UswdsForm
uses it by default.For more details on how to use this class, see the Django documentation on customizing the error list format.