37.5 apex.item

apex.item APIによって、Application Expressのアイテム関連機能に単一のインタフェースが提供されます。このAPIでApplication Expressアイテム・オブジェクトを戻し、それをアイテム関連のファンクションおよびプロパティにアクセスするために使用できます。アイテム・オブジェクトは、ページ・アイテムまたは列アイテムに適用できます。ページ・アイテムとは、任意のリージョンでセッション・ステートによって支持されるページ上のアイテムです。列アイテムは、編集可能な列をサポートする対話グリッドなどのリージョン・タイプによって作成されます。列アイテムの状態。その値と、リージョンの編集コンテキストに応じた変更を含む。

• apex.item
  
• addValue
  
• disable
  
• displayValueFor
  
• enable
  
• getValidity
  
• getValidationMessage
  
• getValue
  
• hide
  
• isChanged
  
• isDisabled
  
• isEmpty
  
• アイテム・オブジェクトのプロパティ
  
• setFocus
  
• setStyle
  
• setValue
  
• show
  
• apex.item.create
  

37.5.1 apex.item

このAPIでApplication Expressアイテム・オブジェクトを戻し、それをアイテム関連のファンクションおよびプロパティにアクセスするために使用できます。

プラグイン開発者は、apex.item.createをオーバーライドで呼び出すことによって、apex.itemネームスペースに定義された動作の多くをオーバーライドできます。

パラメータ

表37-11 pNdのパラメータ

名前	タイプ	説明
pNd	DOMノード|文字列	Application Expressのアイテム名またはDOMノード。このパラメータは、ページ・アイテムか列アイテムいずれかを参照できます。

戻り値

Application Expressのアイテム・オブジェクトを戻し、このオブジェクトが、アイテム固有のファンクションへのアクセスに使用されます。たとえば、getValue、setValueなどです。

例

これは、単独では使用されず、次に示す各APIで説明されているように、アイテム固有のファンクションおよびプロパティにアクセスするために使用されます。

参照:

apex.item.create

37.5.2 addValue

複数の値をサポートするApplication Expressアイテムに値を追加します。

パラメータ

表37-12 addValueのパラメータ

名前	タイプ	説明
pValue	String	追加される値。

例

この例では、P1_ITEMと呼ばれるページ・アイテムにおいて、現在選択された値に値100が追加されます。

apex.item( "P1_ITEM" ).addValue('100') ;

37.5.3 disable

アイテム・タイプを考慮してApplication Expressのアイテム値を無効にし、編集不可にします。

パラメータ

なし

例

この例では、P1_ITEMと呼ばれるページ・アイテムは無効化され、編集不可となります。

apex.item( "P1_ITEM" ).disable() ;

37.5.4 displayValueFor

Application ExpressアイテムのpValueによって指定される値に対応する表示値を戻します。アイテム・タイプに、この値と違う表示値がない場合はpValueが戻されます。これは、その値が表示値であることを意味します。表示値はあるが、想定されるすべての値と表示値を利用できないアイテム・タイプの場合、このファンクションはpValueがアイテムの現在値である場合にのみ機能します。ネイティブ・アイテムの場合、これが適用されるのはアイテム・タイプPopup LOVのみで、属性はInput Field" = "Not Enterable, Show Display Value and Store Return Valueです。値をすべて利用できる選択リストなどのアイテム・タイプの場合、pValueが有効な値でなければpValueが戻されます。

パラメータ

表37-13 displayValueForのパラメータ

名前	タイプ	説明
pValue	String	このアイテムで有効な値。

戻り値

前述した所定のpValueに対応する文字列表示値。

例

この例では、P1_ITEMという選択リスト・アイテムから表示値を取得し、アラートでそれを表示します。

alert( "The correct answer is: " + apex.item( "P1_ITEM" ).displayValueFor( "APPLES" ) );

37.5.5 enable

アイテム・タイプを考慮してApplication Expressのアイテム値を有効化し、編集可能にします。

パラメータ

なし

例

この例では、P1_ITEMと呼ばれるページ・アイテムは有効化され、編集可能となります。

apex.item( "P1_ITEM" ).enable() ;

37.5.6 getValidity

Application ExpressアイテムのHTML5制約検証APIによって定義されるValidityStateオブジェクトを戻します。プラグイン・アイテムで独自の検証が実装される場合、オブジェクトにはHTML5で定義されるフィールドの一部が含まれない可能性があります。少なくとも、有効なプロパティが必要です。HTML5検証をサポートしないアイテムは、有効とみなされます。

このファンクションは、実際にはアイテム値を検証しません。多くのアイテム・タイプについて、パターンなどのHTML5制約属性を追加すると自動的に検証を実行できます。検証は、HTML5制約検証APIを使用して実行できます。

開発者がこのファンクションをコールすることは、ほとんどありません。クライアント側の検証機能によって内部的に使用されます。アイテム・プラグイン開発者は、各プラグインでこの機能が動作することを確認する必要があります。

パラメータ

なし

戻り値

前述したValidityStateオブジェクト。

例

次の例では、P1_ITEMというアイテムが有効でない場合に、アラート・ダイアログでメッセージを表示します。

var item = apex.item( "P1_ITEM" );
if ( !item.getValidity().valid ) {
    alert( "Error: " + item.getValidationMessage() );
}

37.5.7 getValidationMessage

Application Expressが有効でない場合には検証メッセージを戻し、それ以外の場合には空文字列を戻します。

このメッセージは、要素のvalidationMessageプロパティに由来します。APEX拡張機能によって、カスタム・メッセージを指定できます。これはdata-valid-messageというカスタム属性を追加して、要素のvalidationMessageをオーバーライドします。アイテムにこの属性があれば、アイテムが有効でない場合にその値が戻されます。名前からもわかるように、メッセージのテキストには、問題の状況ではなく、有効な入力として何が必要かを説明する必要があります。

パラメータ

なし

戻り値

アイテムが有効でない場合には検証メッセージ、それ以外の場合には空文字列。

例

このファンクションの例は、getValidityの例を参照してください。

37.5.8 getValue

現在のアイテム・タイプを考慮して、ページにおけるApplication Expressのアイテムの現行値を戻します。これはセッション・ステートからアイテムの現行値を戻すのではなく(同じである可能性もありますが)、現在のページ上にある値を戻します。

アイテム値を戻す.getValue(). $v( pNd )に関連するファンクションは2つあり、この形式でアイテム値は送信されます。これは単一の値か、またはアイテムが複数の値をサポートする場合は、: (コロン)で区切られた値リストとなります。$v2( pNd )ファンクションもあり、これは.getValue()へのショートカットで、単一の値または値の配列のいずれかを戻します。

パラメータ

なし

戻り値

単一の文字列値か、アイテムが複数の値をサポートする場合(たとえば「選択リスト」の「複数選択を許可」属性を「はい」または「シャトル」・ネイティブ・アイテム・タイプに設定)は、文字列値の配列のいずれかを戻します。

例

この例では、P1_ITEMと呼ばれるページ・アイテムの現行値は、アラートで表示されます。

alert( "P1_ITEM value = " +  apex.item( "P1_ITEM" ).getValue()  );

37.5.9 hide

アイテム・タイプを考慮して、Application Expressのアイテム値を非表示にします。.hide()ファンクションを使用するときは、次を理解することが重要です。

• 非表示となっているアイテムが、表のレイアウトを使用しているページ(このページが、「グリッド・レイアウト・タイプ」が「HTML表」に設定されているページ・テンプレートを参照している)でレンダリングされ、非表示にするためのコールで表の行全体の非表示を指定すると(pHideRow = TRUE)、このアイテムに関連するすべてがその行に含まれると見なされ、行全体が非表示になります。

• 非表示となっているアイテムが、表のレイアウトを使用しているページでレンダリングされ、非表示にするためのコールで表の行全体の非表示を指定しないと(pHideRow = FALSE、または指定しない)、ファンクションは、FOR属性がアイテムのIDに一致する場合に、そのアイテムのラベルを非表示にしようとします。

• 非表示となっているアイテムが、グリッド・レイアウトを使用しているページ(このページが「グリッド・レイアウト・タイプ」が「固定列数」または「可変列数」に設定されているページ・テンプレートを参照している)でレンダリングされ、このアイテムが既知のIDのある「フィールド・コンテナ」要素を含む「ラベル」・テンプレートを参照している場合(「フィールド・コンテナ」→「「ラベルの前」とアイテム」属性にid="#CURRENT_ITEM_CONTAINER_ID#"のHTML要素が含まれる場合)、このアイテムに関連するすべてが「フィールド・コンテナ」に含まれると見なされ、非表示になります。

• アイテムが列アイテムの場合、その列値のみが非表示になります。厳密な動作は、リージョンのタイプによって異なります。対話グリッドでの例では、列全体ではなく、セルの内容のみが非表示になります。

パラメータ

表37-14 hideのパラメータ

名前	タイプ	説明
pHideRow	ブール	このパラメータはオプションです。デフォルト値はfalseです。trueの場合、表の同じ行(TR)が非表示となります。このパラメータは、列アイテムではサポートされません。その動作は未定義です。アイテムが表のレイアウトを使用しているページにある場合(ページが「グリッド・レイアウト・タイプ」が「HTML表」に設定されているページ・テンプレートを参照している場合)にのみ、適用可能です。

例

この例では、P1_ITEMと呼ばれるページ・アイテムは非表示になります。P1_ITEMがグリッド・レイアウトを使用しているページ上にあり、そのアイテムが、「フィールド・コンテナ」要素と既知のIDが含まれる「ラベル」・テンプレートを参照している場合(詳細については前述のとおり)、このコンテナ要素は非表示になります。その他の場合は、アイテムおよび対応するラベルは非表示になります。

apex.item( "P1_ITEM" ).hide();

この例では、P1_ITEMと呼ばれるページ・アイテムが含まれる表の行全体(TR)が非表示になります(pHideRow = TRUEのため)。表の行全体の非表示は、表のレイアウトを使用するページ上でのみ使用してください。P1_ITEMがグリッド・レイアウトを使用しているページ上にある場合、pHideRow = TRUEの引き渡しが機能せず、正しくない表の行が誤って非表示になり、ページ・レイアウトに悪影響が生じます。

apex.item( "P1_ITEM" ).hide(true);

37.5.10 isChanged

Application Expressアイテムの現在値が変更されている場合はtrueを戻し、それ以外の場合はfalseを戻します。開発者がこのファンクションをコールすることは、ほとんどありません。未保存の変更がある場合の警告機能によって、内部的に使用されます。アイテム・プラグイン開発者は、未保存の変更がある場合の警告機能に各プラグインが対応するように、各プラグインの動作を確認する必要があります。

パラメータ

なし

戻り値

値が変更されている場合はtrue、それ以外の場合はfalse。

例

次の例では、アイテムP1_ITEMの値が変更されているかどうかを判定します。

If ( apex.item( "P1_ITEM" ).isChanged() ) {
    // do something
}

37.5.11 isDisabled

アイテムの無効な状態を返します。

パラメータ

なし

戻り値

Application Expressアイテムが無効な場合はtrue、それ以外の場合はfalse。

例

この例では、無効化されていない場合のみアイテムの値を取得します。

var value = null;
if ( !apex.item( "P1_ITEM" ).isDisabled() ) {   
    value = apex.item( "P1_ITEM" ).getValue(); }

37.5.12 isEmpty

Application Expressのアイテムが空かどうかでtrueまたはfalseを戻します(空白、タブ、フォーム・フィードなどの空白文字のみで構成されるアイテム値を空とみなします)。また、アイテム・タイプで「LOV」が使用されているかどうか、および「LOV」で「NULL戻り値」が定義されているかどうかについても考慮します。この場合、「NULL戻り値」は、アイテムが空である場合にアサートするために使用されます。

パラメータ

なし

戻り値

Application Expressアイテムが空の場合はtrue、それ以外の場合はfalse。

例

この例では、P1_ITEMと呼ばれるページ・アイテムが空かどうかを.isEmpty()へのコールによって確認し、空の場合はアラートを表示します。

if( apex.item( "P1_ITEM" ).isEmpty()  ) {
  alert( "P1_ITEM empty!" );
}

37.5.13 アイテム・オブジェクトのプロパティ

apex.itemから戻されるアイテム・オブジェクトのプロパティは、次の表に示すとおりです。

パラメータ

表37-15 アイテム・オブジェクトのプロパティ

名前	説明
id	Application Expressアイテムのidプロパティは、アイテムのDOM要素のIDを示します。
node	Application Expressアイテムのnodeプロパティは、アイテムのDOM要素を示します。アイテムが無効な場合、値はfalseです。

例

次のコードは、Application ExpressアイテムP1_OPTIONAL_ITEMが存在するかどうかをチェックしてから、その値を設定します。アイテムが存在しない可能性がある場合には、これに似たコードを使用します。

var item = apex.item( "P1_OPTIONAL_ITEM" );
if ( item.node ) {
    item.setValue( newValue );
}

37.5.14 setFocus

特定のアイテムがどのようにフォーカスを受け取るように設計されているかを考慮し、ユーザーのフォーカスをApplication Expressのアイテムに移動します。

パラメータ

なし

例

この例では、ユーザーのフォーカスはP1_ITEMと呼ばれるページ・アイテムに設定されています。

apex.item( "P1_ITEM" ).setFocus();

37.5.15 setStyle

特定のアイテムがどのようにスタイル設定されるように設計されているかを考慮し、Application Expressのアイテムにスタイルを設定します。

注意:

setStyleの使用は推奨されません。CSSクラスを追加または削除し、CSSルールを使用してアイテムのスタイルを制御することをお薦めします。また、ネイティブおよびプラグイン・アイテムの正確なマークアップは、リリースごとに変わる可能性があることにも注意してください。

パラメータ

表37-16 setStyleのパラメータ

名前	タイプ	説明
pPropertyName	String	設定されるCSSプロパティ名。
pPropertyValue	String	CSSプロパティを設定するために使用される値。

例

この例では、CSSプロパティのcolorが、P1_ITEMと呼ばれるページ・アイテムに対してredに設定されています。

apex.item( "P1_ITEM" ).setStyle( "color", "red" );

37.5.16 setValue

アイテム・タイプを考慮して、Application Expressのアイテム値を設定します。このファンクションは、ページ上のApplication Expressアイテムの現行値を設定し、アイテムのセッション・ステートにおける現行値は設定しません。これによってコール元は、必要に応じて、設定されるアイテムにchangeイベントを抑止することもできます。

.setValue()へのショートカットについては、$s( pNd, pValue, pDisplayValue, pSuppressChangeEvent )ファンクションに関する説明を参照してください。

パラメータ

表37-17 setValueのパラメータ

名前	タイプ	説明
pValue	文字列|配列	設定される値。複数の値をサポートするアイテムの場合(例: Shuttle)、1つ文字列値配列を渡すことで、複数の値を一度に設定できます。
pDisplayValue	String	戻り値が異なる場合に、ページ・アイテムの表示値を設定するために使用されるオプションのパラメータ。たとえば、アイテム・タイプPopup LOVがInput Field = Not Enterable, Show Display Value and Store Return Valueの場合、この値でInput Fieldが設定されます。このアイテムの非表示の戻り値フィールドを設定するには、pValueの値を使用します。
pSuppressChangeEvent	ブール	このパラメータはオプションです。指定されていない場合のデフォルトは、falseです。設定されているアイテムがchangeイベントによってトリガーされないようにするには、trueを渡します。

例

この例では、P1_ITEMと呼ばれるページ・アイテムの値は、10に設定されます。pSuppressChangeEventが渡されていないため、デフォルトの動作である、P1_ITEMをトリガーするchangeイベントが発生します。

apex.item( "P1_ITEM" ).setValue( "10" );

この例でP1_ITEMは、Input Field = Not Enterable, Show Display Value and Store Return ValueとなっているPopup LOVのページ・アイテムであり、Input Fieldに設定されます。P1_ITEMの表示値はSALESに設定され、非表示の戻り値が10に設定されます。pSuppressChangeEventパラメータにtrueが渡されているため、P1_ITEMに関してchangeイベントはトリガーされません。

apex.item( "P1_ITEM" ).setValue( "10", "SALES", true );

37.5.17 show

アイテム・タイプを考慮して、Application Expressのアイテム値を表示します。.show()ファンクションを使用するときは、次を理解することが重要です。

• 表示となっているアイテムが、表のレイアウトを使用しているページ(このページが、「グリッド・レイアウト・タイプ」が「HTML表」に設定されているページ・テンプレートを参照している)でレンダリングされ、表示するためのコールで表の行全体の表示を指定すると(pShowRow = TRUE)、このアイテムに関連するすべてがその行に含まれると見なされ、行全体が表示されます。

• 表示となっているアイテムが、表のレイアウトを使用しているページでレンダリングされ、表示するためのコールで表の行全体の表示を指定しないと(pShowRow = FALSE、または指定しない)、ファンクションは、FOR属性がアイテムのIDに一致する場合に、そのアイテムのラベルを表示しようとします。

• 表示となっているアイテムが、グリッド・レイアウトを使用しているページ(このページが「グリッド・レイアウト・タイプ」が「固定列数」または「可変列数」に設定されているページ・テンプレートを参照している)でレンダリングされ、このアイテムが既知のIDのある「フィールド・コンテナ」要素を含む「ラベル」・テンプレートを参照している場合(「フィールド・コンテナ」→「「ラベルの前」とアイテム」属性にid="#CURRENT_ITEM_CONTAINER_ID#"のHTML要素が含まれる場合)、このアイテムに関連するすべてが「フィールド・コンテナ」に含まれるとみなされ、表示になります。

• アイテムが列アイテムの場合、その列値のみが表示されます。厳密な動作は、リージョンのタイプによって異なります。対話グリッドでの例では、列全体ではなく、セルの内容のみが表示されます。

パラメータ

表37-18 showのパラメータ

名前	タイプ	説明
pShowRow	ブール	このパラメータはオプションです。指定されていない場合のデフォルトは、falseです。trueの場合、表の同じ行(TR)が表示となります。このパラメータは、列アイテムではサポートされません。その動作は未定義です。アイテムが表のレイアウトを使用しているページにある場合(ページが「グリッド・レイアウト・タイプ」が「HTML表」に設定されているページ・テンプレートを参照している場合)にのみ、適用可能です。

例

この例では、P1_ITEMと呼ばれるページ・アイテムが表示されます。P1_ITEMがグリッド・レイアウトを使用しているページ上にあり、そのアイテムが、「フィールド・コンテナ」要素と既知のIDが含まれる「ラベル」・テンプレートを参照している場合(詳細については前述のとおり)、このコンテナ要素は表示されます。その他の場合には、アイテムおよび対応するラベルが表示されます。

apex.item( "P1_ITEM" ).show();

この例では、P1_ITEMと呼ばれるページ・アイテムが含まれる表の行全体(TR)が表示されます(pShowRow = TRUEのため)。表の行全体の表示は、表のレイアウトを使用するページ上でのみ使用してください。P1_ITEMがグリッド・レイアウトを使用しているページ上にある場合、pShowRow = TRUEの引き渡しが機能せず、正しくない表の行が誤って表示され、ページ・レイアウトに悪影響が生じます。

apex.item( "P1_ITEM" ).show(true);

37.5.18 apex.item.create

このファンクションは、アイテム・プラグインの開発者専用です。そのアイテムについて、プラグイン固有の実装を提供します。これは、プラグイン・アイテム・タイプに、Application Expressのクライアント側機能に関する組込みアイテムをシームレスに統合するために必要です。

パラメータ

表37-19 apex.item.createのパラメータ

名前	タイプ	説明
pName	DOMノード|文字列	Application Expressのページ・アイテム名またはDOMノード。このパラメータは、ページ・アイテムか列アイテムいずれかを参照できます。
pItemImpl	Object	Application Expressアイテムのオブジェクト動作をカスタマイズする際に必要な機能を提供するプロパティを持つオブジェクト。apex.itemによって戻されるオブジェクトには、多くのページ・アイテム、特に標準フォーム要素を使用するアイテムに適した各ファンクションのデフォルト実装があります。apex.itemのファンクションごとに、使用するアイテム・プラグインでデフォルトの処理が適切かどうかを確認する必要があります。適切でない場合は、このpItemImplオブジェクトを使用して、対応するファンクションを独自に実装できます。ファンクションが省略されている場合は、デフォルトの動作が使用されます。 pItemImplには、次のいずれかのプロパティを含めることができます。 displayValueFor( pValue ) enable() getPopupSelector() getValidity() getValue() setValue( pValue, pDisplayValue ) disable() show() hide() isChanged() isDisabled() addValue() nullValue() setFocusTo setStyleTo afterModify() loadingIndicator( pLoadingIndicator$ )

表37-20 pItemImplパラメータのプロパティ

名前	説明
displayValueFor( pValue )	指定したpValueに対応する文字列表示値を戻すファンクションを指定します。
enable()	アイテムを有効化するためのファンクションを指定します(これによって、デフォルトのページ・アイテムの処理がオーバーライドされます)。これは、有効化も必要な複合要素からアイテムが構成されている場合、または再利用しようとする独自の有効化メソッドをすでに保有しているウィジェットにアイテムが基づいている場合などに、役立つ可能性があります。アイテムを正しく有効化できるようにするということは、たとえばアイテムを有効化するために「動的アクション」の「有効化」アクションを使用する場合に、Application Expressのクライアント側機能に関する特定のアイテムが動作していることになります 注意: このファンクションが定義されている場合でも、デフォルト処理によって常に.afterModify()ファンクションと関連するロジックが処理されるため、プラグイン開発者が関係する範囲外となります。 このファンクションを定義する方法の詳細は、enableを参照してください。
getPopupSelector()	アイテムによって使用されるポップアップを検索するCSSセレクタを戻すファンクションを指定します。ポップアップを使用するプラグイン・アイテム・タイプ(ドキュメントの末尾近くに追加され、入力アイテムの付近にフローティング状態で表示されるdiv)には、ポップアップのトップ・レベル要素を検索するCSSセレクタを指定する必要があります。こうすると、対話グリッド・リージョンで、あるいはフォーカスとポップアップを調整する必要があるその他のリージョンで、そのアイテム・タイプを使用できます。デフォルト実装はnullを返します。 また、トップ・レベルのポップアップ要素は、フォーカス可能に指定する(tabindex = -1属性を持つ)必要があります。 対話グリッドでポップアップの最適な動作を確保するには、ポップアップに次の特性が必要です。 なんらかの方法でフォーカスを取得できる フォーカスがあるとき、[Esc]で閉じる アタッチ先の要素がフォースを失うと閉じる 閉じたときには、ポップアップを開いた要素にフォーカスを戻す ポップアップ内で循環し、最後にはポップアップを開いた要素に戻るようにタブ・ストップを管理する
getValidity()	検証オブジェクトを戻すファンクションを指定します。戻されるオブジェクトには、少なくともブール型の有効なプロパティが必要です。HTML5のValidityStateオブジェクトに定義されているプロパティを含めることもできます。デフォルト実装は、存在する場合にはアイテム要素の検証オブジェクトを戻し、それ以外の場合には{ valid: true }を戻します。 getValidity、またはこのファンクションを定義する方法の詳細を参照してください。
getValue()	アイテム値を取得するためのファンクションを指定します(これによって、デフォルトのページ・アイテムの処理がオーバーライドされます)。アイテムが値を正しく戻すようにするということは、たとえばアイテムでWhen条件を評価するための「動的アクション」、またはアイテムの値を取得するためにJavaScriptファンクション$vをコールする場合などに、Application Expressのクライアント側機能に関する特定のアイテムが動作しているということです。 このファンクションを定義する方法の詳細は、getValueを参照してください。
setValue( pValue, pDisplayValue )	アイテム値を設定するためのファンクションを指定します(これによって、ページ・アイテムのデフォルトの処理がオーバーライドされます)。アイテムが値を正しく設定できるようにするということは、たとえば「動的アクション」の「値の設定」アクションを使用してアイテム値を設定する場合や、JavaScriptファンクション$sをコールしてアイテムの値を設定する場合などに、Application Expressのクライアント側機能に関する特定のアイテムが動作しているということです。 注意: このファンクションが定義されている場合でも、デフォルト処理によって常に.afterModify()ファンクションおよびpSuppressChangeEventパラメータと関連するロジックが処理されるため、プラグイン開発者が関係する範囲外となります。 このファンクションを定義する方法の詳細は、setValueを参照してください。
disable()	アイテムを無効化するためのファンクションを指定します(これによって、デフォルトのページ・アイテムの処理がオーバーライドされます)。これは、無効化も必要な複合要素からアイテムが構成されている場合、または再利用しようとする独自の無効化メソッドをすでに保有しているウィジェットにアイテムが基づいている場合などに、役立つ可能性があります。アイテムを正しく無効化できるようにするということは、たとえばアイテムを無効化するために「動的アクション」の「無効化」アクションを使用する場合に、Application Expressのクライアント側機能関連の特定のアイテムが動作していることになります。 注意: このファンクションが定義されている場合でも、デフォルト処理によって常に.afterModify()ファンクションと関連するロジックが処理されるため、プラグイン開発者が関係する範囲外となります。 このファンクションを定義する方法の詳細は、disableを参照してください。
show()	アイテムを表示するためのファンクションを指定します(これによって、デフォルトのページ・アイテムの処理がオーバーライドされます)。これは、表示も必要な複合要素からアイテムが構成されている場合、または再利用しようとする独自の表示メソッドをすでに保有しているウィジェットにアイテムが基づいている場合などに、役立ちます。アイテムを正しく表示できるようにするということは、たとえば「動的アクション」の「表示」アクションを使用する場合に、Application Expressのクライアント側機能に関する特定のアイテムが動作してアイテムを表示するということです。 このファンクションを定義する方法の詳細は、showを参照してください。
hide()	アイテムを非表示にするためのファンクションを指定します(これによって、デフォルトのページ・アイテムの処理がオーバーライドされます)。これは、非表示も必要な複合要素からアイテムが構成されている場合、または再利用しようとする独自の非表示メソッドをすでに保有しているウィジェットにアイテムが基づいている場合などに、役立つ可能性があります。アイテムを正しく非表示にできるようにするということは、たとえば「動的アクション」の「非表示」アクションを使用する場合に、Application Expressのクライアント側機能に関する特定のアイテムが動作してアイテムを非表示にするということです。 このファンクションを定義する方法の詳細は、hideを参照してください。
isChanged()	アイテムの現在値が変更されている場合はtrueを戻し、それ以外の場合はfalseを戻すファンクションを指定します。このファンクションでは、未保存の変更がある場合の警告機能を有効にできます。デフォルト実装では、HTMLフォーム要素の組込み機能を使用して変更を検出します。このファンクションが正しく機能しない場合は、プラグイン・アイテム・タイプに対する変更が検出されず、ユーザーがページを離れるときに警告が表示されません。 このファンクションを定義する方法の詳細は、isChangedを参照してください。
isDisabled()	アイテムが無効化されている場合はtrueを戻し、それ以外の場合はfalseを戻すファンクションを指定します。
addValue()	アイテムが複数の値をサポートする場合、アイテムに値を追加するためのファンクションを指定します。現在、これに依存するApplication Expressのクライアント側の機能はありません。デフォルトのページ・アイテム処理もありません。 注意: このファンクションが定義されている場合でも、デフォルト処理によって常に.afterModify()ファンクションと関連するロジックが処理されるため、プラグイン開発者が関係する範囲外となります。 このファンクションを定義する方法の詳細は、addValueを参照してください。
nullValue	アイテムがnullかどうかの判断に使用される値を指定します。これは、アイテムが「LOV」の定義をサポートする場合、開発者がアイテムの「NULL戻り値」を定義できる場合、およびアイテムがnullまたは空の場合にアサートするため、これをデフォルトのアイテム処理で認識する必要がある場合に使用されます。これは、次の手順に従って行います。 プラグイン定義のレンダリング・ファンクションから、ページがロードされる際に起動する、アイテム初期化JavaScriptコードの一部としてp_item.lov_null_valueに格納される値を送信します。次に例を示します。 /* Assumes that you have some JavaScript function called 'com_your_company_your_item' that accepts 2 parameters, the first being the name of the item and the second being an object storing properties (say pOptions) required by the item's client side code. */ apex_javascript.add_onload_code ( p_code => 'com_your_company_your_item('|| apex_javascript.add_value( apex_plugin_util.page_item_names_to_jquery(p_item.name)||', {'|| apex_javascript.add_attribute('lovNullValue', p_item.lov_null_value, false, false)|| '});' ); 次に、com_your_company_your_item( pName, pOptions )の実装において、pOptions.lovNullValueプロパティに、特定のアイテムの「NULL戻り値」に値を定義します。これは、nullValueプロパティを設定するためのapex.widget.initPageItemへのコールに使用できます。 nullValueプロパティを設定すると、たとえばアイテムに関するis nullまたはis not nullのwhen条件を正しく評価するための「動的アクション」において、またはアイテムがnullかどうかを判断するためにJavaScriptファンクションapex.item( pNd ).isEmpty() をコールする場合に、Application Expressのクライアント側機能に関する特定のアイテムが動作していることになります。 このAPIの詳細は、isEmptyを参照してください。
setFocusTo	apex.item( pNd ).setFocus() APIを使用してアイテムにフォーカスを設定する際に、フォーカスを受けとるための要素を指定します。これは、jQueryセレクタ、jQueryまたはDOM要素を識別するDOMオブジェクト、または要素を参照するjQueryオブジェクトを戻すファンクションとして定義できます。これは、アイテムが複合要素から構成され、アイテム名と一致するIDがある要素にフォーカスが移動する(デフォルトの動作)必要がない場合に、役立つ可能性があります。たとえば、属性Input FieldがNot enterable, Show Display Value and Store Return Valueに設定されている場合、ネイティブ・アイテム・タイプPopup LOVは、アイテム名と一致するIDのある主な要素として無効化された入力フィールドと、入力の隣のポップアップ選択アイコンをレンダリングします。この場合、無効化された入力に移動するためのフォーカスが不要であるため、setFocusToアイテムのプロパティを使用して、ポップアップ選択アイコンに設定します。 アイテムがフォーカスを正しく設定できるようにするということは、たとえば「動的アクション」のSet Focusアクションを使用してアイテムへのフォーカスを設定する場合、関連するアイテムに直接移動するために検証エラーのメッセージに表示されるGo to Errorリンクにユーザーが従う場合、またはアイテムがページにおける最初のアイテムで、開発者がページ・レベルの属性Cursor FocusをFirst item on pageに設定した場合などに、Application Expressのクライアント側機能に関する特定のアイテムが動作していることになります。 このAPIの詳細は、setFocusを参照してください。
setStyleTo	apex.item( pNd ).setStyle() APIを使用してアイテムにスタイルを設定する際に、スタイルを受け取るための要素を指定します。これは、jQueryセレクタ、jQueryまたはDOM要素を識別するDOMオブジェクト、または要素を参照するjQueryオブジェクトを戻すファンクションとして定義できます。これは、アイテムが複合要素から構成され、要素にスタイルが設定される必要がない場合に、あるいはアイテム名と一致するIDのある要素のみから構成されている場合(デフォルトの動作)に、役立ちます。アイテムがスタイルを正しく設定できるようにするということは、たとえば「動的アクション」のSet Styleアクションを使用してアイテムにスタイルを追加する場合に、Application Expressのクライアント側機能に関する特定のアイテムが動作していることになります。 注意: このプロパティが定義されている場合でも、デフォルト処理によって常に.afterModify()ファンクションと関連するロジックが処理されるため、プラグイン開発者が関係する範囲外となります。 このAPIの詳細は、apex.item( pNd ).setStyle()に関するドキュメントを参照してください。
afterModify()	アイテムが変更された後で、呼び出されるファンクションを指定します。これは、たとえばjQuery Mobileなどの一部のフレームワークでウィジェットの変更の有無が通知される必要があるときに(例: 値が設定されたり、これらがネイティブ制御と拡張制御の両方を同期するために無効化されたなど)役立ちます。これを行うためのフックが、このコールバックによって提供されます。
loadingIndicator( pLoadingIndicator$ )	アイテムの一部のページのリフレッシュ中に、アイテムのロード・インジケータが表示される方法を標準化するファンクションを指定します。このファンクションは、最初のパラメータとしてpLoadingIndicator$パラメータを渡す必要があり、ロード・インジケータに関してDOM要素への参照があるjQueryオブジェクトを含んでいます。次にこのファンクションはアイテムのページにおける適切なDOM要素にロード・インジケータを追加し、ロード・インジケータへjQueryオブジェクト参照をも戻すため(これへの参照がフレームワークにあるようなもの)、コールが完了するとこれを削除可能です。 これはたとえば、アイテムがCascading LOVであって「カスケードLOV親アイテム」が変更される場合、またはサーバー側の「動的アクション」(例: Set Value - SQL Statement)の1つを使用することによってアイテムの値を設定する場合に使用されます。

例

次の例では、使用可能なコールバックとプロパティをすべて渡して、apex.item.create( pNd, pItemImpl )をコールします。プラグインが、コールバックとプロパティをいずれも指定しなければならない可能性はありません。これは、構文を示すためだけの例です。

apex.item.create( "P100_COMPANY_NAME", {
     displayValueFor: function( pValue ) {
        var lDisplayValue;
        // code to determine the display value for pValue
        return lDisplayValue;
    },
     enable: function() {
         // code that enables the item type
     },
     getPopupSelector: function() {
         return "<some CSS selector>";
    },
     getValidity: function() {
         var lValidity = { valid: true };
         if ( /* item is not valid */ ) {
             lValidity.valid = false;
         }
         return lValidity;
     },
     getValue: function() {
         var lValue;
         // code to determine lValue based on the item type.
         return lValue;
     },
     setValue: function( pValue, pDisplayValue ) {
        // code that sets pValue and pDisplayValue (if required), for the item type
     },
     disable: function() {
        // code that disables the item type
     },
     show: function() {
         // code that shows the item type
     },
     hide: function() {
         // code that hides the item type
     },
     isChanged: function() {
         var lChanged;
         // code to determine if the value has changed
         return lChanged;
     },
     addValue: function( pValue ) {
         // code that adds pValue to the values already in the item type
     },
     nullValue: "<null return value for the item>",
     setFocusTo: $( "<some jQuery selector>" ),
     setStyleTo: $( "<some jQuery selector>" ),
     afterModify: function(){
         // code to always fire after the item has been modified (value set, enabled, etc.)
     },
     loadingIndicator: function( pLoadingIndicator$ ){
         // code to add the loading indicator in the best place for the item
         return pLoadingIndicator$;
     }
});

参照:

『Oracle Application Expressアプリケーション・ビルダー・ユーザーズ・ガイド』のプラグインの実装に関する項