31.13 apex.utilネームスペース

apex.utilネームスペースは、Oracle Application Expressの汎用ユーティリティ・ファンクションを格納します。

31.13.1 apex.util.escapeCSS

CSSメタ文字をエスケープした文字列pValueを戻します。CSSセレクタのときと同じようにこの値を使用する場合は、このファンクションを使用します。可能な場合には、CSSメタ文字が含まれないように値を制約すると、このファンクションを使用しなくて済みます。

パラメータ

表31-73 apex.util.escapeCSS

名前	タイプ	説明
`pValue`	String	CSSメタ文字を含む可能性があり、エスケープされた文字列。

戻り値

エスケープされた文字列。

例

この例では、「my.id」というIDの要素を検索できるように、ピリオド(.)文字を含む要素IDをエスケープしています。このファンクションを使用しない場合、セレクタはまったく異なる意味を解釈します。

apex.jQuery( "#" + apex.util.escapeCSS( "my.id" ) );

31.13.2 apex.util.escapeHTML

クロスサイトスクリプティング(XSS)攻撃を防ぐために、HTML特殊文字(&<>"'/)をエスケープした文字列pValueを戻します。

注意:

信頼できないデータをDOMに挿入する場合は、必ずこのファンクションを使用する必要があります。

パラメータ

表31-74 apex.util.escapeHTML

名前	タイプ	説明
`pValue`	String	HTML特殊文字を含む可能性があり、エスケープされた文字列。

戻り値

エスケープされた文字列。

例

この例では、テキストがP1_UNTRUSTED_NAMEというページ・アイテムに由来する場合に、DOM要素にテキストを追加します。ユーザーが入力したユーザーは、悪質なマークアップを含んでいないという保証がありません。

apex.jQuery( "#show_user" ).append( apex.util.escapeHTML( $v("P1_UNTRUSTED_NAME") ) );

31.13.3 apex.util.showSpinner

ユーザー処理が実行されていることを示すスピン・アラートをレンダリングするファンクション。アラートは、スクリーン・リーダーなどの支援テクノロジが処理ステータスへの注意を喚起されるようにARIAアラートとして定義されます。

パラメータ

表31-75 util.showSpinner

名前	タイプ	説明
`pContainer`	Object	スピナーを中央に置くコンテナを特定するオプションのjQueryセレクタ、jQueryまたはDOMオブジェクト。渡されない場合、スピナーはページ全体の中央に配置されます。デフォルトは`$("body")`です。
`pOptions`	Object	"alert"オプション(非表示でも、支援テクノロジで使用可能なアラート・テキスト)があるオプションのオブジェクト。デフォルトは、Processingです。デフォルトは、`Processing`です。

戻り値

スピナーのjQueryオブジェクト。

例

スピナーを表示するには、次のようにします。

var lSpinner$ = apex.util.showSpinner( $( "#container_id" ) );

スピナーを削除するには、次のようにします。

 lSpinner$.remove();

31.13.4 apex.util.stripHTML

HTMLタグをすべて削除した文字列pTextを戻します。

パラメータ

表31-76 apex.util.stripHTML

名前	タイプ	説明
`pText`	String	削除したいHTMLマークアップを含む可能性がある文字列。

戻り値

HTMLタグがすべて削除された入力文字列。

例

この例では、テキスト文字列がHTMLタグを削除します。

apex.util.stripHTML("Please <a href='www.example.com/ad'>click here</a>") 
// result “Please click here”

31.13.5 apex.util.applyTemplate

このファンクションは、データをテンプレートに適用します。pOptionsのオプションに従って値を置換することによって、pTemplateで指定したテンプレート文字列を処理します。テンプレートでは、Application Expressサーバー・スタイルのプレースホルダとアイテム置換構文がサポートされます。

これは、Application Expressスタイルのテンプレートをブラウザで処理するためのファンクションです。ただし、サーバーにあるデータすべてアクセスできるわけではありません。ページ・アイテムと列アイテムを置換する際には、サーバー上でセッション・ステートにある値ではなく、ブラウザに格納されている現在値が使用されます。旧式の不正確な置換(&ITEMのように末尾のピリオドがない)はサポートされません。#COLUMN_NAME#を使用する旧式の列参照構文はサポートされません。prepare_urlは実行できません(サーバー上で実行する必要があります)。テンプレートを使用してJavaScriptをDOMに挿入することはできません。処理後のテンプレートでは、スクリプト・タグが削除されます。

テンプレート文字列は、テキストに任意の数の置換トークンが混ざった形式です。サポートされる置換トークンは、プレースホルダと置換の2種類です。プレースホルダが先に処理されます。

プレースホルダの構文は次のとおりです。

 #<placeholder-name>#

<placeholder-name>は大文字の英数字とアンダースコア(_)およびドル記号($)の文字列で、プロパティ値によって置換されるオプション・オブジェクト・プレースホルダのプロパティ名である必要があります。プレースホルダ・オブジェクトの何にも一致しないプレースホルダ・トークンは、そのまま残されます(次のプレースホルダの検索は、末尾の#から始まります)。

置換構文は次のとおりです(いずれか)。

     &<item-name>.
     &<item-name>!<escape-filter>.
     &"<quoted-item-name>".
     &"<quoted-item-name>"!<escape-filter>.

<item-name>は大文字の英数字とアンダースコア(_)、ドル記号($)およびポンド記号(#)の文字列です。<quoted-item-name>は任意の文字の文字列ですが、&、キャリッジ・リターン、ライン・フィードおよび二重引用符を除きます。どちらの場合も、アイテム名はページ・アイテム(オプションincludePageItemsがfalseの場合を除く)、列アイテム(modelおよびrecordオプションを指定する場合)、組込みの置換(オプションincludeBuiltinSubstitutionsがfalseの場合を除く)、または追加置換(オプションextraSubstitutionsを指定している場合)のアイテム名です。置換の置換パターンが見つからない場合は、空の文字列で置き換えられます。列アイテムを置換する場合は、指定したモデルの指定したレコードを使用して一致する列名を検索します。見つからない場合や、モデルに親モデルがある場合には、親モデルの列が確認されます。これが、親モデルのあるかぎり続けられます。アイテム名を処理する順序。ページ・アイテム、列アイテム、先祖モデルからの列アイテム、組込みの置換、追加置換の順です。定義済の列ラベルにアクセスするとき、列アイテムは_LABEL接尾辞をサポートします。たとえば、NOTEという名前の列アイテムがある場合、&NOTE_LABEL.という置換によって、NOTE列のラベル文字列が戻されます。

組込みの置換名は、次のとおりです。

APP_ID
APP_PAGE_ID
APP_SESSION
REQUEST
DEBUG
IMAGE_PREFIX

置換値をどのようにエスケープまたはフィルタ処理するかは、エスケープ・フィルタによって制御されます。次のいずれかの値です。

HTML: HTML文字がエスケープされた値になります。
ATTR: 値はHTML属性コンテキスト(現在はHTMLと同じ)にエスケープされます。
RAW: 値をまったく変更しません。
STRIPHTML: HTMLタグを削除しHTML文字をエスケープした値になります。

これは、オプションdefaultEscapeFilterで、または列定義エスケープ・プロパティから設定されているデフォルトのエスケープ・フィルタをオーバーライドします。

パラメータ

表31-77 defaultEscapeFilter

名前	タイプ	説明
`pTemplate`	String	前述のフォーマットを持つテンプレート文字列。
`pOptions`	Object	テンプレートの処理方法を示すオブジェクト。次に示す`pOptions`のプロパティ表を参照してください。

表31-78 pOptionsのプロパティ

名前	説明
`placeholders`	プレースホルダ名から値へのオブジェクト・マップ。デフォルトは`null`です。
`defaultEscapeFilter`	上のエスケープ・フィルタ値のいずれか。デフォルトはHTML。これは、置換トークンにエスケープ・フィルタが指定されていない場合に実行されるエスケープ処理またはフィルタ処理です。モデル列定義にエスケープ・プロパティがある場合、デフォルトのエスケープ処理はオーバーライドされます。
`includePageItems`	`true`の場合、ページ・アイテムの現在値が置換されます。デフォルトは`true`です。
`model`	列アイテム値を取得するApplication Expressのモデル。デフォルトは`null`です。
`レコード`	列アイテム値の取得元であるモデルのレコード。オプション・モデルも指定する必要があります。デフォルトは`null`です。
`extraSubstitutions`	追加置換のオブジェクト・マップ。デフォルトは`null`です。
`includeBuiltinSubstitutions`	`true`の場合、`APP_ID`など組込みの置換が実行されます。デフォルトは`true`です。

戻り値

テンプレート・トークンがすべて置換されたテンプレートの文字列。

例

この例では、組込みのIMAGE_PREFIX置換と、P1_PROFILE_IMAGE_FILEというページ・アイテムから取得した画像のパスで、画像タグを挿入します。

apex.jQuery("#photo").html( 
    apex.util.applyTemplate( 
        "<img src='&IMAGE_PREFIX.people/&P1_PROFILE_IMAGE_FILE.'>" ) );

この例では、MESSAGEというプレースホルダから取得されるメッセージ・テキストで、メッセージにdivを挿入します。

var options = { placeholders: { MESSAGE: "All is well" } };
apex.jQuery("#notification").html( apex.util.applyTemplate( "<div>#MESSAGE#</div>", options ) );

31.13.6 apex.util.delayLingerについて

delayLingerシングルトンは、点滅する進捗インジケータ(スピナーなど)の問題を解決します。しばらく時間がかかるAjaxリクエスト(および後続のユーザー・インタフェースの更新)などのプロセスの場合、何かが発生していることをユーザーに知らせることが重要です。問題は、非同期プロセスが高速の場合、進捗インジケータを必要としないことです。ユーザーは、ユーザー・インタフェースの更新を瞬時に体験します。ごく短時間の非同期プロセスに進捗インジケータを表示して非表示にすると、ユーザーが完全に理解する時間がないほど瞬間的にコンテンツが表示されることになります。良くても、邪魔なものとなり、悪ければ、何かおかしいとか、何か重要なことを見逃したのではないかとユーザーは考えます。インジケータが表示されてすぐにプロセスは終了することもあるため、進捗インジケータを遅らせるだけでは問題の解決になりません。リクエストがすでに終了していたとしても、せめて短くても認識できる程度の時間、インジケータを表示する必要があります。

このオブジェクトを使用すると、このようなapex.util.showSpinnerなどの進捗実装による進捗表示の期間の管理が簡単になります。apex.server namespaceなど、Oracle Application Expressの非同期ファンクションの多くはすでに内部的にdelayLingerを使用しているため、このAPIが必要になるのは、実行時間が長い独自のカスタム非同期処理の場合のみです。

31.13.7 apex.util.delayLinger.start

このファンクションは、潜在的に実行時間が長い非同期プロセスが起動する際にコールします。各コールが指定されたpScopeNameで始まるには、対応するコールが同じpScopeNameで終わるようにする必要があります。別のpScopeName引数が指定されたコールは互いに干渉しません。

終了するためのコールの前に、同じpScopeNameに対して開始するためのコールが複数あってもかまいませんが、最初のコールのpActionのみが1回しかコールされません。

パラメータ

表31-79 apex.util.delayLinger.startファンクションのパラメータ

名前	タイプ	説明
`pScopeName`	String	進捗インジケータごとに一意の名前。
`pAction`	ファンクション	進捗インジケータを表示するためにコールするファンクション。

31.13.8 apex.util.delayLinger.finish

このファンクションは、潜在的に実行時間が長い非同期プロセスが終了する際にコールします。各コールが指定されたpScopeNameで始まるには、対応するコールが同じpScopeNameで終わるようにする必要があります。pActionは、対応する開始pActionがコールされた場合のみ、1回コールされます。終了するためのコールが複数ある場合、最後のコールのpActionのみがコールされます。

パラメータ

表31-80 apex.util.delayLinger.finishFunctionのパラメータ

名前	タイプ	説明
`pScopeName`	String	進捗インジケータごとに一意の名前
`pAction`	ファンクション	進捗インジケータを表示するためにコールするファンクション

例

var lSpinner$, lPromise;
lPromise = doLongProcess();
util.delayLinger.start( "main", function() {
    lSpinner$ = apex.util.showSpinnter( $( "#container_id" ) );
} );
lPromise.always( function() {
    util.delayLinger.finish( "main", function() {
        lSpinner$.remove();
    } );
} );