ウィジェットは、Django が HTML の input 要素の表現方法です。ウィジェットは、HTML のレンダリングをコントロールして、ウィジェットに合致する GET/POST ディクショナリからデータを取り出します。
ちなみに
ウィジェットを form fields と混同しないでください。フォームフィールドは入力値の検証ロジックを扱い、テンプレート内で直接使用されます。ウィジェットはウェブページ上で input 要素から HTML の form をレンダリングし、submit された生データを取り出します。ウィジェットはフォームフィールドにアサイン (assigned) される必要があります。
フォーム上でフィールドを指定したときは、Django は描画されるデータのタイプに適したデフォルトのウィジェットを使用します。各フィールドで使われるウィジェットを調べるためには、 ビルトインの Field クラス をご覧ください。
フィールドに異なるウィジェットを使いたい場合は、フィールドを定義するときに widget
引数を使うことができます。例えば:
from django import forms
class CommentForm(forms.Form):
name = forms.CharField()
url = forms.URLField()
comment = forms.CharField(widget=forms.Textarea)
これは、comment のフォームに対して、デフォルトの TextInput
ウィジェットではなく、より大きなサイズの Textarea
ウィジェットを指定しています。
多くのウィジェットは、省略可能な追加の引数を持っています; これらは、フィールド上でウィジェットを定義する際にセットできます。以下の例では、SelectDateWidget
に対して years
属性がセットされます:
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
ウィジェットを継承したウィジェットは、選択肢を扱います。これらはユーザーに選択肢のリストを提示します。提示される選択肢はウィジェットによって異なります; Select
ウィジェット自体は、<select>
HTML のリスト表現を使い、一方で RadioSelect
はラジオボタンを使います。
Select
ウィジェットは、 ChoiceField
フィールド上でデフォルトで使われます。
>>> 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 としてウィジェットをレンダリングするとき、最低限のマークアップだけをレンダリングします - Django はクラスの名前や、他のあらゆるウィジェット特有の属性を追加しません。これは、例えば、すべての TextInput
ウィジェットはウェブページ上で同じに表示されることを意味します。
ウィジェットをカスタマイズする方法には 2 つあります: ウィジェットごとのインスタンス と ウィジェットごとのクラス です。
1 つのウィジェットのインスタンスを他と異なる見た目にしたい場合、ウィジェットのオブジェクトをインスタンス化してフォームフィールドに割り当てるタイミングで、追加の属性を指定する必要があります (そしておそらく、あなたの CSS ファイルにいくつか記述を追加する必要もあります)。
例えば、以下のサンプルフォームを見てください:
from django import forms
class CommentForm(forms.Form):
name = forms.CharField()
url = forms.URLField()
comment = forms.CharField()
このフォームは、デフォルトのレンダリングとともに、3 つのデフォルトの TextInput
ウィジェットを含みます – CSS のクラスも追加の属性もありません。これは、それぞれのウィジェットに対して提供された input ボックスが、以下とまったく同じくレンダリングされることを意味します。
>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" required /></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required /></td></tr>
実際のウェブページでは、全てのウィジェットを同じ見た目にしたいことはあまりありません。コメントに対しては大きめの input 要素にしたいでしょうし、’名前’ のウィジェットには特別な CSS クラスを適用したいでしょう。新しい HTML5 の input のタイプを利用するために、’type’ 属性を指定することも可能です。これらを実現するためには、ウィジェットを作成するときに 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 はこれで、レンダリングされたアウトプットに、追加的な要素を含むようになります:
>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" class="special" required /></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" size="40" required /></td></tr>
attrs
を使った HTML の id
をセットすることもできます。BoundField.id_for_label
で例をご覧ください。
ウィジェットとともに、アセット (css
や javascript
) 、およびより詳細にカスタマイズされた見た目や動作を追加することができます。
要するに、ウィジェットをサブクラス化して、 “Media” 内部クラスの定義 か “media” プロパティの作成 のどちらかをする必要があります。
これらのメソッドにはやや高度なPythonプログラミングが含まれており、トピックガイド Form Assets で詳しく説明しています。
Widget
や MultiWidget
といった基本ウィジェットは、ビルトインのウィジェット によってサブクラス化され、カスタムウィジェットのための基礎となります。
ウィジェット
¶Widget
(attrs=None)[ソース]¶この抽象クラスはレンダリングできませんが、基本的な属性 render()
を実行するかオーバーライドできます。
attrs
¶ディクショナリは、レンダリングされたウィジェット上にセットされる 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" required />'
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" />'
supports_microseconds
¶True
をデフォルト値にする属性です。False
にセットされた場合は、datetime
と time
のマイクロ秒の部分の値は、0
にセットされます。
古いバージョンでは、この属性は日付と時間のウィジェットにおいてのみ (False
として) 定義されていました。
format_value
(value)¶ウィジェットのテンプレートで使うための値を整えて返します。value
は入力値が検証されるとは限りません。そのため、サブクラスの実行は防衛的にプログラムされなければなりません。
古いバージョンでは、このメソッドは _format_value()
と名付けられたプライベートな API でした。この古い名前は、Django 2.0 までは動く予定です。
id_for_label
(self, id_)[ソース]¶このウィジェットのフィールドの ID が付与された <label>
で使われるための HTML の ID 属性を返します。 IDが有効でない場合は None
を返します。
いくつかのウィジェットは複数の HTML 要素、そして、複数の ID を持っているため、このフックが必要です。この場合、このメソッドは、ウィジェットのタグの最初の ID と一致する ID 値を返す必要があります。
render
(name, value, attrs=None)[ソース]¶ウィジェットに対する HTML を、Unicode 文字列として返します。このメソッドは、サブクラスによって実行されなければなりません。でなければ、NotImplementedError
が投げられます。
与えられた ‘value’ は、入力が検証されるとは限りません。そのため、サブクラスの実行は防衛的にプログラムされる必要があります。
value_from_datadict
(data, files, name)[ソース]¶データとこのウィジェットの名前のディクショナリが与えられ、このウィジェットの値を返します。files
には request.FILES
からのデータが含まれている可能性があります。値が指定されなかった場合は None
を返します。 また、value_from_datadict
はフォームデータの処理中に複数回呼び出される可能性があるので、カスタマイズして複雑な処理を追加する場合は、自分でキャッシュの仕組みを実装する必要があります。
value_omitted_from_data
(data, files, name)[ソース]¶data
と files
のディクショナリとこのウィジェットの名前が与えられ、ウィジェットのためのデータやファイルが存在するかを返します。
メソッドの結果は、モデルフォームのフィールドが デフォルトに逆戻りする かどうかに影響します。
Special cases are CheckboxInput
,
CheckboxSelectMultiple
, and
SelectMultiple
, which always return
False
because an unchecked checkbox and unselected
<select multiple>
don’t appear in the data of an HTML form
submission, so it’s unknown whether or not the user submitted a value.
use_required_attribute
(initial)[ソース]¶フォームフィールドの 初期の
値が与えられ、ウィジェットが 必要な
HTML 属性とともにレンダリングできるかどうかを返します。フォームは、各フィールドに 必要な
属性を描画するかどうかを決定するために、Field.required
と Form.use_required_attribute
とともにこのメソッドを使います。
デフォルトでは、hidden のウィジェットには Flase
を、それ以外には True
を返します。特別な場合は、initial
がセットされていないとき False
を返す ClearableFileInput
と、ブラウザの検証が最低 1 つではなく全チェックボックスがチェックされていることを要求するため常に False
を返す CheckboxSelectMultiple
です。
ブラウザの検証と互換性のないカスタムウィジェットでは、このメソッドをオーバーライドしてください。例えば、ある非表示の textarea
要素が背後にある WSYSIWG テキストエディタのウィジェットは、ブラウザが非表示のフィールドを検証するのを避けるため、常に False
を返したがるかもしれません。
MultiWidget
¶MultiWidget
(widgets, attrs=None)[ソース]¶複数のウィジェットで構成されたウィジェットです。MultiWidget
は MultiValueField
と協調して動作します。
MultiWidget
には 1 つの必要な引数があります。
widgets
¶必要なウィジェットを含む反復可能なものです。
それと、1 つの必要なメソッドです:
decompress
(value)[ソース]¶このメソッドは、フィールドから単一の “圧縮された” 値を取り、”解凍された” 値のリストを返します。入力された値は検証済みと見なせますが、空 (empty)でないとは限りません。
このメソッドは、サブクラスによって 実行される必要があり、値が空 (empty) かもしれないので、処理は防衛的である必要があります。
“解凍” の裏にある根本的な原理は、フォームのフィールドから各ウィジェットの値に、結合された値を “分割する” 必要があることです。
以下は、SplitDateTimeWidget
が どのように SplitDateTimeWidget
の値を 2 つの分割された値に日付や時刻とともにリストに入れるかの例です:
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
が、正反対の責務 - 全メンバーフィールドの整えられた値を 1 つにまとめること - を持つ補完メソッド compress()
を持っていることを覚えておいてください。
オーバーライドに役立つ可能性がある他のメソッドは以下の通りです:
render
(name, value, attrs=None)[ソース]¶引数 value
は、このメソッド内では Widget
のサブクラスとは異なった方法で扱われます。なぜならば、単一の値を複数のウィジェット内で表示するためにどのように分割するかを明確にする必要があるからです。
レンダリングのときにつかわれる value
引数は、以下の 2 つのうちの 1 つです:
リスト
単一の値 (例: 単一の文字列) で、値の リスト
の “圧縮された” 表現
value
がリストの場合、render()
のアウトプットはリンダリングされた子ウィジェットの連鎖です。value
がリストではない場合、まずリストを作るために decompress()
メソッドにより計算され、それからレンダリングされます。
render()
が HTML レンダリングを実施するとき、リスト内の各値は適切なウィジェットともにレンダリングされます – 最初の値は最初のウィジェット内でレンダリングされ、2 番目の値は 2 番目のウィジェット内で描画されます。以降同様です。
単一の値のウィジェットとは異なり、メソッド render()
はサブクラスで実行される必要はありません。
format_output
(rendered_widgets)[ソース]¶レンダリングされた (文字列としての) ウィジェットのリストが与えられ、単体のロットのために HTML を表す Unicode 文字列を返します。
このフックは、あなたが好むあらゆる方法でウィジェットの HTML デザインをフォーマットすることを可能にします。
異なるセレクトボックス内で MultiWidget
を日、月、年とともに日付を表示するためにサブクラス化するウィジェットの例です。このウィジェットは MultiValueField
ではなく DateField
とともに使われることを意図しています。そして、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
ウィジェットを作成します。super
クラスは、このタプルをウィジェットをセットアップするために使います。
format_output()
メソッドはここではとても平凡ですが (実際、MultiWidget
に対してデフォルトで実施されるものと同じです)、ウィジェットの間にカスタム HTML を追加することができます。
必要なメソッド decompress()
は datetime.date
の値を各ウィジェットに対応する日、月、年の値に分解します。メソッドが、 value
が None
のケースをどのように扱うか覚えておいてください。
value_from_datadict()
のデフォルトの処理は、各 ウィジェット
に一致する値のリストを返します。MultiWidget
を MultiValueField
とともに使うときには適していますが、このウィジェットを単一の値を取る class:~django.forms.DateField とともに使いたいので、サブウィジェットのデータを datetime.date
にまとめるようメソッドはオーバーライドされています。メソッドは POST
ディクショナリからデータを展開し構成して、日付を検証します。値が適正な場合、文字列を返します。適正でなければ、 form.is_valid
に False
を返させるための空の文字列を返します。
Django は、全ての基本的な HTML ウィジェットの表現のほか、django.forms.widgets
でいくつかの一般的に使われるウィジェットのグループを提供します。これは テキストの入力、多種のチェックボックスおよび選択肢、ファイルアップロード、複数値の入力の扱い を含みます。
これらのウィジェットは、 input
と textarea
の HTML 要素を使います。
NumberInput
¶PasswordInput
¶DateInput
¶DateInput
[ソース]¶シンプルなテキストボックスの日付 input: <input type='text' ...>
TextInput
と同じ引数を取り、さらに 1 つ省略可能な引数があります:
format
¶このフィールドの初期値が描画されるフォーマットです。
format
引数が渡されないとき、デフォルトのフォーマットは DATE_INPUT_FORMATS
内で最初に見つかったフォーマットで、表示形式のローカル化 を尊重します。
DateTimeInput
¶DateTimeInput
[ソース]¶シンプルなテキストボックスの日付と時刻の input: <input type='text' ...>
TextInput
と同じ引数を取り、さらに 1 つ省略可能な引数があります:
format
¶このフィールドの初期値が描画されるフォーマットです。
format
引数が渡されないとき、デフォルトのフォーマットは DATETIME_INPUT_FORMATS
内で最初に見つかったフォーマットで、表示形式のローカル化 を尊重します。
デフォルトでは、時刻のマイクロ秒部分は常に 0
にセットされます。マイクロ秒が必要な場合は、サブクラスで supports_microseconds
属性を True
にセットして使ってください。
TimeInput
¶TimeInput
[ソース]¶シンプルなテキストボックスの時刻 input: <input type='text' ...>
TextInput
と同じ引数を取り、さらに 1 つ省略可能な引数があります:
format
¶このフィールドの初期値が描画されるフォーマットです。
format
引数が渡されないとき、デフォルトのフォーマットは TIME_INPUT_FORMATS
内で最初に見つかったフォーマットで、表示形式のローカル化 を尊重します。
マイクロ秒の扱いについては、DateTimeInput
を参照してください。
CheckboxInput
¶Select
¶SelectMultiple
¶RadioSelect
¶RadioSelect
[ソース]¶Select`と似ているが ``<li>`
タグでラジオボランのリストとして表示:
<ul>
<li><input type='radio' name='...'></li>
...
</ul>
For more granular control over the generated markup, you can loop over the
radio buttons in the template. Assuming a form myform
with a field
beatles
that uses a RadioSelect
as its widget:
{% for radio in myform.beatles %}
<div class="myradio">
{{ radio }}
</div>
{% endfor %}
This would generate the following HTML:
<div class="myradio">
<label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" required /> John</label>
</div>
<div class="myradio">
<label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required /> Paul</label>
</div>
<div class="myradio">
<label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" required /> George</label>
</div>
<div class="myradio">
<label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required /> Ringo</label>
</div>
That included the <label>
tags. To get more granular, you can use each
radio button’s tag
, choice_label
and id_for_label
attributes.
For example, this template...
{% for radio in myform.beatles %}
<label for="{{ radio.id_for_label }}">
{{ radio.choice_label }}
<span class="radio">{{ radio.tag }}</span>
</label>
{% endfor %}
...will result in the following HTML:
<label for="id_beatles_0">
John
<span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" required /></span>
</label>
<label for="id_beatles_1">
Paul
<span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required /></span>
</label>
<label for="id_beatles_2">
George
<span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" required /></span>
</label>
<label for="id_beatles_3">
Ringo
<span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required /></span>
</label>
If you decide not to loop over the radio buttons – e.g., if your template
simply includes {{ myform.beatles }}
– they’ll be output in a <ul>
with <li>
tags, as above.
The outer <ul>
container receives the id
attribute of the widget,
if defined, or BoundField.auto_id
otherwise.
When looping over the radio buttons, the label
and input
tags include
for
and id
attributes, respectively. Each radio button has an
id_for_label
attribute to output the element’s ID.
CheckboxSelectMultiple
¶CheckboxSelectMultiple
[ソース]¶Similar to SelectMultiple
, but rendered as a list of check
buttons:
<ul>
<li><input type='checkbox' name='...' ></li>
...
</ul>
The outer <ul>
container receives the id
attribute of the widget,
if defined, or BoundField.auto_id
otherwise.
Like RadioSelect
, you can loop over the individual checkboxes for the
widget’s choices. Unlike RadioSelect
, the checkboxes won’t include the
required
HTML attribute if the field is required because browser validation
would require all checkboxes to be checked instead of at least one.
When looping over the checkboxes, the label
and input
tags include
for
and id
attributes, respectively. Each checkbox has an
id_for_label
attribute to output the element’s ID.
SplitDateTimeWidget
¶SplitDateTimeWidget
[ソース]¶Wrapper (using MultiWidget
) around two widgets: DateInput
for the date, and TimeInput
for the time. Must be used with
SplitDateTimeField
rather than DateTimeField
.
SplitDateTimeWidget
has two optional attributes:
date_format
¶attr:DateInput.format と同様。
time_format
¶TimeInput.format
と同様
SelectDateWidget
¶SelectDateWidget
[ソース]¶Wrapper around three Select
widgets: one each for
month, day, and year.
Takes several optional arguments:
years
¶An optional list/tuple of years to use in the “year” select box. The default is a list containing the current year and the next 9 years.
months
¶An optional dict of months to use in the “months” select box.
The keys of the dict correspond to the month number (1-indexed) and the values are the displayed months:
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')
}
empty_label
¶If the DateField
is not required,
SelectDateWidget
will have an empty choice at the top of the
list (which is ---
by default). You can change the text of this
label with the empty_label
attribute. empty_label
can be a
string
, list
, or tuple
. When a string is used, all select
boxes will each have an empty choice with this label. If empty_label
is a list
or tuple
of 3 string elements, the select boxes will
have their own custom label. The labels should be in this order
('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"),
),
)
This widget used to be located in the django.forms.extras.widgets
package. It is now defined in django.forms.widgets
and like the
other widgets it can be imported directly from django.forms
.
4月 04, 2017