apex.messageネームスペース

apex.message.addVisibilityCheck

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

構文

apex.message.addVisibilityCheck( pFunction )

パラメータ

表38-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" );
    }
});

親トピック: apex.messageネームスペース

apex.message.alert

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

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

ダイアログ・スタイルは残りのアプリケーションと一致しています。
ダイアログは移動可能です。
apex.message.alertへのコールはブロックされません。apex.message.alertへのコールに続いて定義されたコードは、ユーザーが「OK」を押す前に実行されます。このため、ユーザーがダイアログを閉じた後に実行されるコードは、次の例に示すようにコールバック内で実行される必要があります。

注意:

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

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

構文

apex.message.alert( pMessage, pCallback )

パラメータ

表38-28 apex.message.alert

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

例

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

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

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

親トピック: apex.messageネームスペース

apex.message.clearErrors

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

構文

apex.message.clearErrors()

パラメータ

なし

例

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

 apex.message.clearErrors();

親トピック: apex.messageネームスペース

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 )

パラメータ

表38-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();
    }
});

親トピック: apex.messageネームスペース

apex.message.hidePageSuccess

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

ヒント:

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

構文

apex.message.hidePageSuccess()

パラメータ

なし

例

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

 apex.message.hidePageSuccess();

参照:

apex.message.setThemeHooks

親トピック: apex.messageネームスペース

apex.message.setThemeHooks

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

構文

apex.message.setThemeHooks( pOptions )

パラメータ

表38-30 apex.message.setThemeHooks

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

表38-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

ファンクション

デフォルトのページ通知表示機能の前にコールされるコールバック・ファンクション。オプションで、デフォルトの表示機能を完全に上書きするために、コールバックから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" );
        }
    }             
});

親トピック: apex.messageネームスペース

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 )

パラメータ

表38-32 apex.message.showErrors

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

表38-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」

親トピック: apex.messageネームスペース

apex.message.showPageSuccess

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

ヒント:

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

構文

apex.message.showPageSuccess( pMessage )

パラメータ

表38-34 apex.message.showPageSuccess

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

例

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

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

参照:

apex.message.setThemeHooks

親トピック: apex.messageネームスペース

apex.message.TYPE

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

プロパティ

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

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

例

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

親トピック: apex.messageネームスペース