==============
ウィジェット
==============

:revision-up-to: 17812 (1.4) unfinished

.. module:: django.forms.widgets
   :synopsis: Django の組み込みフォームウィジェットです。

.. currentmodule:: django.forms

ウィジェットとは、Django で HTML の入力エレメントを表現するためのオブジェク
トです。ウィジェットは、 HTML のレンダリングや、個々のウィジェットに対応す
るデータをGET/POST 辞書から抽出する処理を行います。

ウィジェットの指定
------------------

フォームに何らかのフィールドを作成する場合、 Django は表示するデータの型に
応じて適切なデフォルトのウィジェットを使います。どのフィールドがどのウィ
ジェットを使っているかは、 :ref:`組み込みフィールドクラス <built-in fields>`
のドキュメントを参照してください。

とはいえ、デフォルトとは違うウィジェットを使いたい場合もあるでしょう。その
場合には、以下の例のように、フィールドを定義する際に :attr:`~Field.widget`
引数を指定します::

    from django import forms

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = forms.CharField(widget=forms.Textarea)

上のコードでは、 comment フィールドにデフォルトの :class:`TextInput` ウィジェッ
トではなく、より大きな :class:`Textarea` ウィジェットを使うように指定しています。


.. Setting arguments for widgets
   -----------------------------

ウィジェットに引数を設定する
----------------------------

.. Many widgets have optional extra arguments; they can be set when defining the
   widget on the field. In the following example, the
   :attr:`~SelectDateWidget.years` attribute is set for a
   :class:`~django.forms.extras.widgets.SelectDateWidget`::

多くのウィジェットにはオプションの追加引数があり、それらはフィールドの
ウィジェットを定義する際に設定できます。次の例では、
:attr:`~SelectDateWidget.years` 属性が
:class:`~django.forms.extras.widgets.SelectDateWidget` に設定されます::

    from django.forms.fields import DateField, ChoiceField, MultipleChoiceField
    from django.forms.widgets import RadioSelect, CheckboxSelectMultiple
    from django.forms.extras.widgets import SelectDateWidget

    BIRTH_YEAR_CHOICES = ('1980', '1981', '1982')
    GENDER_CHOICES = (('m', 'Male'), ('f', 'Female'))
    FAVORITE_COLORS_CHOICES = (('blue', 'Blue'),
                                ('green', 'Green'),
                                ('black', 'Black'))

    class SimpleForm(forms.Form):
        birth_year = DateField(widget=SelectDateWidget(years=BIRTH_YEAR_CHOICES))
        gender = ChoiceField(widget=RadioSelect, choices=GENDER_CHOICES)
        favorite_colors = forms.MultipleChoiceField(required=False,
            widget=CheckboxSelectMultiple, choices=FAVORITE_COLORS_CHOICES)

.. See the :ref:`built-in widgets` for more information about which widgets
   are available and which arguments they accept.

どのようなウィジェットが利用可能で、それらがどの引数を受け付けるかについては、
:ref:`built-in widgets` を参照してください。


.. Widgets inheriting from the Select widget
   -----------------------------------------

Select ウィジェットを継承するウィジェット
-----------------------------------------

.. Widgets inheriting from the :class:`Select` widget deal with choices. They
   present the user with a list of options to choose from. The different widgets
   present this choice differently; the :class:`Select` widget itself uses a
   ``<select>`` HTML list representation, while :class:`RadioSelect` uses radio
   buttons.

:class:`Select` ウィジェットを継承するウィジェットは選択肢を扱います。これらは
選ぶことのできるオプション一覧をユーザに提示します。ウィジェットによって
オプション一覧の提示方法は異なります。 :class:`Select` ウィジェットは HTML の
``<select>`` を、 :class:`RadioSelect` はラジオボタンを使う、という具合です。

.. :class:`Select` widgets are used by default on :class:`ChoiceField` fields. The
   choices displayed on the widget are inherited from the :class:`ChoiceField` and
   changing :attr:`ChoiceField.choices` will update :attr:`Select.choices`. For
   example::

:class:`Select` ウィジェットはデフォルトで :class:`ChoiceField` フィールド
によって使われます。このウィジェットは表示する選択肢を :class:`ChoiceField`
から継承しており、 :attr:`ChoiceField.choices` を変更すると
:attr:`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')]

.. Widgets which offer a :attr:`~Select.choices` attribute can however be used
   with fields which are not based on choice -- such as a :class:`CharField` --
   but it is recommended to use a :class:`ChoiceField`-based field when the
   choices are inherent to the model and not just the representational widget.

:attr:`~Select.choices` 属性を持つウィジェットは、実は選択肢を扱わないフィールド
-- 例えば :class:`CharField` -- に対して使うことも可能ですが、本質的にその
選択肢がモデル由来であり、かつ表示目的だけのウィジェットでもないならば、
:class:`ChoiceField` ベースのフィールドに対して使うことを推奨します。

ウィジェットインスタンスのカスタマイズ
--------------------------------------

ウィジェットを HTML としてレンダリングする際、 Django は最小限の HTML しか
出力しません。すなわち、クラス定義やウィジェット固有の属性は一切付加しない
のです。従って、例えばページ上にまったく同じ見栄えの :class:`TextInput`
ウィジェットが並ぶわけです。

ウィジェットごとに見栄えを変えたいのなら、各々のウィジェットに属性を指定し
てやる必要があります。ウィジェットを指定するときに、レンダリング後の HTML
に付加したい属性のリストを指定できます。

例えば、以下のような簡単なフォームを考えましょう::

    from django import forms

    class CommentForm(forms.Form):
        name = forms.CharField()
        url = forms.URLField()
        comment = forms.CharField()

このフォームは 3 つの :class:`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="text" name="url"/></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>

現実の Web ページでは、全ウィジェットが同じに見えるような見栄えを期待しない
でしょう。コメント欄をもうちょっと大きな入力ボックスにしたかったり、
``'name'`` ウィジェットに特別な CSS クラスを指定したかったりするかもしれま
せん。そうするには、ウィジェット作成時に :attr:`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"/></td></tr>
    <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
    <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>

.. _built-in widgets:

組み込みウィジェット
--------------------

Django は、基本的な HTML ウィジェットすべてと、よく使われるウィジェットグルー
プを提供しています:

``Widget``
~~~~~~~~~~

.. class:: Widget

    .. This abstract class cannot be rendered, but provides the basic attribute :attr:`~Widget.attrs`.

    この抽象クラスはレンダリングできませんが、基本の属性 :attr:`~Widget.attrs`
    を提供します。

    .. attribute:: Widget.attrs

        .. A dictionary containing HTML attributes to be set on the rendered widget.

        レンダリングされるウィジェットに設定される HTML 属性を含んだ辞書です。

        .. code-block:: python

            >>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name',})
            >>> name.render('name', 'A name')
            u'<input title="Your name" type="text" name="name" value="A name" size="10" />'

``TextInput``
~~~~~~~~~~~~~

.. class:: TextInput

    テキスト入力: ``<input type='text' ...>`` です。

``PasswordInput``
~~~~~~~~~~~~~~~~~

.. class:: PasswordInput

    パスワードテキスト入力: ``<input type='password' ...>`` です。

    .. Takes one optional argument:

    オプションの引数を一つ取ります。

    .. attribute:: PasswordInput.render_value

        .. Determines whether the widget will have a value filled in when the
           form is re-displayed after a validation error (default is ``False``).

        検証エラー後にウィジェットが再表示される際、値が記入されるかどうかを
        決定します (デフォルトは ``False`` です)。

        .. .. versionchanged:: 1.3
               The default value for
               :attr:`~PasswordInput.render_value` was
               changed from ``True`` to ``False``

        .. versionchanged:: 1.3
            :attr:`~PasswordInput.render_value` のデフォルト値は ``True`` から
            ``False`` に変更されました。

``HiddenInput``
~~~~~~~~~~~~~~~

.. class:: HiddenInput

    hidden ウィジェット: ``<input type='hidden' ...>`` です。

``MultipleHiddenInput``
~~~~~~~~~~~~~~~~~~~~~~~

.. class:: MultipleHiddenInput

    複数の hidden ウィジェット: ``<input type='hidden' ...>`` です。

    .. A widget that handles multiple hidden widgets for fields that have a list
       of values.

    複数の値を持つフィールド用に、複数の hidden ウィジェットを使うウィジェット
    です。

    .. attribute:: MultipleHiddenInput.choices

        .. This attribute is optional when the field does not have a
           :attr:`~Field.choices` attribute. If it does, it will override anything
           you set here when the attribute is updated on the :class:`Field`.

        この属性は、フィールドに :attr:`~Field.choices` 属性が無い場合には
        指定する必要はありません。もし属性がある場合、 :class:`Field` で
        `choices` 属性が更新されると、ここでの指定は上書きされます。

``FileInput``
~~~~~~~~~~~~~

.. class:: FileInput

    ファイルアップロード: ``<input type='file' ...>`` です。

``ClearableFileInput``
~~~~~~~~~~~~~~~~~~~~~~

.. class:: ClearableFileInput

    .. versionadded:: 1.3

    .. File upload input: ``<input type='file' ...>``, with an additional checkbox
       input to clear the field's value, if the field is not required and has
       initial data.

    フィールドが入力必須ではなく、かつ初期データがある場合に、フィールドの値を
    クリアするためのチェックボックスを備えたファイルアップロード入力:
    ``<input type='file' ...>`` です。

``DateInput``
~~~~~~~~~~~~~

.. class:: DateInput

    .. Date input as a simple text box: ``<input type='text' ...>``

    単純なテキストボックスで表現された、日付用の入力ウィジェット:
    ``<input type='text' ...>``  です。

    .. Takes one optional argument:

    オプションの引数を一つ取ります:

    .. attribute:: DateInput.format

        .. The format in which this field's initial value will be displayed.

        フィールド初期値の表示に使う書式。

    .. If no ``format`` argument is provided, the default format is the first
       format found in :setting:`DATE_INPUT_FORMATS` and respects
       :ref:`format-localization`.

    ``format`` 引数が指定されない場合、デフォルトの書式は
    :setting:`DATE_INPUT_FORMATS` で最初に見つかった書式になり、かつ
    :ref:`format-localization` が適用されます。

``DateTimeInput``
~~~~~~~~~~~~~~~~~

.. class:: DateTimeInput

    単純なテキストボックスで表現された、日付／時刻用の入力ウィジェット:
    ``<input type='text' ...>`` です。

    .. Takes one optional argument:

    オプションの引数を一つ取ります:

    .. attribute:: DateTimeInput.format

        .. The format in which this field's initial value will be displayed.

        フィールド初期値の表示に使う書式。

    .. If no ``format`` argument is provided, the default format is the first
       format found in :setting:`DATETIME_INPUT_FORMATS` and respects
       :ref:`format-localization`.

    ``format`` 引数が指定されない場合、デフォルトの書式は
    :setting:`DATETIME_INPUT_FORMATS` で最初に見つかった書式になり、かつ
    :ref:`format-localization` が適用されます。

``TimeInput``
~~~~~~~~~~~~~

.. class:: TimeInput

    .. Time input as a simple text box: ``<input type='text' ...>``

    単純なテキストボックスで表現された、時刻用の入力ウィジェット:
    ``<input type='text' ...>`` です。

    .. Takes one optional argument:

    オプションの引数を一つ取ります:

    .. attribute:: TimeInput.format

        .. The format in which this field's initial value will be displayed.

        フィールド初期値の表示に使う書式。

    .. If no ``format`` argument is provided, the default format is the first
       format found in :setting:`TIME_INPUT_FORMATS` and respects
       :ref:`format-localization`.

    ``format`` 引数が指定されない場合、デフォルトの書式は
    :setting:`TIME_INPUT_FORMATS` で最初に見つかった書式になり、かつ
    :ref:`format-localization` が適用されます。

``Textarea``
~~~~~~~~~~~~

.. class:: Textarea

    テキストエリア: ``<textarea>...</textarea>`` です。

``CheckboxInput``
~~~~~~~~~~~~~~~~~

.. class:: CheckboxInput

    チェックボックス: ``<input type='checkbox' ...>`` です。

    .. Takes one optional argument:

    オプションの引数を一つ取ります:

    .. attribute:: CheckboxInput.check_test

        .. A callable that takes the value of the CheckBoxInput and returns
           ``True`` if the checkbox should be checked for that value.

        CheckboxInput の値を受け取り、チェックボックスにチェックを入れるべき
        ならば ``True`` を返す呼び出し可能オブジェクト。

``Select``
~~~~~~~~~~

.. class:: Select

    セレクタ: ``<select><option ...>...</select>`` です。

    .. attribute:: Select.choices

        .. This attribute is optional when the field does not have a
           :attr:`~Field.choices` attribute. If it does, it will override anything
           you set here when the attribute is updated on the :class:`Field`.

        この属性は、フィールドに :attr:`~Field.choices` 属性が無い場合には
        指定する必要はありません。もし属性がある場合、 :class:`Field` で
        `choices` 属性が更新されると、ここでの指定は上書きされます。

``NullBooleanSelect``
~~~~~~~~~~~~~~~~~~~~~

.. class:: NullBooleanSelect

    「不明」, 「はい」, 「いいえ」 を選択肢とするセレクタです。

``SelectMultiple``
~~~~~~~~~~~~~~~~~~

.. class:: SelectMultiple

    .. Similar to :class:`Select`, but allows multiple selection:
       ``<select multiple='multiple'>...</select>``

    :class:`Select` と似ていますが、複数選択が可能なセレクタ:
    ``<select multiple='multiple'>...</select>`` です。

``RadioSelect``
~~~~~~~~~~~~~~~

.. class:: RadioSelect

    .. Similar to :class:`Select`, but rendered as a list of radio buttons within
       ``<li>`` tags:

    :class:`Select` と似ていますが、 ``<li>`` タグを使ったラジオボタンのリスト
    としてレンダリングされます:

    .. code-block:: html

        <ul>
          <li><input type='radio' ...></li>
          ...
        </ul>

    .. versionadded:: 1.4

    .. 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:

    生成されるマークアップをもっと細かくコントロールしたければ、テンプレート内で
    ラジオボタンに対してループを回すことができます。仮に ``myform`` という
    フォームがあり、そこに ``RadioSelect`` をウィジェットに指定した ``beatles``
    というフィールドがあると仮定すると:

    .. code-block:: html+django

        {% for radio in myform.beatles %}
        <div class="myradio">
            {{ radio }}
        </div>
        {% endfor %}

    .. This would generate the following HTML:

    これは次の HTML を生成します:

    .. code-block:: html

        <div class="myradio">
            <label><input type="radio" name="beatles" value="john" /> John</label>
        </div>
        <div class="myradio">
            <label><input type="radio" name="beatles" value="paul" /> Paul</label>
        </div>
        <div class="myradio">
            <label><input type="radio" name="beatles" value="george" /> George</label>
        </div>
        <div class="myradio">
            <label><input type="radio" name="beatles" value="ringo" /> Ringo</label>
        </div>

    .. That included the ``<label>`` tags. To get more granular, you can use each
       radio button's ``tag`` and ``choice_label`` attributes. For example, this template...

    ``<label>`` タグに囲まれていますね。さらに細かくコントロールしたければ、
    ラジオボタンごとの ``tag`` と ``choice_label`` 属性を使えます。例えば
    このテンプレート...

    .. code-block:: html+django

        {% for radio in myform.beatles %}
            <label>
                {{ radio.choice_label }}
                <span class="radio">{{ radio.tag }}</span>
            </label>
        {% endfor %}

    .. ...will result in the following HTML:

    ...は次の HTML になります:

    .. code-block:: html

            <label>
                John
                <span class="radio"><input type="radio" name="beatles" value="john" /></span>
            </label>
            <label>
                Paul
                <span class="radio"><input type="radio" name="beatles" value="paul" /></span>
            </label>
            <label>
                George
                <span class="radio"><input type="radio" name="beatles" value="george" /></span>
            </label>
            <label>
                Ringo
                <span class="radio"><input type="radio" name="beatles" value="ringo" /></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.

    もしラジオボタンに対してループを回さない -- つまり単純にテンプレートで
    ``{{ myform.beatles }}`` と書く -- と決めたなら、上に記した通り、
    それらは ``<li>`` タグを使った ``<ul>`` の中に出力されることになるでしょう。

``CheckboxSelectMultiple``
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. class:: CheckboxSelectMultiple

    .. Similar to :class:`SelectMultiple`, but rendered as a list of check
       buttons:

    :class:`SelectMultiple` と似ていますが、チェックボックスのリストとして
    レンダリングされます:

    .. code-block:: html

        <ul>
          <li><input type='checkbox' ...></li>
          ...
        </ul>

``MultiWidget``
~~~~~~~~~~~~~~~

.. class:: MultiWidget

    .. Wrapper around multiple other widgets. You'll probably want to use this
       class with :class:`MultiValueField`.

    複数のウィジェットをラップするウィジェットです。おそらく
    :class:`MultiValueField` と共に使いたくなるでしょう。

    .. Its ``render()`` method is different than other widgets', because it has to
       figure out how to split a single value for display in multiple widgets.

    これの ``render()`` メソッドは、どうやって一つの値を複数のウィジェットで
    表示するかを決める必要があるため、他のウィジェットのものとは異なります。

    .. Subclasses may implement ``format_output``, which takes the list of
       rendered widgets and returns a string of HTML that formats them any way
       you'd like.

    これのサブクラスは ``format_output`` メソッドを独自に実装しているかも
    しれません。 ``format_output`` メソッドは、レンダリングされたウィジェットの
    リストを受け取って、それらを自由に書式化し、 HTML の文字列を返します (訳注:
    format_output メソッドはウィジェットのレンダリング結果をカスタマイズする
    フックです)。

    .. The ``value`` argument used when rendering can be one of two things:

    レンダリング時に使われる引数 ``value`` は次の 2 つのいずれかになります:

    .. * A ``list``.
       * A single value (e.g., a string) that is the "compressed" representation
         of a ``list`` of values.

    * 一つの ``list`` 。
    * 値の ``list`` を「圧縮」表現した一つの値 (例えば文字列) 。

    .. In the second case -- i.e., if the value is *not* a list -- ``render()``
       will first decompress the value into a ``list`` before rendering it. It
       does so by calling the ``decompress()`` method, which
       :class:`MultiWidget`'s subclasses must implement. This method takes a
       single "compressed" value and returns a ``list``. An example of this is how
       :class:`SplitDateTimeWidget` turns a :class:`datetime` value into a list
       with date and time split into two seperate values::

    2 つ目の場合 -- すなわちリスト *ではない* 場合 -- ``render()`` はまず
    レンダリングする前に値を ``list`` に展開します。これは、
    :class:`MultiWidget` のサブクラスが実装しなければならない ``decompress()``
    メソッドを呼ぶことで行われます。このメソッドは一つの「圧縮」された値を
    受け取り、``list`` を返します。一例として、
    :class:`SplitDateTimeWidget` がどうやって :class:`datetime` の値を
    日付と時刻という 2 つの値に分離したリストに変換しているかを挙げましょう::

        class SplitDateTimeWidget(MultiWidget):

            # ...

            def decompress(self, value):
                if value:
                    return [value.date(), value.time().replace(microsecond=0)]
                return [None, None]

    .. When ``render()`` executes its HTML rendering, each value in the list is
       rendered with the corresponding widget -- the first value is rendered in
       the first widget, the second value is rendered in the second widget, etc.

    ``render()`` が HTML レンダリングを実行するとき、リスト中の各値は対応する
    ウィジェットを使ってレンダリングされます -- 最初の値は最初のウィジェットで、
    2 つ目の値は 2 つ目のウィジェットで、という具合です。

    .. :class:`MultiWidget` has one required argument:

    :class:`MultiWidget` は 1 つ指定必須の引数があります:

    .. attribute:: MultiWidget.widgets

        .. An iterable containing the widgets needed.

        必要なウィジェットを含んだイテレーション可能オブジェクト。

``SplitDateTimeWidget``
~~~~~~~~~~~~~~~~~~~~~~~

.. class:: SplitDateTimeWidget

    .. Wrapper (using :class:`MultiWidget`) around two widgets: :class:`DateInput`
       for the date, and :class:`TimeInput` for the time.

    日付用の :class:`DateInput` と、時刻用の :class:`TimeInput` を、
    :class:`MultiWidget` を使ってラップしたものです。

    ``SplitDateTimeWidget`` には 2 つオプションの属性があります:

    .. attribute:: SplitDateTimeWidget.date_format

        .. Similar to :attr:`DateInput.format`

        :attr:`DateInput.format` と似ています。

    .. attribute:: SplitDateTimeWidget.time_format

        .. Similar to :attr:`TimeInput.format`

        :attr:`TimeInput.format` と似ています。

``SplitHiddenDateTimeWidget``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. class:: SplitHiddenDateTimeWidget

    .. Similar to :class:`SplitDateTimeWidget`, but uses :class:`HiddenInput` for
       both date and time.

    :class:`SplitDateTimeWidget` と似ていますが、 :class:`HiddenInput`
    を日付と時間の両方に使用します。

.. currentmodule:: django.forms.extras.widgets

``SelectDateWidget``
~~~~~~~~~~~~~~~~~~~~

.. class:: SelectDateWidget

    .. Wrapper around three :class:`~django.forms.Select` widgets: one each for
       month, day, and year. Note that this widget lives in a separate file from
       the standard widgets.

    年・月・日それぞれ用の :class:`~django.forms.Select` ウィジェット
    3 つをラッピングしたウィジェットです。なおこのウィジェットは標準の
    ウィジェットとは異なるファイルで提供されていますので注意してください。

    .. Takes one optional argument:

    オプションの引数を一つ取ります。

    .. attribute:: SelectDateWidget.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.

        オプションの、"year" セレクタで使用する年のリストまたはタプルです。
        デフォルトでは現在の年から 9 年先までを含んだリストになります。