パーフェクトDojo(6) 多彩な機能を誇るテキストフィールドウィジェット

今回は、テキストフィールドウィジェットに関する紹介だ。Dijitのテキストフィールドは、入力値のチェックや入力支援、値のフォーマットといった機能を備えており、非常に機能が豊富だ。

Dojoが持つテキストフィールドウィジェットの概要

Dojoには、豊富なテキストフィールドウィジェットが存在する。目的に応じてそれらを使い分けるわけだが、通常のテキストフィールド(<input type="text">)と比べると以下のような利点がある。

入力値の自動的な整形機能……フォーカス喪失時に、数値、日付、金額などさまざま形式へと自動的に入力値が整形される
表示形式と値の分離……入力値がどのように整形されようとも、それに左右されず純粋な値を取得できる。「10,000」と表示されているフィールドから数値の10000を取得するなど。フォームを送信した際にサーバに送信される値は、NumberTextBoxやCurrencyTextBoxであれば生の数値、DateTextBoxやTimeTextBoxであればISO-8601フォーマット(例: "2008-04-11T00:00:00")の文字列で送信される
入力値のチェック機能……入力された値のバリデーションも自動的に行われる。数値や日付、範囲などはもちろんのこと、カスタムの正規表現を用いたり、チェック関数を自作することも可能
その他の機能……前後の空白を除去したり、自動的に大文字/小文字に変換するなど、細かい機能をいくつもそろえる

以下に詳細なリファレンスを示す。

テキストフィールド

対応するクラス

dijit.form.TextBox

利用例

通常のテキストフィールド

TextBox:<div dojoType="dijit.form.TextBox" lowercase="true">

説明

以降で紹介するテキストフィールドのベースとなるウィジェットだ。標準的なテキストフィールドが持つ属性に加え、入力された値を加工(前後の空白除去や大文字/小文字の変換など)する機能を備える。

属性

lowercase	trueの場合、フォーカスが外れた際に入力された文字列をすべて小文字に変換する
maxLength	最大入力文字数
propercase	trueの場合、単語の先頭をすべて大文字に変換する
size	テキストフィールドのサイズ
trim	trueの場合、入力値の前後から空白を除去する
uppercase	trueの場合、フォーカスが外れた際に入力された文字列をすべて大文字に変換する

メソッド

getDisplayedValue()	ユーザに対して表示されている文字列を取得する。DateTextBoxやCurrencyTextBoxなどは表示上の文字列と、内部的に保持されている(サーバに送信される)値が異なるため、両者を別々に扱うことができる
setDisplayedValue(/String/ value)	ユーザに対して表示する文字列をセットする
setValue(value, /Boolean, optional/ priorityChange, /String, optional/ formattedValue)	テキストフィールドに値をセットする。引数の説明は以下: value…セットする値 priorityChange…trueの場合、onChangeイベントが発生する(省略可) formattedValue…表示する値(省略可)

入力値チェック可能なテキストフィールド

対応するクラス

dijit.form.ValidationTextBox

利用例1: 正規表現を用い、7桁の郵便番号のみを許容

バリデーションテキストボックス

<div
  dojoType="dijit.form.ValidationTextBox"
  promptmessage="郵便番号(nnn-nnnn)"
  regexp="\d{3}\-\d{4}">
</div>

利用例2: 拡張ポイントregExpGen()をオーバーライドして、7桁の郵便番号のみを許容

<div
  dojoType="dijit.form.ValidationTextBox"
  promptmessage="郵便番号(nnn-nnnn)"
  constraint="{}">
  <script type="dojo/method" event="regexpgen" args="constraint">
        return "\\d{3}\\-\\d{4}";
  </script>
</div>

利用例3: 拡張ポイントisValid()をオーバーライドして、7桁の郵便番号のみを許容

<div
  dojoType="dijit.form.ValidationTextBox"
  promptmessage="郵便番号(nnn-nnnn)">
  <script type="dojo/method" event="isValid">
        return this.textbox.value.match(/\d{3}\-\d{4}/);
  </script>
</div>

説明

入力値のチェックを行うことができるテキストボックス。以下のテキストボックスウィジェットの親クラスとなる。

入力値のチェックは、以下の方法を用いて行うことができる。

regExp属性に正規表現を指定
regExpGenメソッドをオーバーライド…同メソッドは、constraint属性に指定したJavaScriptオブジェクトを引数にとり、正規表現文字列を生成して返す
isValidメソッドをオーバーライド・・・入力値のチェック結果をtrue/falseで返す。入力された値は「this.textbox.value」にアクセスすると取得できる

属性

constraints	バリデータ関数に渡されるために使われる、ユーザ定義のオブジェクト
invalidMessage	値が不正だった場合に表示されるメッセージ
promptMessage	入力のヒントになるメッセージ
regExp	入力値のバリデーションに使用される正規表現
required	入力が必須かどうか(Boolean)

拡張ポイント

displayMessage(/String/ message)	invalidMessageやpromptMessageを表示するためにオーバーライドできる(デフォルトではツールチップが使用される)
String getErrorMessage(/* Boolean*/ isFocused)	入力エラー時に表示するメッセージを返す
String getPromptMessage(/* Boolean*/ isFocused)	入力のヒント(フォーカス時に表示される)になるメッセージを返す
Boolean isValid(/* Boolean*/ isFocused)	入力値のチェック結果をtrue/falseで返す
String regExpGen(/* Object */constraints)	カスタムの正規表現を利用してチェックするようオーバーライドできる

数値入力フィールド

対応するクラス

dijit.form.NumberTextBox
dijit.form.CurrencyTextBox

利用例: 10000以上、99999以下の数値を受け付けるテキストフィールド

数値入力テキストフィールド

<div dojoType="dijit.form.NumberTextBox"
  constraints="{min: 10000, max: 99999}">
</div>

説明

数値のみ入力を受け付けるテキストフィールド。フォーカス喪失時に、自動的に桁区切りなどのフォーマットが行われる。また、CurrencyTextBoxを使うと、ロケールに合わせた通貨記号を付与することも可能(currency属性を用いて、通貨記号を指定することも可能)。

上の例のように、constraints属性を用いて最小値(min)や最大値(max)を指定することも可能。また、ValidationTextBoxを継承しているため、同クラスの機能をすべて利用できる。

属性

currency	CurrencyTextBoxのみ。ISO-4217で規定されている通貨コードを利用して、通貨記号の指定を行うことができる

拡張ポイント

Integer compare(/* Object /val1, / Object */val2)	範囲のチェックに用いられる比較関数。オーバーライドし、独自の比較を行わせることができる。第1引数には入力値、第2引数はconstraints属性で指定したminやmaxの値が渡される
Boolean isInRange(/* Boolean*/ isFocused)	独自の範囲チェックを行うためにオーバーライドすることができる

日付/時刻入力フィールド

対応するクラス

dijit.form.DateTextBox
dijit.form.TimeTextBox

利用例: 日付入力フィールド

日付入力フィールド

DateTextBox:<div dojoType="dijit.form.DateTextBox"></div>

利用例: 時刻入力フィールド

時刻入力フィールド

TimeTextBox:
    <div dojoType="dijit.form.TimeTextBox" constraints="{formatLength: 'full'}">
    </div>

説明

日付や時刻の入力用フィールドで、フォーカスすると画像のように入力支援用のカレンダーが表示される。内部的には値をDate型で保持しているほか、サーバに送信される値はISO-8601フォーマット(例:"2008-04-11T00:00:00")が使用される。

これらのクラスは、ValidationTextBoxを継承しているだけではなく、最小値や最大値を用いた範囲チェックも行うことができる。

また、さまざまなconstraints属性を用いて入力値のチェックや書式指定を行うことが可能だ。constraints属性については、英語になってしまうがこちらのドキュメントを参照いただきたい。

拡張ポイント

Integer compare(/* Object /val1, / Object */val2)	範囲のチェックに用いられる比較関数。オーバーライドし、独自の比較を行わせることができる。第1引数には入力値、第2引数はconstraints属性で指定したminやmaxの値が渡される
Boolean isInRange(/* Boolean*/ isFocused)	独自の範囲チェックを行うためにオーバーライドすることができる