.. _ref-forms-widgets:
.. _Widgets:

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

:revision-up-to: 8961 (1.0)

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

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

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

.. class:: TextInput

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

.. class:: PasswordInput

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

.. class:: HiddenInput

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

.. class:: MultipleHiddenInput

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

.. class:: FileInput

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

.. class:: DateTimeInput

    .. versionadded:: 1.0

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

.. class:: Textarea

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

.. class:: CheckboxInput

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

.. class:: Select

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

.. class:: NullBooleanSelect

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

.. class:: SelectMultiple

    複数選択の可能なセレクタ: ``<select multiple='multiple'>...</select>``
    です。 

.. class:: RadioSelect

    ラジオボタンのリストです。以下のようにレンダされます:
    
    .. code-block:: html
    
        <ul>
          <li><input type='radio' ...></li>
          ...
        </ul>

.. class:: CheckboxSelectMultiple

    チェックボックスのリストです。以下のようにレンダされます:
    
    .. code-block:: html
    
        <ul>
          <li><input type='checkbox' ...></li>
          ...
        </ul>

.. class:: MultiWidget

    複数のウィジェットをラップするウィジェットです。

.. class:: SplitDateTimeWidget

    日付と時刻を表す二つの ``TextInput`` ウィジェットを組み合わせてラップし
    たものです。

.. _Specifying widgets:

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

.. attribute:: Form.widget

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

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

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

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

.. _Customizing widget instances:

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

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

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

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

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

このフォームは 3 つの 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 クラスを指定したかったりするかもしれま
せん。個々のウィジェットの属性こ細かく指定するには、フィールドにカスタムの
ウィジェットを指定して、ウィジェットのレンダリング時に使われる属性を指定し
ます。

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