ウィジェット

□未翻訳

□翻訳中

■翻訳完了（細田謙二）

■レビュー（Omi Chiba）

ウィジェット

以下に利用可能なweb2pyのウィジェットの一覧を示します：

Here is a list of available web2py widgets:

最初の10個は対応するフィールド型のデフォルトになります。"options"ウィジェットは、フィールドの要求がIS_IN_SETかIS_IN_DBでmultiple=False(デフォルトの挙動)のときに使用されます。"multiple"ウィジェットはフィールドの要求がIS_IN_SETかIS_IN_DBでmultiple=Trueのときに使用されます。"radio"と"checkboxes"ウィジェットはデフォルトでは決して使用されませんが、手動で設定することができます。autocompleteウィジェットは特別で、それ自身のセクションで説明します。

The first ten of them are the defaults for the corresponding field types. The "options" widget is used when a field's requires is IS_IN_SET or IS_IN_DB with multiple=False (default behavior). The "multiple" widget is used when a field's requires is IS_IN_SET or IS_IN_DB withmultiple=True. The "radio" and "checkboxes" widgets are never used by default, but can be set manually. The autocomplete widget is special and discussed in its own section.

たとえば、textareaで表される"文字列"フィールドを持つには以下のようにします：

For example, to have a "string" field represented by a textarea:

新しいウィジェットを作成したり、既存のウィジェットを拡張したりすることができます。

You can create new widgets or extend existing widgets.

SQLFORM.widgets[type]はクラスで、SQLFORM.widgets[type].widgetは対応するクラスの静的メンバ関数です。各ウィジェット関数は2つの引数をとります。フィールドオブジェクトと現在のフィールドの値です。これは、ウィジェットの表現を返します。例として、stringウィジェットは次のように再コード化することができます：

SQLFORM.widgets[type] is a class and SQLFORM.widgets[type].widget is a static member function of the corresponding class. Each widget function takes two arguments: the field object, and the current value of that field. It returns a representation of the widget. As an example, the string widget could be recoded as follows:

idとclassの値は、本章の後半で説明されている慣例に従う必要があります。ウィジェットは独自のバリデータを持つことが可能ですが、バリデータをフィールドの"requires"属性に関連付け、ウィジェットがそこからそれらを得るようにするのが良いプラクティスです。

The id and class values must follow the convention described later in this chapter. A widget may contain its own validators, but it is good practice to associate the validators to the "requires" attribute of the field and have the widget get them from there.

Autocomplete ウィジェット

Autocomplete Widget

autocompleteウィジェットには2つの使い道があります：リストから値を受けてフィールドを自動補完するためと、参照フィールドを自動補完するためです(ここで自動補完される文字列はidのように実装された参照の表現です)。

There are two possible uses for the autocomplete widget: to autocomplete a field that takes a value from a list or to autocomplete a reference field (where the string to be autocompleted is a representation of the reference which is implemented as an id).

最初のケースは簡単です：

The first case is easy:

ここで、limitbyは一度に10個までの候補しか表示しないようにウィジェットに指示します。min_lengthは、ユーザーが検索ボックスにおいて少なくとも2文字をタイプした後のみ、候補を取得するAjaxコールバックを実行するようにウィジェットに指示します。

Where limitby instructs the widget to display no more than 10 suggestions at the time, andmin_length instructs the widget to perform an Ajax callback to fetch suggestions only after the user has typed at least 2 characters in the search box.

2番目のケースはより複雑になります：

The second case is more complex:

この場合、id_fieldの値は、自動補完される値がdb.category.nameでも、保存される値は対応するdb.category.idになるようにウェジェットに支持します。オプションのパラメタorderbyは、候補をどのようにソートするかをウィジェットに指示します(デフォルトはアルファベット順です)。

In this case the value of id_field tells the widget that even if the value to be autocompleted is a db.category.name, the value to be stored is the corresponding db.category.id. An optional parameter is orderby that instructs the widget on how to sort the suggestions (alphabetical by default).

このウィジェットは、Ajaxを介して動作します。ここで、Ajaxコールバックはどこにあるのでしょうか？いくつかの魔法が、このウィジェットで起こっています。コールバックはウィジェットオブジェクトのメソッドそのものです。どのように公開されているのでしょうか？web2pyにおいて、任意のコード断片はHTTP例外を発生させることによってレスポンスを生成することができます。このウィジェットは次の方法でこの可能性を利用しています：ウィジェットはAjax呼び出しを最初にウィジェットを生成したURLと同じところに送ります。そして、request.varsにおいて特別なトークンを置きます。ウィジェットは再びインスタンス化されるはずで、ウィジェットはそのトークンを見つけ、リクエストに応答するHTTP例外を発生させます。これらすべては内部で行われ、開発者に対して隠されています。

This widget works via Ajax. Where is the Ajax callback? Some magic is going on in this widget. The callback is a method of the widget object itself. How is it exposed? In web2py any piece of code can generate a response by raising an HTTP exception. This widget exploits this possibility in the following way: the widget sends the Ajax call to the same URL that generated the widget in the first place and puts a special token in the request.vars. Should the widget get instantiated again, it finds the token and raises an HTTP exception that responds to the request. All of this is done under the hood and hidden to the developer.