Fields
There are no additional fields provided by this package. However, there are some Enhancements to existing Django Fields as well as a few Text Field Properties that can be set on a Django field to add additional rendered functionality. Those enhancements and properties are explained below.
Warning
Some of the enhancements listed here might not be fully supported in all browsers yet. However, as time moves on, adoption should increase.
Enhancements
DateTimeField
Any DateTimeField
will be rendered out with the input type set to
datetime-local
, which will allow an automatic DateTime picker widget
provided by the browser per the HTML5 spec.
DateField
Any DateField
will be rendered out with the input type set to
date
, which will allow an automatic date picker widget
provided by the browser per the HTML5 spec.
TimeField
Any TimeField
will be rendered out with the input type set to
time
, which will allow an automatic time picker widget
provided by the browser per the HTML5 spec.
Text Field Properties
With HTML5 there are a lot of use cases for the input element that accepts text. Django handles some of these for us. Such as EmailField and URLField. However, there are some other types that Django does not support out of the box. Rather than making a whole new field that would have to be imported from this package rather than the default Django forms module, we choose to do some extra processing on a standard TextField if you set a specific property on the form field. This extra processing will make the TextField behave with some extra added functionality.
phone_info
If you would like to make a text field render as a phone input, you can add a
phone_info
property that is defined as a dictionary with keys inputmask
and pattern
.
This property will make the field render with both
an inputmask and regex phone pattern to use as validation.
The pattern
key will have a value that is a JavaScript regular expression
that the entered phone number must pass to be submitted.
More information about pattern
can be found via the
Mozilla Pattern Documentation
The inputmask
is specified as a string.
Information about making a valid format can be found in the repository for
Inputmask.
Warning
The pattern and inputmask should not be a replacement for server-side validation. You should still use a clean method on the phone field server-side to ensure that the field does have a correct value. The enhancements provided by this property are all client-side and can be circumvented. Thus it cannot be fully trusted to be accurate.
Note
There are two examples below. One sets the property in the form class. The other sets it in the View class. You should choose one way or the other. You do NOT need to set the property in both locations.
Setting phone_info in a Form class
forms.py
class SampleForm(forms.Form):
"""Sample Form with phone field type"""
sample_phone = forms.CharField()
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self['sample_phone'].phone_info = {
'pattern': r'\([0-9]{3}\) [0-9]{3}-[0-9]{4}',
'inputmask': '(999) 999-9999'
}
Setting phone_info in a View class
views.py
form = SampleForm()
form['sample_phone'].phone_info = {
'pattern': r'\([0-9]{3}\) [0-9]{3}-[0-9]{4}',
'inputmask': '(999) 999-9999'
}
range_min_max
If you would like to make a text field render as a range input, you can add a
range_min_max
property that is defined as a dictionary with keys min
and max
.
This property will make the field render with both a min and max value
that can be selected via the range.
The
min
key will provide the lowest value that can be submitted via the input. More information aboutmin
can be found via the Mozilla Min Range Documentation.The
max
key will provide the highest value that can be submitted via the input. More information aboutmax
can be found via the Mozilla Max Range Documentation.
Note
There are two examples below. One sets the property in the form class. The other sets it in the View class. You should choose one way or the other. You do NOT need to set the property in both locations.
Setting range_min_max in a Form class
forms.py
class SampleForm(forms.Form):
"""Sample Form with range field type"""
sample_range = forms.CharField()
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self['sample_range'].range_min_max={'min':5, 'max':9}
Setting range_min_max in a View class
views.py
form = SampleForm()
form['sample_range'].range_min_max={'min':5, 'max':9}
is_color
If you would like to make a text field render as a color input, you can add a
is_color
property with a value of True
.
This property will make the field render as a color selector.
More information about color
can be found via the
Mozilla Color Documentation.
Note
There are two examples below. One sets the property in the form class. The other sets it in the View class. You should choose one way or the other. You do NOT need to set the property in both locations.
Setting is_color in a Form class
forms.py
class SampleForm(forms.Form):
"""Sample Form with color field type"""
sample_color = forms.CharField()
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self['sample_color'].is_color = True
Setting is_color in a View class
views.py
form = SampleForm()
form['sample_color'].is_color = True
datalist
If you would like to add a datalist to a text field, you can add a
datalist
property with a value of dictionary with keys name
and
data
.
The
name
key should define the name of the datalist that will be used both as the value for the list attribute and the id in the rendered datalist.The
data
key should define the data for the datalist. This should be a list of values.
Note
This property can be applied to any text field. This includes but is not limited to:
text
email
url
phone
range
color
More information about how a datalist will work with the particular text input you have can be found at the Mozilla Datalist Documentation.
Note
There are two examples below. One sets the property in the form class. The other sets it in the View class. You should choose one way or the other. You do NOT need to set the property in both locations.
Setting datalist in a Form class
forms.py
class SampleForm(forms.Form):
"""Sample Form with range field type"""
sample_text = forms.CharField()
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self['sample_text'].datalist={
'name':'my_fancy_datalist',
'data': [
'My First Option',
'My Final Option',
],
}
Setting datalist in a View class
views.py
form = SampleForm()
form['sample_text'].datalist={
'name':'my_fancy_datalist',
'data': [
'My First Option',
'My Final Option',
],
}
Additional Datalist Examples
It is also possible to combine the work of adding a datalist with one of the other properties to enhance the field further. In the below examples we are using the datalist on the range input to add tickmarks to the range input at the values in the datalist. As you can see, it is only a matter of setting both properties on the field.
Note
There are two examples below. One sets the property in the form class. The other sets it in the View class. You should choose one way or the other. You do NOT need to set the property in both locations.
Setting datalist and range_min_max in a Form class
forms.py
class SampleForm(forms.Form):
"""Sample Form with range field type"""
sample_range = forms.CharField()
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self['sample_range'].range_min_max={'min':5, 'max':9}
self['sample_range'].datalist={
'name':'my_fancy_datalist',
'data': [5, 7, 9],
}
Setting datalist and range_min_max in a View class
views.py
form = SampleForm()
form['sample_range'].range_min_max={'min':5, 'max':9}
form['sample_range'].datalist={
'name':'my_fancy_datalist',
'data': [5, 7, 9],
}