10 入力の検証および変換
oj-combobox、oj-input*、oj-text-areaなど、多数のOracle JET編集可能要素に対するバリデータおよびコンバータが含まれています。これらをそのまま使用することも、Oracle JETアプリケーションでの入力を検証および変換するためにカスタマイズすることもできます。oj-checkboxset、oj-radioset、oj-selectなどの一部の編集可能要素には、組込みバリデータを暗黙的に作成するrequired値の単純な属性が含まれます。
ノート:
前述のoj-input*は、特に、oj-input-date-time、oj-input-text、oj-input-passwordなどの入力コンポーネントのファミリを指します。
Oracle JETバリデータおよびコンバータについて
Oracle JETには、ユーザー入力文字列をアプリケーションで使用できるデータ型に変換するコンバータ・クラス、およびそれらの入力文字列に検証ルールを強制するバリデータ・クラスが用意されています。
たとえば、Oracle JETのIntlDateTimeConverterを使用して、ユーザー入力の日付をアプリケーションのViewModelで使用するDateオブジェクトに変換し、次にDateTimeRangeValidatorを使用して、指定の期間範囲に対してその入力を検証できます。コンバータを使用すると、DateまたはNumberオブジェクトを表示に適した文字列に変換する、またはカラー・オブジェクトの形式を変換することもできます。
Oracle JETには、登録済タイプのコンバータ・ファクトリまたはバリデータ・ファクトリを取得するために、コンバータ・ファクトリおよびバリデータ・ファクトリを登録して取得するメソッドが含まれるValidationクラスがあります。
Oracle JETに含まれるコンバータまたはバリデータがアプリケーションにとって十分でない場合は、カスタムのコンバータまたはバリデータを作成できます。必要に応じて、コンバータ(ConverterFactoryを使用)またはバリデータ(ValidatorFactoryを使用)の規約を実装するカスタム・ファクトリを指定し、そのコンバータまたはバリデータをValidationクラスに登録できます。Validationクラスを使用すると、Oracle JETの標準コンバータおよびバリデータを使用する場合と同じメカニズムでカスタム・コンバータまたはバリデータにアクセスできます。
バリデータについて
すべてのOracle JET編集可能要素はvalue属性をサポートし、ユーザーが値を入力または選択できるUI要素を提供します。これらの要素は、要素に対して値の検証方法を指示するためにページ作成者が設定できる、その他の属性もサポートしています。
編集可能要素では、特定の属性が設定されると、標準機能に対する組込みコンバータまたは組込みバリデータ(あるいはその両方)を暗黙的に作成できます。
たとえば、requiredプロパティをサポートする編集可能要素では、プロパティがtrueに設定されると必須バリデータを暗黙的に作成します。oj-input-date、oj-input-date-time、oj-input-timeなどの要素では、日時コンバータを作成してその基本機能を実装します。
Oracle JETバリデータについて
次の表では、Oracle JETバリデータについて説明し、APIドキュメントへのリンクを示します。
| バリデータ | 説明 | APIへのリンク | モジュール |
|---|---|---|---|
|
|
入力日付が、2つの日付間、2つの時刻間、または2つの日時範囲内にあることを検証します |
|
|
|
|
入力日付が制限された日付でないことを検証します |
|
|
|
|
入力文字列が指定された長さ以内であることを検証します |
|
|
|
|
入力数値が指定された範囲内であることを検証します |
|
|
|
|
正規表現が指定のパターンに一致していることを検証します |
|
|
|
|
必須エントリが存在していることを検証します |
|
Oracle JETコンポーネントの検証属性について
コンポーネントがサポートする属性はAPIの一部で、次の検証固有の属性がほとんどの編集可能要素に適用されます。
| 要素の属性 | 説明 |
|---|---|
|
|
指定すると、要素で作成される内部コンバータに対して |
|
|
|
|
|
Oracle JET要素( |
|
|
Oracle JET要素( |
|
|
Oracle JET要素( |
|
|
指定すると、ほとんどの要素にプレースホルダ値が表示されます。 |
|
|
Oracle JET要素に対して指定すると、要素では暗黙的な必須バリデータを作成します。 |
|
|
指定すると、要素ではこれらのバリデータと暗黙的なバリデータを使用して、UI値を検証します。 |
一部の編集可能要素は、固有の機能に関連がないため特定の検証属性をサポートしていません。たとえば、oj-radiosetおよびoj-checkboxsetは、コンバータが変換する対象がないため、converter属性をサポートしていません。属性の正確なリストおよび使用方法は、要素のAPIドキュメントの属性に関する項を参照してください。Oracle JETのAPIドキュメントについては、『Oracle® JavaScript Extension Toolkit (OracleJET) APIリファレンス』を参照してください。APIリストから表示するコンポーネントを選択してください。
Oracle JETコンポーネントの検証メソッドについて
Oracle JET編集可能要素は、検証目的で次のメソッドをサポートしています。このメソッドのコール方法、およびパラメータと戻り値の詳細は、コンポーネントのAPIドキュメントを参照してください。
| 要素メソッド | 説明 |
|---|---|
|
|
このメソッドは、ロケールでの変更のために |
|
|
このメソッドは、すべてのメッセージおよびメッセージ属性( |
|
|
このメソッドは、現在の表示値を使用してコンポーネントを検証するために使用します。 |
要素のメソッドのコール方法、パラメータおよび戻り値の詳細は、『Oracle® JavaScript Extension Toolkit (Oracle JET) APIリファレンス』で、要素のAPIドキュメントのMethodsに関する項を参照してください。コールバックの登録方法、イベントへのバインド方法、およびイベントがトリガーする対象の詳細も記載されています。APIリストから表示するコンポーネントを選択してください。
コンバータについて
Oracle JETコンバータには、次の表で説明するように、日付、日時、数値および色コンバータが含まれています。
| コンバータ | 説明 | APIへのリンク |
|---|---|---|
|
|
Colorオブジェクト形式を変換します |
|
|
|
文字列を |
|
|
|
文字列を数値に変換したり、数値または |
|
|
|
日付のみのISO文字列を書式設定された文字列に、または文字列を日付のみのISO文字列に変換します |
Oracle JETコンポーネントのコンバータ・オプションについて
Oracle JETコンバータではoptions属性を使用して、色、数値、日付および日時の値に様々な書式設定オプションを使用できます。
色コンバータ
色コンバータでは次のオプションがサポートされます。
| オプション名 | 説明 |
|---|---|
|
|
変換された色指定の書式を設定します。使用可能な値は、"rgb" (デフォルト)、"hsl"、"hsv"、"hex"および"hex3" (3桁の16進コード)です。 |
オプションとメソッドの正確なリストおよび使用方法は、ColorConverterクラスのAPIドキュメントを参照してください。ColorConverterに関する項を参照してください。
数値コンバータ
数値コンバータでは、小数、通貨、パーセンテージまたは単位の書式設定に使用可能な多数のオプションがサポートされます。重要なオプションの一部を次に示します。
| オプション名 | 説明 |
|---|---|
|
|
数値の書式設定のスタイルを設定します。使用可能な値は、"decimal" (デフォルト)、"currency"、"percent"または"unit"です。 小数、パーセンテージおよび単位の場合、小数点文字(点またはカンマ)と桁区切り(桁区切りが有効な場合)にはロケールに適した記号が使用されます。 |
|
|
|
|
|
使用可能な値は、"code"、"name"および"symbol" (デフォルト)です。styleがcurrencyの場合、このオプションは通貨の表示を名前(Euroなど)にするか、アルファベットのISO 4217通貨コード(EURなど)にするか、または一般に認識されている記号(€など)にするか指定します。
|
|
|
このオプションは、 |
|
|
小数点前の最小桁数を設定します。数値の桁数が足りない場合は、前にゼロを付けて埋め込みます。使用可能な値は、1から21までの任意の整数です。 |
|
|
小数点後の最小桁数を設定します。数値の桁数が足りない場合は、後ろにゼロを付けて埋め込みます。使用可能な値は、0から20までの任意の整数です。 |
|
|
小数点後の最大桁数を設定します。設定された最大桁数を超える場合、その数値は丸められます。使用可能な値は、0から20までの任意の整数です。 |
|
|
他のオプションをオーバーライドして数値に使用するパターンを設定します。パターンでは、数値、パーセントおよび通貨書式に対してUnicode CLDRで指定された記号を使用します。 通貨書式では パーセンテージ書式では、 小数または指数パターンの場合は、{pattern: "#,##0.00"}または{pattern: "0.##E+0"}のように指定します。 |
|
|
丸め動作を指定します。使用可能な値は、 |
|
|
解析時に丸めるかどうかを指定します。デフォルトはfalseです。数値コンバータでは書式設定時には丸め、解析時には丸めません。 |
オプションとメソッドの正確なリストおよび使用方法は、IntlNumberConverterクラスのAPIドキュメントを参照してください。IntlNumberConverterに関する項を参照してください。
数値コンバータ・オプションの使用例は、数値コンバータに関する項を参照してください。
日時コンバータ
日時コンバータでは、日時の値を複数のロケール間ですべて共通のスタイルに書式設定するための使用可能なオプションが幅広くサポートされています。重要なオプションの一部を次に示します。
| オプション名 | 説明 |
|---|---|
|
|
使用可能な値は、 |
|
|
使用可能な値は、 |
|
|
使用可能な値は、 |
|
|
使用する標準の日付/時間書式の長さを指定します。使用可能な値は、"date"、"time"、"datetime"です。設定する場合は、必要に応じて |
|
|
|
|
|
|
|
|
使用可能な値は、 |
|
|
使用可能な値は、 |
|
|
使用可能な値は、 |
オプションとメソッドの正確なリストおよび使用方法は、IntlDateTimeConverterクラスのAPIドキュメントを参照してください。IntlDateTimeConverterに関する項を参照してください。
日時コンバータ・オプションの使用例は、日時コンバータに関する項を参照してください。
日付コンバータ
日付コンバータでは、日付のみの値を複数のロケール間ですべて共通のスタイルに書式設定するための使用可能なオプションがサポートされています。LocalDateConverterは、オプション数がIntlDateTimeConverterより少なく、時間またはタイムゾーンに関連するオプションはありませんが、ユーザー入力を書式設定された日付文字列に解析する場合は効率的で柔軟性があります。
| オプション名 | 説明 |
|---|---|
|
|
使用する標準の日付書式の長さを指定します。使用可能な値は、 |
locale |
このコンバータ・インスタンスで使用するロケールを指定します。このオプションが指定されていない場合、コンバータは |
オプションとメソッドの正確なリストおよび使用方法は、LocalDateConverterクラスのAPIドキュメントを参照してください。LocalDateConverterに関する項を参照してください。
Oracle JETコンバータについて
Oracle JETの色コンバータ、日付コンバータ、日時コンバータおよび数値コンバータであるColorConverter、LocalDateConverter、IntlDateTimeConverterおよびIntlNumberConverterによって、コンバータ実装の基本規約を定義するConverterオブジェクトが拡張されます。
コンバータAPIは、ECMAScript国際化API仕様(ECMA-402 Edition 1.0)に基づき、ロケール・データに対してUnicode共通ロケール・データ・リポジトリ(CLDR)を使用します。両方のコンバータはコンストラクタを介して初期化され、API仕様で定義されたオプションを受け入れます。ECMA-402 API仕様の詳細は、https://www.ecma-international.org/publications-and-standards/standards/ecma-402/を参照してください。Unicode CLDRの詳細は、http://cldr.unicode.orgを参照してください。
Oracle JET実装では、ユーザー定義パターンのオプションを含む追加オプションを導入することによって、ECMA-402仕様が拡張されます。追加オプションのリストは、ColorConverter、IntlDateTimeConverter、IntlNumberConverterおよびLocalDateConverter APIドキュメントを参照してください。
実行中の日時および数値コンバータを示す例は、Oracle JETクックブックのコンバータに関する項を参照してください。色コンバータを使用する例は、カラー・パレットおよび色のスペクトル Cookbookサンプルを参照してください。
ノート:
RequireJSおよびojs/ojvalidation-datetimeまたはojs/ojvalidation-numberモジュールを使用する場合、Oracle JETコンバータで使用するロケール記号およびデータを保持するバンドルは、ページに設定されたロケールに基づいて自動的にダウンロードされます。アプリケーションでRequireJSを使用しない場合、ロケール・データは自動的にダウンロードされません。
コンバータは、Oracle JETコンポーネントで使用したり、ページで直接インスタンス化して使用できます。
Oracle JETコンポーネントでのOracle JETコンバータの使用
ユーザー入力を受け入れるOracle JET要素(oj-input-dateなど)には、ユーザー入力の解析時に使用される暗黙的なコンバータがすでに含まれています。ただし、ページに表示するモデルからのデータを変換(逆も同様)するときに使用される明示的なコンバータを要素に指定することもできます。タイムゾーン・データを含める場合は、明示的なコンバータが必要です。
たとえば、次のコード・サンプルは、コンポーネントによって暗黙的に提供されるデフォルト・コンバータを使用するoj-input-dateコンポーネントを含むフォームの一部を示しています。強調表示されているコードは、oj-input-dateコンポーネントを示しています。
<oj-form-layout id="datetime-converter-example">
... contents omitted
<oj-input-date id="date1" value="{{date}}" name="date1"
label-hint="input date with no converter"
help.instruction="enter a date in your preferred format and we will attempt to figure it out">
</oj-input-date>
</oj-form-layout>次に、この例のビュー・モデルを作成するためのスクリプトを示します。
require(['knockout', 'ojs/ojbootstrap', 'ojs/ojknockout', 'ojs/ojdatetimepicker', 'ojs/ojlabel'],
function(ko, Bootstrap)
{
function MemberViewModel()
{
var self = this;
self.date = ko.observable();
self.datetime = ko.observable();
self.time = ko.observable();
};
Bootstrap.whenDocumentReady().then(
function ()
{
ko.applyBindings(new MemberViewModel(), document.getElementById('datetime-converter-example'));
}
);
}); ユーザーがページを実行すると、oj-input-date要素によって入力フィールドが適切な日付書式で表示されます。この例では、さらにこの要素によって、ユーザーが入力フィールドにカーソルを重ねたときにはヒントが、ユーザーが入力フィールド内をクリックしたときにはカレンダが表示されます。ユーザーが入力したデータが適切な書式でない場合は、組込みコンバータによってエラー・メッセージと適切な書式が表示されます。
解析操作または書式設定操作時にエラーが発生した場合にコンバータがスローするエラーはConverterErrorオブジェクトで表され、エラー・メッセージはMessageをダック・タイピングで型付けするオブジェクトによって表されます。Oracle JETコンバータが使用するメッセージは、Oracle JETに付属している翻訳バンドルに定義されたリソースです。Oracle JETでのメッセージの詳細は、「ユーザー支援の使用」を参照してください。
コンバータを要素のconverter属性に直接指定することもできます(存在する場合)。次のコード引用では、サンプル・フォームに別のoj-input-date要素を定義し、ページに設定されたロケールの規則に従って、ユーザーの入力をnumericの年、longの月、numericの日に変換するオプションを指定してIntlDateTimeConverterコンバータを指定します。optionsパラメータは、ECMA-402オプションを名前-値ペアとして含むオブジェクト・リテラルです。
<div class="oj-flex">
<div class="oj-flex-item">
<oj-label for="date2">input date</oj-label>
</div>
<div class="oj-flex-item">
<oj-input-date id="date2" value="{{date}}" name="date2"
help.instruction="enter a date in your preferred format and we will attempt to figure it out"
converter= '{
"type":"datetime",
"options": {"year": "numeric", "month": "long", "day": "numeric"}}'>
</oj-input-date>
</div>
</div>ユーザーがen-usロケールでページを実行すると、oj-input-date要素によって入力フィールドが表示されます。このフィールドは、ユーザーの入力日付がmmmm d, yyyy書式である必要があります。コンバータは、18/07/17 (MM/dd/yy)などの代替入力を受け入れて(妥当な場合)、変換を実行しますが、入力を解析できない場合はエラーをスローします。Oracle JETコンバータおよび寛大な解析のサポートの詳細は、「Oracle JETコンバータの寛大な解析について」を参照してください。
年代、曜日または月の短縮名の解析は、適切な値の選択する際にあいまいさが生じるためサポートされていません。たとえば、オプション{weekday: 'narrow', month: 'narrow', day: 'numeric', year: 'numeric'}を指定して日時コンバータを初期化すると、en-USロケールの場合、コンバータは、May 06, 2014と表す日付をT, M 6, 2014に書式設定します(TはTuesday (火曜日)を表します)。ユーザーがT, M 6, 2014と入力した場合、コンバータは、ユーザーが意図するのがThursday, March 6, 2014なのか、またはTuesday, May 6, 2014なのか判断できません。したがって、Oracle JETでは、ユーザー入力が短い形式または長い形式のいずれか(例: Tues, May 06, 2014)で入力される必要があります。
IntlDateTimeConverterおよびIntlNumberConverterコンポーネントのオプションの詳細は、IntlDateTimeConverterおよびIntlNumberConverterを参照してください。
Oracle JETコンバータの寛大な解析について
Oracle JETコンバータは、ユーザー入力が適切なパターンと完全に一致しない場合に、数値および日付の寛大な解析をサポートしています。パーサーは、特定のコンバータの寛大さルールに基づいて寛大な解析を実行します。
IntlDateTimeConverterでは、ユーザー入力を日付に変換するときに寛大な解析が実行され、ユーザーは次のことを実行できます。
-
関連付けられたパターンで指定されているセパレータに関係なく、任意の文字をセパレータとして入力できます。たとえば、適切な日付パターンが
y-M-dに設定されている場合、日付コンバータは次の値を有効として受け入れます:2020-06-16、2013/06-16および2020aaa06xxx16。同様に、適切な時刻パターンがHH:mm:ssに設定されている場合、コンバータは次の値を有効として受け入れます:12.05.35。 -
日と月に対して任意の位置に4桁の年を指定できます。たとえば、
11-2013-16と16-11-2013は両方とも有効な入力値です。 -
グレゴリオ暦を使用している場合は、日の値が12を超える場合にかぎり、月と日の位置を交換できます。たとえば、
y-M-dが適切な場合にユーザーが2020-16-06と入力すると、コンバータは日付を2020-06-16に自動修正します。ただし、日と月の両方が12以下の場合、日または月に関して推定は行われず、コンバータは適切なパターンに対して値を解析します。 -
文字列の任意の場所に、曜日名と月名、または短い名前と長い名前を混在させて入力できます。たとえば、適切なパターンが
E, MMM, d, yの場合、ユーザーは次のどの日付でも入力できます。Tue, Jun 16 2020 Jun, Tue 2020 16 2020 Tue 16 Jun
-
曜日を省略できます。たとえば、適切なパターンが
E, MMM d, yの場合、ユーザーはJun 16, 2020と入力でき、コンバータは日付をTuesday, Jun 16, 2020に自動修正します。無効な曜日はサポートされていません。たとえば、ユーザーがWednesday, Jun 16, 2020と入力した場合、コンバータは例外をスローします。
IntlNumberConverterでは、次のように寛大な解析をサポートしています。
-
入力が適切なパターンに一致しない場合、Oracle JETでは、入力文字列内で数値パターンを特定しようとします。たとえば、パターンが
#,##0.0で、入力文字列がabc-123.45deの場合、-123.45と解析されます。 -
通貨スタイルの場合は、通貨記号を省略できます。また、マイナス接頭辞やマイナス接尾辞のかわりに、マイナス記号を使用できます。たとえば、
patternオプションが"\u00a4#,##0.00;(\u00a4#,##0.00)"に指定されている場合、($123)、(123)および-123は-123.と解析されます。 -
スタイルがパーセントの場合は、パーセント記号を省略できます。たとえば、
5%および5は両方とも0.05と解析されます。
Oracle JETにおけるタイムゾーン・サポートの理解
デフォルトでは、oj-input-date-timeおよびoj-input-time要素、ならびにIntlDateTimeConverterはローカル・タイムゾーン入力のみをサポートしています。タイムゾーン・サポートを追加するには、ojs/ojtimezonedataモジュールを含めて、必要なパターンでコンバータを作成します。
Oracle JETは、次のパターンを使用したタイムゾーンの変換および書式設定をサポートしています。
| トークン | 説明 | 例 |
|---|---|---|
|
z、zz、zzz |
省略されたタイムゾーン名、書式サポートのみ |
PDT、PST |
|
zzzz |
完全なタイムゾーン名、書式サポートのみ |
太平洋標準時、太平洋夏時間 |
|
Z、ZZ、ZZZ |
記号、時、分 |
-0800 |
|
X |
記号、時 |
-08 |
|
XX |
記号、時、分 |
-0800 |
|
XXX |
記号、時:分 |
-08:00 |
|
VV |
タイム・ゾーンID |
アメリカ/ロサンゼルス |
次の図は、タイムゾーン・サポート用に構成した基本的なoj-input-date-time要素を示しています。この例では、Zパターンを使用してコンポーネントが変換されます。
oj-input-date-time要素は、そのconverter属性(この場合はdateTimeConverterという名前のメソッド)を使用して初期化されます。
<div id="div1">
<oj-label for="timezone">InputDateTime Timezone converter</oj-label>
<oj-input-date-time id="timezone" value={{dateTimeValue}} converter=[[dateTimeConverter]]>
</oj-input-date-time>
<br/><br/>
<p>
<oj-label for="patternSelector">Pattern options:</oj-label>
<oj-combobox-one id="patternSelector" value="{{patternValue}}">
<oj-option value="MM/dd/yy hh:mm:ss a Z">MM/dd/yy hh:mm:ss a Z</oj-option>
<oj-option value="MM-dd-yy hh:mm:ss a VV">MM-dd-yy hh:mm:ss a VV</oj-option>
<oj-option value="MM-dd-yy hh:mm X">MM-dd-yy hh:mm X</oj-option>
</oj-combobox-one>
</p>
<p>
<oj-label for="isoStrFormatSelector">isoStrFormat options:</oj-label>
<oj-combobox-one id="isoStrFormatSelector" value="{{isoStrFormatValue}}">
<oj-option value="offset">offset</oj-option>
<oj-option value="zulu">zulu</oj-option>
<oj-option value="local">local</oj-option>
</oj-combobox-one>
</p>
<br/>
<span class="oj-label">Current dateTime value is: </span>
<span><oj-bind-text value="[[dateTimeValue]]"></oj-bind-text></span>
//...contents omitted
</div>ViewModelには、dateTimeConverter()定義が含まれます。また、DateTimeConverter APIを使用するためにojs/ojconverter-datetimeモジュールを追加し、タイムゾーン・データ・ファイルにアクセスするためにojs/timezonedataモジュールをRequireJS定義に追加する必要もあります。
require(['knockout', 'ojs/ojbootstrap',
'ojs/ojconverter-datetime', 'ojs/ojknockout',
'ojs/ojdatetimepicker', 'ojs/ojselectcombobox',
'ojs/ojtimezonedata', 'ojs/ojlabel'],
function (ko, Bootstrap, DateTimeConverter,)
{
function FormatModel()
{
var self = this;
this.dateTimeValue = ko.observable("2020-06-16T20:00:00-08:00");
this.patternValue = ko.observable("MM/dd/yy hh:mm:ss a Z");
this.isoStrFormatValue = ko.observable("offset");
this.dateTimeConverter = ko.observable(
new DateTimeConverter.IntlDateTimeConverter(
{
pattern : self.patternValue(),
isoStrFormat: self.isoStrFormatValue(),
timeZone:'Etc/GMT-08:00'
}));
//Note that ojCombobox's value is always encapsulated in an array
this.patternValue.subscribe(function (newValue) {
this.dateTimeConverter
new DateTimeConverter.IntlDateTimeConverter(
{
pattern : newValue,
isoStrFormat: self.isoStrFormatValue(),
timeZone:'Etc/GMT-08:00'
}));
}.bind(this));
this.isoStrFormatValue.subscribe(function (newValue) {
this.dateTimeConverter(
new DateTimeConverter.IntlDateTimeConverter(
{
pattern : self.patternValue(),
isoStrFormat: newValue,
timeZone:'Etc/GMT-08:00'
}));
}.bind(this));
//...contents omitted
Bootstrap.whenDocumentReady().then(
function ()
{
ko.applyBindings(new FormatModel(), document.getElementById('div1'));
}
);
});oj-input-date-timeおよびoj-input-time要素にタイムゾーン・サポートを追加する方法を示すその他の例は、日時の入力 - タイムゾーンを参照してください。
Oracle JETでのカスタム・コンバータの使用
Converterを拡張またはダック・タイピングして、カスタム・コンバータをOracle JETに作成できます。さらに、カスタム・コンバータ・ファクトリを作成して、コンバータをOracle JETに登録し、コンバータのインスタンス化を容易にできます。
カスタム・コンバータは、Oracle JETコンポーネントの整合性に違反しないかぎり、Oracle JETコンポーネントで使用できます。組込みのOracle JETコンバータと同様に、ページで直接使用することもできます。
次の図は、現在日付を相対的な用語に変換するのに使用するカスタム・コンバータの例を示しています。Schedule For列では、RelativeDateTimeConverterを使用して、ページが実行されている日付をen-USロケールで変換し、Today、Tomorrow、および2日間の日付を表示します。
Oracle JETでカスタム・コンバータを作成および使用するには:
Oracle JETコンポーネント以外でのOracle JETコンバータの使用
コンバータをOracle JETコンポーネントにバインドせずに使用する場合は、選択したコンバータに対するコンストラクタを使用してコンバータを作成します。
Oracle JETクックブックには、組込みの数値コンバータおよび日時コンバータをOracle JETコンポーネントにバインドせずに直接ページで使用する方法を示すコンバータ・ファクトリのデモが含まれています。デモの図では、給与は通貨として書式設定された数値で、開始日は日付として書式設定されたISO文字列です。
次のサンプル・コードは、数値をcurrencyとして書式設定するsalaryConverter、およびdate書式スタイルとmedium日付書式を使用して開始日を書式設定するdateConverterを定義するviewModelの一部を示しています。
require(['knockout', 'ojs/ojbootstrap, 'ojs/ojconverter-number',
'ojs/ojconverter-datetime', 'ojs/ojknockout',],
function(ko, Bootstrap, NumberConverter, DateTimeConverter)
{
function DemoViewModel()
{
var self = this;
// for salary fields
var salOptions = {style: 'currency', currency: 'USD'};
var salaryConverter = new NumberConverter.IntlNumberConverter(salOptions);
self.amySalary = ko.observable(salaryConverter.format(125475.00));
self.garySalary = ko.observable(salaryConverter.format(110325.25));
// for date fields
var dateOptions = {formatStyle: 'date', dateFormat: 'medium'};
var dateConverter = new DateTimeConverter.IntlDateTimeConverter(dateOptions);
self.amyStartDate = ko.observable(dateConverter.format("2020-01-02"));
self.garyStartDate = ko.observable(dateConverter.format("2009-07-25"));
... contents omitted
}); 次のコード・サンプルは、amySalary、amyStartDate、garySalary、garyStartDateに含まれる書式設定された値に表示出力を設定するマークアップの一部を示しています。
<td>
<div class="oj-panel oj-panel-alt4 demo-panel-customizations">
<h3 class="oj-header-border">Amy Flanagan</h3>
<img src="images/Amy.png" alt="Amy">
<p>Product Manager</p>
<span style="white-space:nowrap;"><b>Salary</b>:
<span>
<oj-bind-text value="[[amySalary]]"></oj-bind-text>
</span>
</span>
<br />
<span style="white-space:nowrap;"><b>Joined</b>:
<span>
<oj-bind-text value="[[amyStartDate]]"></oj-bind-text>
</span>
</span>
<br />
</div>
</td>
<td>
<div class="oj-panel oj-panel-alt2 demo-panel-customizations">
<h3 class="oj-header-border">Gary Fontaine</h3>
<img src="images/Gary.png" alt="Gary">
<p>Sales Associate</p>
<span style="white-space:nowrap;"><b>Salary</b>:
<span>
<oj-bind-text value="[[garySalary]]"></oj-bind-text>
</span>
</span>
<br />
<span style="white-space:nowrap;"><b>Joined</b>:
<span>
<oj-bind-text value="[[garyStartDate]]"></oj-bind-text>
</span>
</span>
<br />
</div>
</td>Oracle JETバリデータについて
Oracle JETバリデータは、コール元がバリデータ・インスタンスをカスタマイズできるようにするプロパティを提供します。プロパティはバリデータのAPIの一部として記述されます。コンバータのインスタンスを1つしか要素に設定できないコンバータとは異なり、ページ作成者は1つ以上のバリデータを要素に関連付けることができます。
ユーザーが要素と対話してその値を変更すると、その要素に関連付けられたバリデータが順に実行されます。値が検証ルールに違反する場合、value属性は移入されず、バリデータによって、エラーが発生した要素が強調表示されます。
バリデータは、Oracle JET要素で使用したり、ページで直接インスタンス化して使用できます。
Oracle JETコンポーネントでのOracle JETバリデータの使用
Oracle JET編集可能要素(oj-input-text、oj-input-dateなど)は、サポートする特定の属性(required、min、maxなど)に基づいて暗黙的にバリデータを設定したり、コンポーネントのvalidators属性を使用して1つ以上のバリデータを設定する方法を提供して明示的にバリデータを設定できます。Oracle JETコンバータと同様に、validators属性はJSON配列表記または実際のバリデータ・インスタンスの配列を使用して指定できます。
たとえば、次のコード・サンプルは、コンポーネントによって暗黙的に提供されるデフォルト・バリデータを使用するoj-input-date要素を含むフォームの一部を示しています。強調表示されているコードは、oj-input-date要素に設定されたHTML5属性を示しています。oj-input-dateは、min属性を読み取ると、暗黙的なDateTimeRangeValidatorを作成します。
<oj-form-layout id="validator-example" label-edge="inside">
<oj-input-date id="dateTimeRange1" value="{{dateValue1}}" min="2000-01-01T08:00:00.000"
help.instruction="Enter a date that falls in the current millenium and not greater than today's date."
max= '[[todayIsoDate]]' label-hint="'min' attribute and 'max' option">
</oj-input-date>
</oj-form-layout>次に、この例のビュー・モデルを作成するためのスクリプトを示します。
require(['knockout', 'ojs/ojbootstrap', 'ojs/ojconverterutils-i18n',
'ojs/ojasyncvalidator-datetimerange', 'ojs/ojconverter-datetime',
'ojs/ojknockout', 'ojs/ojinputnumber', 'ojs/ojinputtext',
'ojs/ojdatetimepicker', 'ojs/ojlabel', 'ojs/ojformlayout'],
function(ko, Bootstrap, ConverterUtilsI18n, AsyncDateTimeRangeValidator, DateTimeConverter)
{
function DemoViewModel()
{
var self = this;
self.dateValue1 = ko.observable();
self.todayIsoDate = ko.observable(ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date()));
};
Bootstrap.whenDocumentReady().then(
function ()
{
ko.applyBindings(new DemoViewModel(), document.getElementById('validator-example'));
}
);
}); ユーザーがページを実行すると、oj-input-date要素によって入力フィールドが適切な日付書式で表示されます。要素に設定されたhelp.instruction属性は、カーソルを重ねたときのツールチップとして表示されます。ユーザーがフィールドをクリックすると、暗黙的に作成されたDateTimeRangeValidatorが提供するバリデータ・ヒントが、カレンダ・ポップアップとともにノート・ウィンドウに表示されます。ユーザーが入力したデータが適切な範囲内でない場合は、組込みバリデータによってエラー・メッセージと適切な範囲が表示されます。
検証が失敗したときにOracle JETバリデータがスローするエラーはValidatorErrorオブジェクトで表され、エラー・メッセージはMessageをダック・タイピングで型付けするオブジェクトで表されます。Oracle JETバリデータがエラーをスローするときに使用するメッセージとヒントは、Oracle JETに付属している翻訳バンドルに定義されたリソースです。Oracle JETでのメッセージの詳細は、「ユーザー支援の使用」を参照してください。
要素のvalidators属性にバリデータを指定することもできます(存在する場合)。次のコード・サンプルでは、別のoj-input-date要素をサンプル・フォームに追加し、DateTimeRangeValidatorバリデータ(dateTimeRange)をvalidators属性に指定する関数をコールします。
<oj-form-layout id="validator-example" label-edge="inside">
<oj-input-date id="dateTimeRange2" value="{{dateValue2}}"
validators="[[validators]]"
label-hint="'validators' attribute">
</oj-input-date>
</oj-form-layout>次の強調表示されているコードは、有効な最小日付と最大日付を設定するオプションおよびユーザーがフィールドにフォーカスを設定したときに表示されるヒントが設定された、定義済の関数などのviewModelへの追加コードを示しています。
require(['knockout', 'ojs/ojbootstrap', 'ojs/ojconverterutils-i18n',
'ojs/ojasyncvalidator-datetimerange', 'ojs/ojconverter-datetime',
'ojs/ojknockout', 'ojs/ojinputnumber', 'ojs/ojinputtext',
'ojs/ojdatetimepicker', 'ojs/ojlabel', 'ojs/ojformlayout'],
function(ko, Bootstrap, ConverterUtilsI18n, AsyncDateTimeRangeValidator, DateTimeConverter)
{
function DemoViewModel()
{
var self = this;
self.dateValue1 = ko.observable();
self.todayIsoDate = ko.ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date()));
self.milleniumStartIsoDate = ko.observable(ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date(2000, 00, 01)));
self.validators = ko.computed(function()
{
return [{
new AsyncDateTimeRangeValidator({
max: this.todayIsoDate(),
min: this.milleniumStartIsoDate(),
hint: {
'inRange': 'Custom Hint: Enter a date that falls in the current millennium.'
},
messageSummary: {'rangeUnderflow': 'Custom: Oops!', 'rangeOverflow': 'Custom: Oops!'},
converter: new DateTimeConverter.IntlDateTimeConverter({"day":"2-digit","month":"2-digit","year":"2-digit"})
})
];
}.bind(this));
};
Bootstrap.whenDocumentReady().then(
function ()
{
ko.applyBindings(new DemoViewModel(), document.getElementById('validator-example'));
}
);
}); ユーザーがen-USロケールでページを実行すると、oj-input-date要素によって入力フィールドが表示されます。このフィールドは、ユーザーの入力日付が01/01/00から現在日付の間である必要があります。日付値をフィールドに入力するとき、日付コンバータは、日付を明確に解析できる場合にかぎり代替入力を受け入れます。これによって、エンド・ユーザーが日付値を入力するときの許容範囲が大きく広がります。
たとえば、1-2-3と入力すると、Dateは2003年1月2日に変換されます。Date値が、バリデータに設定されたDate範囲内である場合も、その値は受け入れられます。検証に失敗すると、コンポーネントでエラーが表示されます。
Oracle JET要素では、regExpバリデータも使用できます。正規表現パターンにバックスラッシュが必要で、Oracle JET要素内に式を指定する場合、二重のバックスラッシュを使用する必要があります。たとえば:
<oj-input-text
…
validators='[{
"type": "regExp",
"options": {
"pattern": "\\d+(\\.\\d\{1,2})?",
"messageDetail": "Enter a valid number with up to 2 digits of decimal"
}
}]'>
</oj-input-text>各バリデータが受け入れるオプションは、『Oracle® JavaScript Extension Toolkit (Oracle JET) APIリファレンス』に指定されています。
Oracle JETクックブックには、この項で使用される完全な例に加え、日付制限、長さ、数値範囲、正規表現および必須フィールドに対する組込みバリデータを示す例があります。詳細は、バリデータを参照してください。
Oracle JETコンポーネントの検証の詳細は、「Oracle JET編集可能コンポーネントでの検証およびメッセージ機能の理解」を参照してください。
Oracle JETでのカスタム・バリデータの使用
Validatorを拡張またはダック・タイピングして、カスタム・バリデータをOracle JETに作成できます。
カスタム・バリデータは、Oracle JETコンポーネントの整合性に違反しないかぎり、Oracle JETコンポーネントで使用できます。組込みのOracle JETバリデータと同様に、ページで直接使用することもできます。Oracle JETでのメッセージの詳細は、「messages-custom属性の使用」を参照してください。
次の図は、パスワード入力の検証に使用するカスタム・バリデータの例を示しています。ユーザーのパスワードが一致しない場合は、バリデータによってエラー・メッセージが表示されます。
Oracle JETでカスタム・バリデータを作成および使用するには:
非同期バリデータについて
Oracle JET入力コンポーネントでは、validators属性を介した非同期サーバー側検証をサポートしています。つまり、フォームを送信したり、ページをリフレッシュすることなく、サーバー・データに対する入力値をチェックできます。
たとえば、新しいユーザー・データを収集するフォームで、e-mailフィールドに対してすでに入力値が登録されているかをチェックするバリデータを設定できます。
また、揮発性データに基づいてチェックする数値範囲バリデータを設定することもできます。たとえば、e-コマースのWebサイトで、ユーザーのカートを利用可能在庫に基づいてチェックし、商品の利用可能在庫がなければ、ユーザーが支払のためにカートを送信する前にそれを通知することができます。
Oracle JET Cookbookには、validators属性およびダミー・データを使用してサーバー側検証をシミュレーションするサンプルが用意されています。
次のコードはoj-input-text要素を示しています。ここでは、validators属性がJavaScriptコードでvalidatorsおよびasyncValidatorオブザーバブルに設定されています。非同期バリデータの作成に必要なAPI規約に準拠するためには、validators属性がダックタイプAsyncValidatorである必要があります。
<oj-form-layout id="fl1" label-edge="top">
<oj-input-text id="text-input" required
label-hint="Quantity Limit"
on-valid-changed="[[validChangedListener]]"
validators="[[validators, asyncValidator]]"
value="{{quantityLimit}}"
converter= '{
"type":"number",
"options": {"style": "currency", "currency": "USD",
"currencyDisplay": "code", "pattern": "¤ ##,##0.00"}}'>
</oj-input-text>
</oj-form-layout>次のJavaScriptコードは、asyncValidatorオブジェクトに作成された、Promiseを返す数値範囲バリデータを示しています。
self.asyncValidator = {
// 'validate' is a required method
// that is a function that returns a Promise
validate: function (value) {
// used to format the value in the validation error message.
var converterOption =
{
style: 'currency',
currency: 'USD',
currencyDisplay: 'code',
pattern: '¤ ##,##0.00'
};
// As of JET 8.0, by default JET's validators are AsyncValidators.
var numberRangeValidator =
new AsyncNumberRangeValidator(
{ min: 100, max: 10000, converter: converterOption });
// eslint-disable-next-line no-undef
return new Promise(function (resolve, reject) {
// We could go to the server and check the
// user's credit score and based on that
// credit score use a specific number range validator.
// We mock a server-side delay
setTimeout(function () {
numberRangeValidator.validate(value).then(
// eslint-disable-next-line no-unused-vars
function (result) {
/* handle a successful result */
resolve();
},
function (e) {
/* handle an error */
var converterInstance =
new NumberConverter.IntlNumberConverter(converterOption);
reject({
detail: e + ' Your value is ' +
converterInstance.format(value) + '.'
});
});
}, 1000);
});
},
// 'hint' is an optional field that returns a Promise
'hint': new Promise(function(resolve, reject) {
...
})
}; ノート:
JavaScriptにおけるPromiseオブジェクトとは、まだ利用可能になっていない可能性があるが、将来のある時点で解決される値を表しています。非同期検証では、AsyncValidator.validate()関数は、検証に合格すればBoolean trueに評価されるPromiseを返し、検証に合格しなければErrorを返します。詳細は、 ojInputTextのvalidators属性の項を参照するか、「Promise (MDN)」を参照してください。
完全なCookbookサンプルは、「非同期バリデータ」を参照してください。