プライマリ・コンテンツに移動

Oracle® Application Express APIリファレンス リリース5.1 E85937-02 |
| 目次 | 索引

前 | 次 |

# 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を参照してください。