Sensible form extensions for django.
Project description
Description
django-extensible-forms
is a form functionality extension for django that introduces the well established Meta
class API for form construction. It allows customizing field widget rendition attributes and CSS on an individual level, without having to write custom HTML.
Installation
Install from pypi with pip install django-extensible-forms
or install directly with git clone https://github.com/Naggafin/django-extensible-forms.git && cd django-extensible-forms/ && pip install .
Once the package is installed, add it to your project by including the following in your settings.py
:
INSTALLED_APPS = [
"django_extensible_forms",
"django_extensible_forms.bootstrap5", # if you want Bootstrap5 niceities
...
# goes last
"django.forms",
]
FORM_RENDERER = "django_extensible_forms.renderers.TemplatesSetting"
Examples
You're using AlpineJS. You want to use its x-model
feature without having to manually write it out in HTML for each field. You also want custom CSS, without it being a pain in the ass to do. This can be done with the following:
import django_extensible_forms as forms
class MyForm(forms.Form):
username = forms.CharField(autofocus=True)
password = forms.CharField(autocomplete="new-password", strip=False)
class Meta:
css = {
'fields': {
'username': ["form-control"],
'password': ["form-control"],
}
}
attrs = {
'fields': {
'username': {'x-model': "username"},
'password': {'x-model': "password"},
}
}
Instantiating this form and rendering it produces the following HTML:
<div>
<label for="id_username" class="required">Username:</label>
<input type="text" name="username" required autofocus x-model="username" id="id_username" class="form-control required">
<div id="id_usernameFeedback" class="errorlist" style="display: none;"></div>
</div>
<div>
<label for="id_password" class="required">Password:</label>
<input type="text" name="password" required autocomplete="new-password" x-model="password" id="id_password" class="form-control required">
<div id="id_passwordFeedback" class="errorlist" style="display: none;"></div>
</div>
Take notice of how our CSS is properly included ("required" is added automatically, though this can be customized on the form class definition) and our attributes were added accordingly. The username
input has x-model="username"
and the autofocus
attributes, while the password
input has x-model="password"
and the autocomplete="new-password"
attributes. Attributes and CSS can be added either directly as keywoed arguments to the field or through Meta
definitions.
Usage
I apologize in advance for the brevity of the documentation here. I plan to write more detailed API docs, but for now, I am unfortunately far too busy. I hope this suffices for now.
Define attributes through Meta definitions
The preferred way to define custom attributes is through the Meta
class interface. The following fields are available for customization in the Meta
API: template_name
, template_name_label
, css
, attrs
, help_texts
, error_class
, field_error_class
, localized_fields
, field_order
. I'll go into detail what they're for and how to use each now.
template_name
[str
] sets the template for the form to use. You can still set the template the old way as well by defining it directly on the form. If you do that, the declaration on the form itself takes precedence over the declaration within the Meta
class.
template_name_label
[str
] sets the template for labels for fields to use. You can still set the template the old way as well by defining it directly on the form. If you do that, the declaration on the form itself takes precedence over the declaration within the Meta
class.
error_class
[object
] defines what class to use to render non-field errors.
field_error_class
[object
] defines what class to use to render field errors.
field_order
[Iterable
] defines what order the fields should appear in. This has no effect if this is manually declared within your HTML template for the form.
localized_fields
[Iterable | str
] defines which fields should use i18n localization for presentation. Specify '__all__'
to include all fields. Otherwise, an iterable of field names to localize should be used.
css
[dict
] defines the CSS for the form. The dict
specified should be structured like so, with any given key-value pair being optional to include:
css = {
'form': {
'error_css_class': "custom-error-class",
'required_css_class': "custom-required-class",
'non_field_errors_css_class': "custom-nonfield-errors-section-class",
},
'fields': {
'__all__': "css-applied-to-all-inputs",
'<field_name_here>': "custom-input-css",
},
'labels': {
'__all__': "css-applied-to-all-labels",
'<field_name_here>': "custom-label-css",
},
'field_errors': {
'__all__': "css-applied-to-all-field-errors-tag",
'<field_name_here>': "custom-error-css",
},
'separators': {
'__all__': "css-applied-to-all-field-separator-tags",
'<field_name_here>': "custom-separator-css",
},
'help_texts': {
'__all__': "css-applied-to-all-field-help-texts",
'<field_name_here>': "custom-help-text-css",
}
}
attrs
[dict
] defines the attributes for the form. The dict
specified should be structured like so, with any given key-value pair being optional to include:
attrs = {
'fields': {
'__all__': {'data-example-attr': "customValue"},
'<field_name_here>': {'data-example-attr': "customValue"},
},
'labels': {
'__all__': {'data-example-attr': "customValue"},
'<field_name_here>': {'data-example-attr': "customValue"},
},
'help_texts': {
'__all__': {'data-example-attr': "customValue"},
'<field_name_here>': {'data-example-attr': "customValue"},
},
}
Define attributes through field definitions
Any attribute you could specify in Meta
can be done directly within the field definition. The available extra parameters are css
, label_css
, error_css
, separator_css
, help_text_css
, attrs
, label_attrs
, separator_attrs
, help_text_attrs
, bf_class
, and template_name
. Any extra keyword argument which does not match an argument in the field's __init__()
function spec will be applied as an HTML attribute. This is why setting autofocus=True
on the CharField
for username
in the example produced the result it did. The same result could've been achieved by passing attrs={'autofocus': True}
instead.
I'll detail what each keyword argument is for now:
css
[str | Iterable
] defines what shall appear in the HTML class
property on the input
tag. If there is a conflicting Meta
defintion, this definition takes precedence.
label_css
[str | Iterable
] defines what shall appear in the HTML class
property on the label
tag. If there is a conflicting Meta
defintion, this definition takes precedence.
error_css
[str | Iterable
] defines what shall appear in the HTML class
property on the div
tag containing field errors. If there is a conflicting Meta
defintion, this definition takes precedence.
separator_css
[str | Iterable
] defines what shall appear in the HTML class
property on the div
tag containing the field as a whole (input, label, help text, errors). If there is a conflicting Meta
defintion, this definition takes precedence.
help_text_css
[str | Iterable
] defines what shall appear in the HTML class
property on the div
tag containing the help text. If there is a conflicting Meta
defintion, this definition takes precedence.
attrs
[dict
] defines what custom attributes should appear in the HTML for the input
tag. If there is a conflicting Meta
defintion, the declarations within the field definition combine with the declarations in the Meta
definition, with those defined in the field taking precedence.
label_attrs
[dict
] defines what custom attributes should appear in the HTML for the label
tag. If there is a conflicting Meta
defintion, the declarations within the field definition combine with the declarations in the Meta
definition, with those defined in the field taking precedence.
separator_attrs
[dict
] defines what custom attributes should appear in the HTML for the div
tag containing the field as a whole (input, label, help text, errors). If there is a conflicting Meta
defintion, the declarations within the field definition combine with the declarations in the Meta
definition, with those defined in the field taking precedence.
help_text_attrs
[dict
] defines what custom attributes should appear in the HTML for the div
tag containing the help text. If there is a conflicting Meta
defintion, the declarations within the field definition combine with the declarations in the Meta
definition, with those defined in the field taking precedence.
bf_class
[object
] defines what class to use as this field's BoundField class for rendering.
template_name
[str
] defines what template to use to render the field as a whole, which includes the separator element, the widget, any errors, and help text. This is not to be confused with the widget template; it does not override that.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_extensible_forms-0.9.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 73dbad1d9e5a6b75db18e8ecf4d565ce775f12243d53e6ef3e98fbb9ab7cf749 |
|
MD5 | 274aef66318785fd252605ff8f6a319e |
|
BLAKE2b-256 | 697e9693919f765d52b5050df2cdbc56966345dbb2b27af97450dba15917e0c6 |
Hashes for django_extensible_forms-0.9.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8f18be7cb94099572fb47557c4d892913cc82ad1f5513ed583de7d9ce93d5de2 |
|
MD5 | 4345b5871b2ff1f4b8ef528a8f704576 |
|
BLAKE2b-256 | 268faac211be005361c853cd623fe229e9c00df84b43d01595ba6aae94dfeaad |