Виджет – это представление поля в виде HTML кода. Виджеты обеспечивают генерацию HTML и извлечение соответствующих данных из GET/POST запросов.
Совет
Не следует путать виджеты с полями формы. Поля формы обеспечивают логику проверки вводимой информации и используются в шаблонах. Виджеты же отвечают за рендеринг форм на веб-странице и обработку переданных данных. Тем не менее, виджеты следует назначать на поля формы.
При добавлении поля на форму, Django использует стандартный виджет, наиболее подходящий к отображаемому типу данных. Для того, чтобы узнать какой виджет использует интересующий вас тип поля обратитесь к built-in fields.
Тем не менее, если потребуется указать другой виджет для поля, просто используйте аргумент widget при определении поля. Например:
from django import forms
class CommentForm(forms.Form):
name = forms.CharField()
url = forms.URLField()
comment = forms.CharField(widget=forms.Textarea)
Этот код создают форму, у которой полю комментария назначен виджет class:Textarea вместо стандартного TextInput widget.
Большинство виджетов принимают дополнительные аргументы. Они могут быть назначены при определении виджета для поля. В следующем примере атрибут years передаётся в SelectDateWidget:
from django import forms
BIRTH_YEAR_CHOICES = ('1980', '1981', '1982')
FAVORITE_COLORS_CHOICES = (
('blue', 'Blue'),
('green', 'Green'),
('black', 'Black'),
)
class SimpleForm(forms.Form):
birth_year = forms.DateField(widget=forms.SelectDateWidget(years=BIRTH_YEAR_CHOICES))
favorite_colors = forms.MultipleChoiceField(required=False,
widget=forms.CheckboxSelectMultiple, choices=FAVORITE_COLORS_CHOICES)
Обратитесь к Встроенные виджеты для получения подробной информации о доступных виджетах и аргументах, которые они принимают.
Виджеты, унаследованные от виджета Select, предназначены для работы с вариантами. Они предоставляют список вариантов, из которых надо сделать выбор. Разные виджеты позволяют сделать выбор по-разному. Базовый виджет Select использует HTML тег <select>, а унаследованный виджет RadioSelect использует радио кнопки.
Виджеты типа Select по умолчанию используют поля ChoiceField. Варианты, отображаемые виджетом, наследуются от ChoiceField и изменение ChoiceField.choices повлияет на Select.choices. Например:
>>> from django import forms
>>> CHOICES = (('1', 'First',), ('2', 'Second',))
>>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
>>> choice_field.choices
[('1', 'First'), ('2', 'Second')]
>>> choice_field.widget.choices
[('1', 'First'), ('2', 'Second')]
>>> choice_field.widget.choices = ()
>>> choice_field.choices = (('1', 'First and only',),)
>>> choice_field.widget.choices
[('1', 'First and only')]
Виджеты, поддерживающие атрибут choices могут, тем не менее, использоваться совместно с полями, которые не основаны на выборе, – такими как CharField – но рекомендуется использовать поля типа ChoiceField в случаях, когда варианты берутся из модели.
При отображении виджета на странице сайта, Django генерирует минимальный HTML код, который не включает в себя указание классов или других специфических атрибутов виджета. Это означает, что все виджеты типа TextInput будут отображаться на странице однообразно.
Существует два способа настройки виджета: на уровне экземпляра виджет и на уровне класса виджета.
Если требуется визуально выделить один виджет от других, потребуется во время его создания указать для него дополнительные атрибуты и назначить его на поле формы (и возможно, добавить несколько правил в ваши CSS файлы).
Например, рассмотрим следующую простую форму:
from django import forms
class CommentForm(forms.Form):
name = forms.CharField()
url = forms.URLField()
comment = forms.CharField()
Эта форма включает в себя три обычных виджета TextInput, которым не назначены ни CSS класс, ни дополнительные атрибуты. Это означает, что визуально они будут выглядеть одинаково:
>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" /></td></tr>
<tr><th>Url:</th><td><input type="url" name="url"/></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
На реальной странице сайта, возможно, вам понадобится разнообразить их отображение. Вам может потребоваться сделать поле для ввода комментария побольше или назначить имя виджету, чтобы он начал реагировать на особый CSS класс. Также возможно указать атрибут ‘type’ для поддержки типов HTML5. Для этого надо использовать аргумент Widget.attrs при создании виджета:
class CommentForm(forms.Form):
name = forms.CharField(widget=forms.TextInput(attrs={'class': 'special'}))
url = forms.URLField()
comment = forms.CharField(widget=forms.TextInput(attrs={'size': '40'}))
Django добавит дополнительные атрибуты в генерируемый HTML код:
>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
<tr><th>Url:</th><td><input type="url" name="url"/></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
Вы также можете указать HTML id используя attrs. Смотрите BoundField.id_for_label.
Для виджетов можно добавлять медиа файлы (css и javascript) для более глубокой настройки их внешнего вида и поведения.
Вкратце, вам потребуется унаследовать виджет и либо определить класс “Media”, либо создать свойство “media”, возвращающее экземпляр этого класса.
Эти методы требуют некоторого объёма продвинутого кода и подробно описаны в руководстве по ресурсам форм.
Основные классы виджетов Widget и MultiWidget унаследованы всеми встроенными виджетами и могут являться основой для ваших собственных виджетов.
Абстрактный класс не может быть использован для отображения поля, но он предоставляет основной атрибут attrs. Вы также можете реализовать или переопределить метод render() в своём виджете.
Словарь, которые содержит HTML атрибуты, которые будут назначены сгенерированному виджету.
>>> from django import forms
>>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name',})
>>> name.render('name', 'A name')
'<input title="Your name" type="text" name="name" value="A name" size="10" />'
Если вы укажите True или False атрибуту, он будет отрендерен как HTML5 булев атрибут:
>>> name = forms.TextInput(attrs={'required': True})
>>> name.render('name', 'A name')
'<input name="name" type="text" value="A name" required />'
>>>
>>> name = forms.TextInput(attrs={'required': False})
>>> name.render('name', 'A name')
'<input name="name" type="text" value="A name" />'
Атрибут по умолчанию равен True. При False микросекунды объекта datetime и time будут сброшены в 0.
В предыдущих версиях этот атрибут был доступен только для виджетов даты и времени (по умолчанию False).
Возвращает HTML ID атрибут виджета, который можно использовать для <label>, принимая ID поля. Возвращает None, если ID не доступен.
Этот метод необходим т.к. некоторые виджеты состоят из нескольких HTML элеентов с разными ID. В этом случает метод должен вернуть ID первого тега виджета.
Возвращает HTML для виджета в виде строки Unicode. Этот метод должен быть реализован в дочерних классах. В противном случае будет выброшено исключение NotImplementedError.
Никто не гарантирует, что полученное значение будет правильным, поэтому реализация метода в дочерних классах должна обеспечивать соответствующую проверку.
Принимает словарь с данными и имя виджета. files может содержать данные из request.FILES. Возвращает None, если значение не найдено. Обратите внимание, value_from_datadict может вызываться несколько раз при обработке данных в форме. Если вы добавите медленные операции в этот метод, позаботьтесь о кешировании результата.
Виджет, который состоит из множества виджетов. Класс MultiWidget предназначен для поля MultiValueField.
Класс MultiWidget имеет один обязательный аргумент:
Итератор, содержащий необходимые виджеты.
И один обязательный метод:
Этот метод принимает единственное “сжато” значение от поля и возвращает список “распакованных” значений. Введённое значение может считаться верным, но не обязательно не пустым.
Этот метод должен быть реализован в дочернем классе и, так как значение может быть пустым, реализация должна проверять этот момент.
Наличие “распаковки” объясняется необходимостью “разделить” объединённое значение поля формы на значения для каждого виджета.
Пример того как SplitDateTimeWidget преобразовывает значение datetime в список с датой и временем:
from django.forms import MultiWidget
class SplitDateTimeWidget(MultiWidget):
# ...
def decompress(self, value):
if value:
return [value.date(), value.time().replace(microsecond=0)]
return [None, None]
Совет
Следует отметить, что MultiValueField обладает дополнительным методом compress() с обратной функциональностью – объединять проверенные значения всех элементов поля в единое значение.
Список других методов, которые может быть полезно переопределить:
Аргумент value обрабатывается по-другому в этом методе в отличие от дочерних классов Widget, потому что он должен знать как именно разделять единое значение для отображения во множестве виджетов.
Аргумент value, используемый при генерации, может быть одним из:
Список (list).
Единственное значение (т.е., строка), которая является “сжатым” представлением списка значений.
Если value является списком, результатом метода render() будет совокупность отрендеренных виджетов. Если value не является списком, то сначала оно будет обработано методом decompress() для получения списка и затем выполнится рендеринг.
При работе метода render() каждому значению в списке назначается соответствующий виджет. Первое значение значение назначается первому виджету, второе – второму и так далее.
В отличие от виджетов с единственным значением, метод render() не обязательно должен быть реализован в дочерних классах.
Переданный список отрендеренных виджетов (в виде строки), возвращает строку Unicode, представляющую HTML код для всего этого.
Этот обработчик позволяет вам форматировать HTML код виджетов в нужном вам виде.
Ниже приведён виджет унаследован от MultiWidget и подходит для отображения даты, разделяя день, месяц и год по различным элементам. Этот виджет предназначен для использования совместно с DateField вместо MultiValueField, следовательно мы должны реализовать метод value_from_datadict():
from datetime import date
from django.forms import widgets
class DateSelectorWidget(widgets.MultiWidget):
def __init__(self, attrs=None):
# create choices for days, months, years
# example below, the rest snipped for brevity.
years = [(year, year) for year in (2011, 2012, 2013)]
_widgets = (
widgets.Select(attrs=attrs, choices=days),
widgets.Select(attrs=attrs, choices=months),
widgets.Select(attrs=attrs, choices=years),
)
super(DateSelectorWidget, self).__init__(_widgets, attrs)
def decompress(self, value):
if value:
return [value.day, value.month, value.year]
return [None, None, None]
def format_output(self, rendered_widgets):
return ''.join(rendered_widgets)
def value_from_datadict(self, data, files, name):
datelist = [
widget.value_from_datadict(data, files, name + '_%s' % i)
for i, widget in enumerate(self.widgets)]
try:
D = date(
day=int(datelist[0]),
month=int(datelist[1]),
year=int(datelist[2]),
)
except ValueError:
return ''
else:
return str(D)
Конструктор создаёт кортеж из нескольких виджетов Select. Класс, от которого был унаследован виджет, использует этот кортеж для настройки виджета.
Метод format_output() не особо нужен здесь (действительно, он похож на стандартную реализацию этого метода в MultiWidget), но идея в том, что вы можете в этой точке можете сделать нужную настройку виджетов.
Обязательный метод decompress() разбивает значение datetime.date на значение дня, месяца и года для каждого виджета. Следует отметить, что метод обрабатывает случай, когда value равно None.
Стандартная реализация метода value_from_datadict() возвращает список значений для каждого Widget. Это полезно при использовании MultiWidget совместно с MultiValueField, но так как мы желаем использовать этот виджет совместно с DateField, который принимает единственное значение, мы переопределили этот метод для соединения данных всех подчинённых виджетов в datetime.date. Метод получает данные из словаря POST, создаёт и проверяет дату. Если она проходит проверку, мы возвращаем строку, в противном случае возвращаем пустую строку, что заставляет form.is_valid вернуть False.
Django с помощью модуля django.forms.widgets обеспечивает представление для всех базовых HTML виджетов, а также некоторые часто используемые группы виджетов, включая виджеты для ввода текста, различные чекбоксы и селекторы, загрузку файлов и обработку сложных значений.
Эти виджеты используют HTML элементы input и textarea.
Ввод даты в простое текстовое поле: <input type='text' ...>
Принимает аргументы, аналогичные TextInput, лишь с одним необязательным аргументом:
Формат, в котором отображается начальное значение поля.
Если аргумент format не предоставлен, то стандартный формат берется из DATE_INPUT_FORMATS с учетом Формат локализации.
Ввод даты/времени в простое текстовое поле: <input type='text' ...>
Принимает аргументы, аналогичные TextInput, лишь с одним необязательным аргументом:
Формат, в котором отображается начальное значение поля.
Если аргумент format не предоставлен, то стандартный формат берется из DATETIME_INPUT_FORMATS с учетом Формат локализации.
По умолчанию микросекунды значения всегда устанавливаются в 0. Если микросекунды необходимы, наследуйтесь от этого класса и установите атрибут supports_microseconds в True.
Ввод времени в простое текстовое поле: <input type='text' ...>
Принимает аргументы, аналогичные TextInput, лишь с одним необязательным аргументом:
Формат, в котором отображается начальное значение поля.
Если аргумент format не предоставлен, то стандартный формат берется из TIME_INPUT_FORMATS с учетом Формат локализации.
Подробности об обработке микросекунд смотрите в описании DateTimeInput.
Аналогично Select, но отображается в виде списка радио кнопок с помощью тегов <li>:
<ul>
<li><input type='radio' name='...'></li>
...
</ul>
Для более тонкого управления процессом генерации HTML кода, вы можете выводить радио кнопки в шаблон в цикле. Рассмотрим форму myform с полем beatles, которое использует RadioSelect в качестве виджета:
{% for radio in myform.beatles %}
<div class="myradio">
{{ radio }}
</div>
{% endfor %}
Она будет представлена в виде следующего HTML кода:
<div class="myradio">
<label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" /> John</label>
</div>
<div class="myradio">
<label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" /> Paul</label>
</div>
<div class="myradio">
<label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" /> George</label>
</div>
<div class="myradio">
<label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" /> Ringo</label>
</div>
Код содержит теги <label>. Также вы можете использовать атрибуты tag, choice_label и id_for_label для управления отображением каждой радио кнопки. Например, этот шаблон...
{% for radio in myform.beatles %}
<label for="{{ radio.id_for_label }}">
{{ radio.choice_label }}
<span class="radio">{{ radio.tag }}</span>
</label>
{% endfor %}
... преобразуется в следующий HTML:
<label for="id_beatles_0">
John
<span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" /></span>
</label>
<label for="id_beatles_1">
Paul
<span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" /></span>
</label>
<label for="id_beatles_2">
George
<span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" /></span>
</label>
<label for="id_beatles_3">
Ringo
<span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" /></span>
</label>
Если вы просто выведите поле в шаблоне с помощью {{ myform.beatles }}, то кнопки будут выведены с помощью тега <ul> с <li>, как было показано ранее.
Контейнер <ul> получает атрибут id, указанный в виджете.
При генерации радио кнопок теги label and input содержат атрибуты for и id соответственно. Каждая радио кнопка использует атрибут id_for_label для генерации ID элемента.
Аналогичен SelectMultiple, но отображается в виде списка чекбоксов.
<ul>
<li><input type='checkbox' name='...' ></li>
...
</ul>
Контейнер <ul> получает атрибут id, указанный в виджете.
Как и для RadioSelect, теперь можно использовать цикл по чекбоксам. Смотрите описание RadioSelect.
При генерации чекбоксов теги label and input содержат атрибуты for и id соответственно. Каждый чекбокс использует атрибут id_for_label для генерации ID элемента.
Обёртка (MultiWidget с помощью) вокруг двух виджетов: DateInput для даты и TimeInput для времени.
SplitDateTimeWidget имеет два необязательных атрибута:
Аналогичен DateInput.format.
Аналогичен TimeInput.format.
Обёртка вокруг трёх виджетов Select – месяц, день и год.
Принимает несколько необязательных аргументов:
Необязательный список/кортеж с вариантами года. По умолчанию содержит текущий год и девять последующих.
Необязательный словарь списка месяцев.
Ключ словаря соответствует номеру месяца (начиная с 1), значения – отображаемое название:
MONTHS = {
1:_('jan'), 2:_('feb'), 3:_('mar'), 4:_('apr'),
5:_('may'), 6:_('jun'), 7:_('jul'), 8:_('aug'),
9:_('sep'), 10:_('oct'), 11:_('nov'), 12:_('dec')
}
Если поле DateField не обязательно, SelectDateWidget будет содержать пустое значение в начале списка (по умолчанию ---). Вы можете поменять название элемента с помощью атрибута empty_label. empty_label принимает string, list, или tuple. Если указана строка, каждый <select> будет содержать пустое значение. Если empty_label содержит list или tuple из 3-х строк – для каждого <select> будет использоваться свое значение. Элементы используются в следующем порядке: ('year_label', 'month_label', 'day_label').
# A custom empty label with string
field1 = forms.DateField(widget=SelectDateWidget(empty_label="Nothing"))
# A custom empty label with tuple
field1 = forms.DateField(
widget=SelectDateWidget(
empty_label=("Choose Year", "Choose Month", "Choose Day"),
),
)
Этот виджет раньше находился в пакете django.forms.extras.widgets. Теперь находится в django.forms.widgets и, как и другие виджеты, может быть импортирован из django.forms.
Mar 31, 2016