31.7 apex.messageネームスペース

apex.messageネームスペースは、クライアント側でのOracle Application Expressのメッセージの表示と管理を処理するために使用されます。

• apex.message.addVisibilityCheck
  
• apex.message.alert
  
• apex.message.clearErrors
  
• apex.message.confirm
  
• apex.message.hidePageSuccess
  
• apex.message.setThemeHooks
  
• apex.message.showErrors
  
• apex.message.showPageSuccess
  
• apex.message.TYPE
  

31.7.1 apex.message.addVisibilityCheck

このファンクションは、APEXリージョン・プラグインの開発者用です。エラーのある(またはエラー状態である可能性のある)アイテム(ページ・アイテムまたは列アイテム)に移動するには、エラー・アイテムにフォーカスする前にエラー・アイテムを表示可能にする必要があります。コンテンツを非表示にする可能性のあるリージョン・タイプには、このメソッドを使用して可視性チェック・ファンクションを追加する必要があります。表示可能にする必要のあるリージョンまたはアイテムに対して、追加された各ファンクションがコールされます。

構文

apex.message.addVisibilityCheck( pFunction )

パラメータ

表31-27 apex.message.addVisibilityCheck

名前	タイプ	説明
pFunction	ファンクション	要素IDでコールされるファンクション。要素が、このファンクションを追加したリージョン・タイプによって管理または制御される場合、このファンクションによって要素が確実に表示される必要があります。

例

次の例では、コンテンツを表示または非表示にし、ページ・アイテムを含むことのできる、Expanderというリージョン・プラグイン・タイプについて説明します。この例の目的のために、このプラグインはt-Expanderクラスをリージョン要素に追加します。また、コンテンツを展開するためのexpandメソッドを使用できます。

このリージョンは、次のように可視性チェック・ファンクションを登録する必要があります。

 apex.message.addVisibilityCheck( function( id ) {
    var lExpander$  = $( "#" + id ).closest( "t-Expander" );

    // Check if lExpander$ is an 'expander' region
    if ( lExpander$.hasClass( "t-Expander" ) ) {

        // If so, expander region must show its contents
        lExpander$.expander( "expand" );
    }
});

31.7.2 apex.message.alert

このファンクションは、指定されたメッセージと「OK」ボタンを示すアラート・ダイアログを表示します。pCallbackパラメータとして渡されるコールバック・ファンクションは、ダイアログを閉じるときにコールされます。jQuery UI Dialogウィジェットを使用してダイアログが表示されます。

このファンクションとブラウザの組込みのアラート・ファンクションには、いくつかの相違点があります。

• ダイアログ・スタイルは残りのアプリケーションと一致しています。

• ダイアログは移動可能です。

• apex.message.alertへのコールはブロックされません。apex.message.alertへのコールに続いて定義されたコードは、ユーザーが「OK」を押す前に実行されます。このため、ユーザーがダイアログを閉じた後に実行されるコードは、次の例に示すようにコールバック内で実行される必要があります。

注意:

次の2つの前提条件のいずれかが満たされない場合、ファンクションはブラウザの組込みアラートを使用してフォールバックします。

• ページ上でjQuery UIダイアログ・ウィジェット・コードをロードする必要があります。

• ブラウザは標準モードで実行されている必要があります。これは、互換モードで実行されている場合(一部の古いテーマの場合)、ダイアログが表示可能なビューポートの中央ではなくページの垂直中心に配置されるという、表示位置の問題が発生する可能性があるためです。

構文

apex.message.alert( pMessage, pCallback )

パラメータ

表31-28 apex.message.alert

名前	タイプ	説明
pMessage	String	確認ダイアログに表示するメッセージ。
pCallback	ファンクション	ダイアログを閉じるときにコールされるコールバック・ファンクション。

例

次の例では、アラート「ロードが完了しました」を表示した後、ダイアログが閉じられてからafterLoad()ファンクションを実行します。

このリージョンは、次のように可視性チェック・ファンクションを登録する必要があります。

 apex.message.alert( "Load complete.", function(){
    afterLoad();
});

31.7.3 apex.message.clearErrors

このファンクションは、現在ページに表示されているすべてのエラーをクリアします。

構文

apex.message.clearErrors()

パラメータ

なし

例

次の例では、現在ページに表示されているすべてのエラーをクリアする方法を示します。

 apex.message.clearErrors();

31.7.4 apex.message.confirm

このファンクションは、指定されたメッセージと「OK」および「取消」ボタンを示す確認ダイアログを表示します。pCallbackパラメータとして渡されるコールバック・ファンクションが、ダイアログを閉じるときにコールされ、「OK」が押された場合はtrue、それ以外の場合はfalseが渡されます。jQuery UI Dialogウィジェットを使用してダイアログが表示されます。

このファンクションとブラウザの組込みのアラート・ファンクションには、いくつかの相違点があります。

• ダイアログ・スタイルは残りのアプリケーションと一致しています。

• ダイアログは移動可能です。

• apex.message.confirmへのコールはブロックされません。apex.message.confirmへのコールに続いて定義されたコードは、ユーザーが「OK」または「取消」を押す前に実行されます。このため、ユーザーの選択に基づくアクションは、次の例に示すようにコールバック内で実行される必要があります。

注意:

次の2つの前提条件のいずれかが満たされない場合、ファンクションはブラウザの組込みの確認を使用してフォールバックします。

• ページ上でjQuery UIダイアログ・ウィジェット・コードをロードする必要があります。

• ブラウザは標準モードで実行されている必要があります。これは、互換モードで実行されている場合(一部の古いテーマの場合)、ダイアログが表示可能なビューポートの中央ではなくページの垂直中心に配置されるという、表示位置の問題が発生する可能性があるためです。

構文

apex.message.confirm( pMessage, pCallback )

パラメータ

表31-29 apex.message.confirm

名前	タイプ	説明
pMessage	String	確認ダイアログに表示するメッセージ。
pCallback	ファンクション	ダイアログを閉じるときにコールされるコールバック・ファンクション。ファンクションは次のパラメータを渡します。 「OK」が押された場合: 「OK」が押された場合はtrue、それ以外の場合はfalse (「取消」が押された場合、または他の方法でダイアログが閉じられた場合)。

例

次の例では、確認メッセージのAre you sure?を表示し、「OK」が押された場合はdeleteIt()ファンクションを実行します。

このリージョンは、次のように可視性チェック・ファンクションを登録する必要があります。

apex.message.confirm( "Are you sure?", function( okPressed ) { 
    if( okPressed ) {
        deleteIt();
    }
});

31.7.5 apex.message.hidePageSuccess

このファンクションは、ページレベルの成功メッセージを非表示にします。

ヒント:

テーマ開発者は、ページレベルの成功ページを非表示にしたときに何が起きるかに影響を与えたり、上書きしたりできます。詳細は、apex.message.setThemeHooksファンクションを参照してください(特にbeforeHideコールバック・ファンクション。ページレベルの成功メッセージを非表示にする際にpMsgType === apex.message.TYPE.SUCCESSを確認して分離する必要があります)。

構文

apex.message.hidePageSuccess()

パラメータ

なし

例

次の例では、ページレベルの成功メッセージを非表示にする方法を示します。

 apex.message.hidePageSuccess();

参照:

apex.message.setThemeHooks

31.7.6 apex.message.setThemeHooks

このファンクションは、テーマがapex.message APIによって提供される一部の動作に影響を与えられるようにします。このファンクションは、テーマ・ページ初期化コードからコールできます。

構文

apex.message.setThemeHooks( pOptions )

パラメータ

表31-30 apex.message.setThemeHooks

名前	タイプ	説明
pOptions	Object	次の表で説明するpOptionsプロパティを持つオブジェクト。

表31-31 pOptionsのプロパティ

名前	タイプ	説明
beforeShow	ファンクション	デフォルトのページ通知表示機能の前にコールされるコールバック・ファンクション。オプションで、デフォルトの表示機能を完全に上書きするために、コールバックからfalseを戻します。コールバックは次のパラメータを渡します。 pMsgType: メッセージ・タイプを指定します。apex.message.TYPEを使用して、エラー・メッセージと成功メッセージのどちらを表示するかを指定します pElement$: 表示される要素を含むjQueryオブジェクト。
beforeHide	ファンクション	デフォルトのページ通知非表示機能の前にコールされるコールバック・ファンクション。オプションで、デフォルトの非表示機能を完全に上書きするために、コールバックからfalseを戻します。コールバックは次のパラメータを渡します。 pMsgType: メッセージ・タイプを指定します。apex.message.TYPEを使用して、エラー・メッセージを表示するか、成功メッセージを表示するかを指定します pElement$: 非表示にする要素を含むjQueryオブジェクト。
closeNotificationSelector	String	通知で「閉じる」ボタンを識別するjQueryセレクタ。ユニバーサル・テーマで使用されるものにデフォルト設定されます(button.t-Button—closeAlert)。引き続きAPEXで非表示ロジックを処理する場合で、メッセージに異なるクラスの閉じる通知ボタンが含まれる場合に、カスタム・テーマで必要となることがあります。

例

次の例では、beforeShowおよびbeforeHideコールバックが定義されます。デフォルトの表示および非表示ロジックの前に、通知要素で追加クラスanimate-msgを追加および削除します。これはpMsgTypeに対する品質チェックによってのみ、成功メッセージに対して行われます。

注意:

コールバックでは何も返されないため、デフォルトの表示/非表示動作はコールバック後に行われます。

apex.message.setThemeHooks( 
    beforeShow: function( pMsgType, pElement$ ){
        if ( pMsgType === apex.message.TYPE.SUCCESS ) {
            pElement$.addClass( "animate-msg" );
        }
    }, 
    beforeHide: function( pMsgType, pElement$ ){
        if ( pMsgType === apex.message.TYPE.SUCCESS ) {
            pElement$.removeClass( "animate-msg" );
        }
    }             
}); 

31.7.7 apex.message.showErrors

このファンクションは、すべてのエラーをapex.messageエラー・スタックに表示します。スタックに追加しない場合は、まずclearErrors()をコールする必要があります。現在のアプリケーションのテーマのテンプレートを使用して、エラーを表示します。ページレベル・メッセージの場合(場所= page)、エラー・メッセージはページ・テンプレートのサブテンプレート>通知属性のマークアップを使用します。アイテムレベル・メッセージの場合(場所= inline)、エラー・メッセージはアイテムのラベル・テンプレートのエラー表示>エラー・テンプレート属性のマークアップを使用します。

ヒント:

テーマ開発者は、次のことを確認する必要があります。

• テーマのエラーを表示するには、前述のテンプレート属性を両方とも定義する必要があります。さらに、inlineエラーの場合は、ラベル・テンプレートは、ラベル・テンプレートのBefore ItemまたはAfter Item属性のいずれかで#ERROR_TEMPLATE#置換文字列を参照する必要があります。

• テーマ開発者は、ページレベルのエラーを表示したときに何が起きるかに影響を与えたり、上書きしたりできます。詳細は、apex.message.setThemeHooksファンクションを参照してください(特にbeforeShowコールバック・ファンクション。ページレベルのエラーを表示する際にpMsgType === apex.message.TYPE.ERRORを確認して分離する必要があります)。

構文

apex.message.showErrors( pErrors )

パラメータ

表31-32 apex.message.showErrors

名前	タイプ	説明
pErrors	オブジェクトまたは配列	次の表で説明するプロパティを持つオブジェクトまたはオブジェクトの配列

表31-33 pErrors

名前	タイプ	説明
type	String	errorを渡す必要がありますが、将来は別の通知タイプをサポートする可能性があります。
location	文字列|配列	使用できる値: inline、pageまたは[inline,page]。
pageItem	String	inlineエラーを表示する必要のあるアイテム参照。場所= inlineの場合は必須。
message	String	エラー・メッセージ。
unsafe	ブール	メッセージがshowErrorsによってエスケープされるようにtrueを渡します。メッセージがすでにエスケープされていて、showErrorsによってエスケープされる必要がない場合は、falseを渡します。

例

次の例では、まず表示された既存のエラーをクリアして、次に2つのエラーを表示します。2つのエラーを表示するために、2つのエラー・オブジェクトを含む配列がshowErrorsコールに渡されます。最初のエラー・メッセージはName is required!で、pageレベルとinlineの両方でアイテムP1_ENAMEとともに表示されます。2番目のエラー・メッセージはPage error has occurred!で、pageレベルでのみ表示されます。両方のエラーで、メッセージ・テキストは安全とみなされるため、エスケープされません。

// First clear the errors
apex.message.clearErrors();

// Now show new errors
apex.message.showErrors([
    {
        type:       "error",
        location:   [ "page", "inline" ],
        pageItem:   "P1_ENAME",
        message:    "Name is required!",
        unsafe:     false
    },
    {
        type:       "error",
        location:   "page",
        message:    "Page error has occurred!",
        unsafe:     false
    }
]);

参照:

• 「apex.message.setThemeHooks」

• 「apex.message.clearErrors」

31.7.8 apex.message.showPageSuccess

このファンクションは、ページレベルの成功メッセージを表示します。表示された以前の成功メッセージをクリアし、エラーがないと想定して以前に表示されたエラーをクリアします。現在のアプリケーションのテーマのテンプレートを使用して、成功メッセージを表示します。特に、ページ成功メッセージの場合は、ページ・テンプレートのサブテンプレート>成功メッセージ属性のマークアップが使用されます。

ヒント:

テーマ開発者は、ページレベルの成功ページを表示したときに何が起きるかに影響を与えたり、上書きしたりできます。詳細は、apex.message.setThemeHooksファンクションを参照してください(特にbeforeShowコールバック・ファンクション。ページレベルの成功メッセージを表示する際にpMsgType === apex.message.TYPE.SUCCESSを確認して分離する必要があります)。

構文

apex.message.showPageSuccess( pMessage )

パラメータ

表31-34 apex.message.showPageSuccess

名前	タイプ	説明
pMessage	String	表示する成功メッセージ。

例

次の例では、ページレベルの成功メッセージChanges saved!を示します。

 apex.message.showPageSuccess( "Changes saved!" );

参照:

apex.message.setThemeHooks

31.7.9 apex.message.TYPE

TYPEプロパティはプロパティ(定数)を含むオブジェクトで、apex.message APIをコールするときに便利です。たとえば、setThemeHooksです。

プロパティ

表31-35 apex.message.TYPEのプロパティ

値	説明
成功: “success”	成功メッセージを識別します
エラー: “error”	エラー・メッセージを識別します

例

使用例は、apex.message.setThemeHooksを参照してください。