Form classes¶
Several form classes are provided with django-registration
, covering common
cases for gathering account information and implementing common constraints for
user registration. These forms were designed with django-registration
’s
built-in registration workflows in mind, but may also be useful in other
situations.
- class django_registration.forms.RegistrationForm(*args, **kwargs)[source]¶
A form for registering a new user account.
This is the default form class used by all included views in
django-registration
, and is designed to be able to work with a wide variety of user models.If you’re using Django’s default
User
model, this form will work automatically. If you’re using a custom user model, this form can work with it so long as your user model meets certain requirements.This form is a
ModelForm
which will derive fields and basic validation from your user model’s field definitions, though it will also perform additional validation steps on certain fields. As aModelForm
, callingsave()
will create an instance of the user model from the validated data, save it to the database, and return it.In general you should use this form as-is, and only subclass it if you want to remove one or more of the additional validators applied here (if you want to supply extra validators, you can do so via subclassing, but you can also declare them on your user model and have them automatically picked up by this form).
If you do find yourself needing to remove validators from this form, it may be better to instead write and use a subclass of
BaseRegistrationForm
, which is a more minimal base class that does not implement any of the field or validation handling of this form.Using a custom user model
Custom user models are supported, but you will need to ensure a few attributes are set on your custom user model to allow this form to work with it:
EMAIL_FIELD
: astr
specifying the name of the field containing the user’s email address.USERNAME_FIELD
: astr
specifying the name of the field containing the user’s “username”. If you use the email address as the primary “username”/identifier, set this to the same field name asEMAIL_FIELD
.REQUIRED_FIELDS
: alist
of names of fields on your user model which must be included in the form.
Django’s
AbstractUser
, which is what many custom user models will inherit from and also what the default Django user model inherits from, sets all three of these, and generally for a custom model you would only need to overrideREQUIRED_FIELDS
in order to specify any additional custom fields of your model which should be included in the form.However, if you have a custom user model which inherits from Django’s
AbstractBaseUser
(which is an even more minimal base class thanAbstractUser
), or which does not inherit from any of Django’s abstract base user classes, you will need to set all three of the above attributes on your custom user model for it to be usable with this form.Additionally, if you use a registration workflow which sends an email to the newly-registered user, your user model must implement the
email_user()
method, with the same API as Django’s implementation. If your user model inherits fromAbstractUser
, this method is implemented for you automatically.Fields defined on this form
Django’s
AbstractBaseUser
does not include its username field inREQUIRED_FIELDS
. To work around that, this form will include all fields listed in your user model’sREQUIRED_FIELDS
and will also include the field named in your user model’sUSERNAME_FIELD
if it is not included inREQUIRED_FIELDS
.If your user model’s email address field is also its username field, set both
EMAIL_FIELD
andUSERNAME_FIELD
to that field’s name, as noted above; the field will be included in the form only once.This form will also include two password fields, with field names
password1
andpassword2
, which will be used to set the user account’s password. Two fields are used in order to implement the common UI pattern of requiring the user to enter the password twice and check that both entries match.Validation on this form
In addition to any validation requirements or validators defined on your user model and its fields, this form will apply the following validation checks:
The values entered into the
password1
andpassword2
fields match. If they do not match, the validation error will be attached to thepassword2
field.The value entered into the password fields passes all password validators configured in your Django settings. If the password fails validation, the error will be attached to the
password2
field.The value entered into the username field is not a case-insensitive match for any existing username value.
The value entered into the username field is not a reserved name. To override the default set of reserved names, subclass this form and set the attribute
reserved_names
to the list of names you wish to reserve.The value entered into the username field is not a “confusable” value (see the documentation on preventing homograph attacks for an explanation).
The field named in your user model’s
EMAIL_FIELD
attribute will haverequired=True
(Django’s defaultAbstractBaseUser
setsblank=True
on the email field, making it optional in any form which does not override this).The value entered into the email address field conforms to the HTML5 email validation rule. Note that this validation rule is automatically enforced client-side by HTML5-compliant browsers as part of the implementation of
input type="email"
, but is also significantly stricter than what the email RFCs allow in an address. Many unusual syntactic constructs which are permitted by the email RFCs are disallowed by HTML5’s email validation and will be rejected bydjango-registration
.The value entered into the email address field does not contain a “confusable” value in its local-part or in its domain, though the combination of the local-part and domain together is allowed to be “confusable”.
- class django_registration.forms.RegistrationFormTermsOfService(*args, **kwargs)[source]¶
A subclass of
RegistrationForm
which adds one extra required field: a checkbox namedtos
indicating agreement to a site’s terms of service.
- class django_registration.forms.RegistrationFormUniqueEmail(*args, **kwargs)[source]¶
A subclass of
RegistrationForm
which enforces uniqueness of email addresses.
- class django_registration.forms.BaseRegistrationForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, instance=None, use_required_attribute=None, renderer=None)[source]¶
Minimal user registration form class.
In most cases, this form should not be used directly, and
RegistrationForm
should be used instead as the base class of user-registration forms. The primary difference between this class andRegistrationForm
is thatRegistrationForm
makes some additional assumptions about which fields to include and includes significant custom validation logic, while this form attempts to be as minimal as possible with respect to included fields.In general, you should be using
RegistrationForm
unless you are absolutely certain that you need to build your own custom registration form without usingRegistrationForm
’s additional validation or fields.Using a custom user model
Custom user models are supported, but you will need to ensure a few attributes are set on your custom user model to allow this form to work with it:
EMAIL_FIELD
: astr
specifying the name of the field containing the user’s email address.USERNAME_FIELD
: astr
specifying the name of the field containing the user’s “username”. If you use the email address as the primary “username”/identifier, set this to the same field name asEMAIL_FIELD
.REQUIRED_FIELDS
: alist
of names of fields on your user model which must be included in the form.
Django’s
AbstractUser
, which is what many custom user models will inherit from and also what the default Django user model inherits from, sets all three of these, and generally for a custom model you would only need to overrideREQUIRED_FIELDS
in order to specify any additional custom fields of your model which should be included in the form.However, if you have a custom user model which inherits from Django’s
AbstractBaseUser
(which is an even more minimal base class thanAbstractUser
), or which does not inherit from any of Django’s abstract base user classes, you will need to set all three of the above attributes on your custom user model for it to be usable with this form.Additionally, if you use a registration workflow which sends an email to the newly-registered user, your user model must implement the
email_user()
method, with the same API as Django’s implementation. If your user model inherits fromAbstractUser
, this method is implemented for you automatically.Fields defined on this form
The set of fields on this form will be all and only the fields listed in your user model’s
REQUIRED_FIELDS
attribute. If you are using the default Django user model, or a subclass ofAbstractUser
without overridingREQUIRED_FIELDS
, this will not include the username field. It also will not include any fields or logic related to setting/validating a password. It is assumed, if you are using this minimal base class, that you will either find this acceptable or be providing your own custom logic in a subclass to handle your particular needs.