ウィジェット

revision-up-to:11321 (1.1) unfinished

ウィジェットとは、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 DateInput
Django 1.1 で新たに登場しました: Please, see the release notes

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

Takes one optional argument:

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

If no format argument is provided, the default format is '%Y-%m-%d'.

class DateTimeInput
Django 1.0 で新たに登場しました: Please, see the release notes

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

Takes one optional argument:

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

If no format argument is provided, the default format is '%Y-%m-%d %H:%M:%S'.

class TimeInput

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

Takes one optional argument:

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

If no format argument is provided, the default format is '%H:%M:%S'.

Django 1.1 で変更されました: The format argument was not supported in Django 1.0.
class Textarea
テキストエリア: <textarea>...</textarea> です。
class CheckboxInput
チェックボックス: <input type='checkbox' ...> です。
class Select

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

Requires that your field provides choices.

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

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

Requires that your field provides choices.

class RadioSelect

ラジオボタンのリストです。以下のようにレンダされます:

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

Requires that your field provides choices.

class CheckboxSelectMultiple

チェックボックスのリストです。以下のようにレンダされます:

<ul>
  <li><input type='checkbox' ...></li>
  ...
</ul>
class MultiWidget
複数のウィジェットをラップするウィジェットです。
class SplitDateTimeWidget

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

Takes two optional arguments, date_format and time_format, which work just like the format argument for DateInput and TimeInput.

Django 1.1 で変更されました: The date_format and time_format arguments were not supported in Django 1.0.

ウィジェットの指定

Form.widget

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

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

from django import forms

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

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

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

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

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>
« 前へ | 上へ | 次へ »