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

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

前 | 次 |

# 31.11 apex.serverネームスペース

`apex.server`ネームスペースは、Oracle Application Expressのサーバー部分と通信するためのすべてのAjaxファンクションを格納します。

- apex.server.loadScript
- apex.server.plugin
- apex.server.pluginUrl
- apex.server.process
- apex.server.url

## 31.11.1 apex.server.loadScript

このAPIは、Asynchronous Module Definition (AMD)を持つ他のJavaScriptライブラリを非同期的にロードするとき、かつ`RequireJS`ライブラリがすでにページにロードされている場合に使用されます。

構文

    apex.server.loadScript( pConfig, callback )

パラメータ

表31-56 apex.server.loadScript

名前 | タイプ | 説明
--- | --- | ---
`pConfig` | オブジェクト | JSONオブジェクトの属性は、次のとおりです。 `path` - {String}ファイルの場所。 `“requirejs”` - {Boolean}このファイルをロードするとき、`requirejs`を使用するかどうか。 `global` - {String}このファイルによって導入されるグローバル名。既存の名前は上書きされます。ファイルが`RequireJS`オプティマイザによって生成される場合、このオプションは空のままにしてください。
`callback` | オブジェクト | スクリプトがロードされると1回実行されるファンクション。

戻り値

ファンクションを戻します。

例

次の例では、`RequireJS`を必要としない通常のライブラリをロードします。

     apex.server.loadScript ({
        "path": "./library_1.js"
     }, function() {
        console.log( 'library_1 is ready.' );
     });

次の例では、`RequireJS`を戻すライブラリをロードし、`myModule`という独自のネームスペースを作成します。

     apex.server.loadScript ({
        "path": "./library_2.js",
        "requirejs": true,
        "global": "myModule"
     }, function() {
        console.log( myModule );
     });

次の例では、`requireJS`がすでにページ上にあると想定し、`RequireJS`オプティマイザによって生成される連結ライブラリをロードします。

     apex.server.loadScript ({
        "path": "./library_all.js",
        "requirejs": true
     }, function() {
        console.log( myModule_1, myModule_2 ... );
     });

## 31.11.2 apex.server.plugin

このファンクションは、プラグインに定義されているPL/SQL Ajaxファンクションをコールします。このファンクションは、`jQuery.ajax`ファンクションのラッパーです。`jQuery.ajax`のサブセットに加え、Application Express固有の追加オプションをサポートします。

プラグインPL/SQL Ajaxファンクションは、PL/SQLパッケージ`apex_plugin.get_ajax_identifier`によって戻される値を使用して識別されます。プラグインAjaxの識別子を指定するには2つの方法があります。

1. 第1引数として`pAjaxIdentifier`を指定する

2. `pData`オブジェクト構造に`ajaxIdentifier`を含むリージョンについて情報を指定する詳細は`pData`を参照してください。

構文

    apex.server.plugin( pAjaxIdentifier, pData, pOptions ) → Promise

パラメータ

表31-57 apex.server.plugin

名前 | タイプ | 説明
--- | --- | ---
`pAjaxIdentifier` | String | オプション。プラグインAjax識別子。指定しない場合は、`ajaxIdentifier`プロパティでリージョンを含むリージョン配列を`pData`に含める必要があります。
`pData` | Object | Ajaxリクエストでサーバーに送信されるデータを含むオブジェクト(オプション)。オブジェクトはJSONとしてシリアライズされ、`p_json`というパラメータでサーバーに送信されます。特別に処理されるプロパティのリストは、次の`pData`の特殊プロパティ表を参照してください。 特定リージョンのデータは、次の書式で送信できます。
        {
            "regions": [ {
               "id": <region-id-or-static-id>,
               "ajaxIdentifier": <ajaxIdentifier>,
                <any other data specific to the region plug-in>
           }, ...
           ]
        }
`pOptions` | Object | 処理前と処理後を含むAjaxコールを制御するために追加のオプションを設定する際に使用する、オプションのオブジェクト。 Application Express固有のオプションのリストは、次の`pOptions`でプロパティ表を参照してください。 サポートされる次のオプションについては、jQuery.ajaxに関するjQueryドキュメントを参照してください: `accepts`、`dataType`、`beforeSend`、`contents`、`converters`、`dataFilter`、`headers`、`complete`、`statusCode`、`error`、`success` dataTypeオプションのデフォルトはjsonです。 asyncオプションは非推奨になりました。今後のリリースで削除される予定です。 `http://docs.jquery.com/`

表31-58 pDataの特殊プロパティ

名前 | タイプ | 説明
--- | --- | ---
`pageItems` | 文字列 | jQuery | DOM要素 | 配列 | リクエストに含まれるページまたは列アイテムを示します。jQueryセレクタ、jQueryオブジェクトまたはDOMオブジェクト、またはアイテム名の配列です。これらのアイテムは、サーバー上のセッション・ステートで使用可能になります。`pageItems`に列アイテムが含まれる場合は、リージョンのセッション・ステート・コンテキストを判別できるように、`pOptions`にターゲット・プロパティを含める必要があります。
`x01 - x10` | String | これらのプロパティは、`p_json`オブジェクトから移動し、`x01 - x10`のスカラー・パラメータとして送信されます。
`f01 - f20` | 文字列|配列 | これらのプロパティは、`p_json`オブジェクトから移動し、`f01 - f20`の配列パラメータとして送信されます。

表31-59 pOptionsのプロパティ

名前 | タイプ | 説明
--- | --- | ---
`refreshObject` | 文字列 | jQuery | DOM要素 | `apexbeforerefresh`および`apexafterrefresh`イベントがトリガーされるDOM要素を特定するjQueryセレクタ、jQueryオブジェクトまたはDOMオブジェクト。このオプションを指定しない場合、各イベントはトリガーされません。
`refreshObjectData` | オブジェクト | 配列 | `refreshObject`を指定した場合にのみ適用されます。`apexbeforerefresh`イベントおよび`apexafterrefresh`イベントをトリガーするコードによって渡されるデータを指定して、これらのイベントに定義されたすべてのハンドラがこのデータにアクセスできるようにします。`「リフレッシュ前」`イベントまたは`「リフレッシュ後」`イベントに定義された動的アクションでは、JavaScriptから`this.data`プロパティを使用してこのデータにアクセスできます。カスタムjQueryイベント・ハンドラの場合、イベント・ハンドラの`pData`パラメータを介してこのデータにアクセスできます。
`clear` | ファンクション | `apexbeforerefresh`イベントのトリガー後で、実際のAjaxコールがトリガーされる前に、DOMをクリアするために使用されるJavaScriptファンクション。
`loadingIndicator` | 文字列 | jQuery | DOMオプション | ファンクション | Ajaxコール中に、隣にロード・インジケータ(進行状況のスピナー)が表示される要素を示します。要素は、jQueryセレクタ、jQueryオブジェクトまたはDOMオブジェクトを使用して指定できます。`loadingIndicator`は、jQueryオブジェクトとしてロード・インジケータを取得するファンクションにすることもでき、作成されたロード・インジケータにjQuery参照を戻す必要があります。次に例を示します。
    function( pLoadingIndicator ) {
        return pLoadingIndicator.prependTo(
            apex.jQuery( "td.shuttleControl",
               gShuttle)
       );
    }
`loadingIndicatorPosition` | String | ロード・インジケータの表示位置を定義する6つのオプション。`loadingIndicator`に渡される値がファンクションでない場合にのみ考慮されます。 `before`: `loadingIndicator`によって定義されるDOM要素の前に表示します。 `after`: `loadingIndicator`によって定義されるDOM要素の後に表示します。 `prepend`: `loadingIndicator`によって定義されるDOM要素の先頭の内側に表示します。 `append`: `loadingIndicator`によって定義されるDOM要素の末尾の内側に表示します。 `centered`: `loadingIndicator`によって定義されるDOM要素の中央に表示します。 `page`: ページの中央に表示します。
`queue` | Object | キューおよびキュー・アクションの名前を指定するオブジェクト。名前プロパティには、リクエスト追加先のキューの名前を指定します。 アクション・プロパティは次のいずれかになります。 `wait` - デフォルトのアクションで、リクエストを順次送信するときに使用します。アクションがwaitの場合、リクエストは指定したキューに追加されます。そのキューに、進行中または待機中のリクエストがない場合は、このリクエストが実行されます。それ以外の場合は、前のリクエストが完了するまで、指定したキューで待機します。 `replace` - 指定したキューで進行中または待機中である前のリクエストが、現在のこのリクエストによって古く、または無効になった場合に、replace(置換)アクションが使用されます。現在のリクエストによって、進行中のリクエストが中止され、待機中のリクエストもクリアされて、現在のリクエストが実行されます。待機中のリクエストは却下され、ステータスは`superseded`になります。 `lazyWrite` - このアクションは、サーバーにリクエストをとどめて、データを永続させるときに使用します。これを使用するのは、ユーザー・インタフェースの設定や状態など、重要ではないデータを永続させるときだけです。データが頻繁に変わる可能性があり、直前のデータ値のみ保存しておく場合に使用します。たとえば、スプリッタ位置、ツリーの展開、フォーカス状態などを保存するときに便利です。 キュー名は、データ・ユニットごとに一意です。たとえば、2種類のスプリッタの位置を保存する場合は、一方に対する最新の更新が、もう一方の前回の遅延書込みを上書きしないように、それぞれ一意の名前を使用します。`lazyWrite`キューを使用する場合、`refreshObject`、`clear`、`loadingIndicator`および`loadingIndicatorPosition`は意味がなくなる可能性があります。何もロードまたはリフレッシュされないからです。 waitとreplaceのアクションを指定したリクエストを、同じキューで混在させることもできます。waitおよびreplaceアクションでも使用されているのと同じキュー名に対して、`lazyWrite`アクションは使用しないでください。
`target` | 文字列 | DOM要素 | このリクエストが該当するターゲット要素(DOM要素またはjQueryセレクタ)。これは、外側リージョンからセッション・ステート・コンテキストを取得する際に使用されます。

戻り値

promiseオブジェクトを戻します。Ajaxリクエストが正常に完了すると、promiseのdoneメソッドがコールされます。これがコールされるのは、`pOptions`でコールバック・ファンクションが成功した場合と同じです。promiseのfailメソッドは、Ajaxリクエストがエラーで終わり、内部で検出されたApplication Expressエラーを伴う場合にコールされます。これがコールされるのは、`pOptions`でコールバック・ファンクションがエラーになった場合と同じです。promiseにはalwaysというメソッドもあり、これは実行後とエラー後のどちらでもコールされます。キューのオプションを使用している場合でも、promiseが戻されます。promiseは`jqXHR`オブジェクトではありませんが、abortメソッドがあります。abortメソッドは、キューのいずれかのオプションを使用するリクエストでは機能しません。

例

この例は、`apex.server.plugin`へのこのコールによって、スカラー値`x01`が`test` (`apex_application.g_x01`を使用してPL/SQLからアクセス可能)に設定され、セッション・ステートにページ・アイテムの`P1_DEPTNO`および`P1_EMPNO`の値が(jQueryセレクタ構文を使用して)設定されることを示します。`apexbeforerefresh`イベントおよび`apexafterrefresh`イベントを起動する要素として、`P1_MY_LIST`アイテムが使用されます。`P1_MY_LIST`は、横にロード・インジケータが表示される要素として使用されます。成功のコールバックはスタブ・アウトされ、コールが正常に戻された際に起動される独自のコードを開発者が追加するために使用されます。`lAjaxIdentifier`の値は、サーバーのPL/SQL API `apex_plugin.get_ajax_identifier`によって戻される値に設定する必要があります。

成功したコールバックに対する`pData`パラメータには、プラグインPL/SQL Ajaxファンクションによって戻されるレスポンスが含まれます。

    apex.server.plugin ( lAjaxIdentifier, {
        x01: "test",
        pageItems: "#P1_DEPTNO,#P1_EMPNO"
        }, {
           refreshObject: "#P1_MY_LIST",
           loadingIndicator: "#P1_MY_LIST",
           success: function( pData ) {
             // do something here
           }
        });

## 31.11.3 apex.server.pluginUrl

プラグインに定義されているPL/SQL Ajaxファンクションに対してGETリクエストを発行するためのURLを戻します。

パラメータ

表31-60 apex.server.pluginUrl

名前 | タイプ | 説明
--- | --- | ---
`pAjaxIdentifier` | String | PL/SQLパッケージ`apex_plugin.get_ajax_identifier`によって戻される値を使用して、プラグインを特定します。
`pData` | Object | URLに含まれる追加の値を設定する際に使用するオブジェクト(オプション)。タイプにjQueryセレクタ、jQueryオブジェクト、DOMオブジェクトまたはアイテム名の配列を選択できる特別な属性`pageItems`によって、URLに含むページ・アイテムが指定されます。`apex.show`プロシージャによって提供される追加のパラメータを設定することもできます(たとえば、スカラー・パラメータ`x01 - x10`および配列`f01 - f20`を設定できます)。

戻り値

`GET`リクエストを発行するURLである文字列を戻します。

例

`apex.server.pluginUrl`へのこのコールによって、プラグインに定義されているPL/SQL Ajaxファンクションに対してGETリクエストを発行するためのURLが戻され、スカラー値`x01`が`test` (`apex_application`.`g_x01`を使用してPL/SQLからアクセス可能)に設定され、セッション・ステートにページ・アイテムの`P1_DEPTNO`および`P1_EMPNO`の値が(jQueryセレクタ構文を使用して)設定されます。`lAjaxIdentifier`の値は、サーバーのPL/SQL API `apex_plugin.get_ajax_identifier`によって戻される値に設定する必要があります。

    var lUrl = apex.server.pluginUrl ( lAjaxIdentifier, {
      x01: "test",
      pageItems: "#P1_DEPTNO,#P1_EMPNO" } );

## 31.11.4 apex.server.process

このファンクションは、ページ・レベルまたはアプリケーション・レベルで定義されたPL/SQLオンデマンド(Ajaxコールバック)プロセスをコールします。このファンクションは、jQuery.ajaxファンクションのラッパーです。`jQuery.ajax`のサブセットに加え、Application Express固有の追加オプションをサポートします。

構文

    apex.server.process( pName, pData, pOptions ) → Promise

パラメータ

表31-61 apex.server.process

名前 | タイプ | 説明
--- | --- | ---
`pName` | String | コールするPL/SQLオンデマンド・ページ・プロセスまたはPL/SQLオンデマンド・アプリケーション・プロセスの名前。
`pData` | Object | Ajaxリクエストでサーバーに送信されるデータを含むオブジェクト(オプション)。オブジェクトはJSONとしてシリアライズされ、p_jsonというパラメータでサーバーに送信されます。特別に処理されるプロパティのリストは、次の`pData`の表を参照してください。 特定リージョンのデータは、次の書式で送信できます。
        {
            "regions": [ {
                "id": <region-id-or-static-id>,
                "ajaxIdentifier": <ajaxIdentifier>,
                <any other data specific to the region plug-in>
            }, ...
            ]
        }
`pOptions` | Object | 処理前と処理後を含むAjaxコールを制御するために追加のオプションを設定する際に使用する、オプションのオブジェクト。Application Express固有のオプションのリストは、次の`pOptions`の表を参照してください。 サポートされる次のオプションについては、`jQuery.ajax`に関するjQueryドキュメントを参照してください: `accepts`、`dataType`、`beforeSend`、`contents`、`converters`、`dataFilter`、`headers`、`complete`、`statusCode`、`error`、`success`dataTypeオプションのデフォルトはjsonです。 asyncオプションは非推奨になりました。今後のリリースで削除される予定です。

表31-62 pDataの特殊プロパティ

名前 | タイプ | 説明
--- | --- | ---
`pageItems` | 文字列 | jQuery | DOM要素 | 配列 | リクエストに含まれるページまたは列アイテムを示します。jQueryセレクタ、jQueryオブジェクトまたはDOMオブジェクト、またはアイテム名の配列です。これらのアイテムは、サーバー上のセッション・ステートで使用可能になります。`pageItems`に列アイテムが含まれる場合は、リージョンのセッション・ステート・コンテキストを判別できるように、`pOptions`にターゲット・プロパティを含める必要があります。
`x01 - x10` | String | これらのプロパティは、`p_json`オブジェクトから移動し、`x01 - x10`のスカラー・パラメータとして送信されます。
`f01 - f20` | 文字列|配列 | これらのプロパティは、`p_json`オブジェクトから移動し、`f01 - f20`の配列パラメータとして送信されます。

表31-63 pOptionsのプロパティ

名前 | タイプ | 説明
--- | --- | ---
`refreshObject` | 文字列 | jQuery | DOM要素 | `apexbeforerefresh`および`apexafterrefresh`イベントがトリガーされるDOM要素を特定するjQueryセレクタ、jQueryオブジェクトまたはDOMオブジェクト。このオプションを指定しない場合、各イベントはトリガーされません。
`refreshObjectData` | オブジェクト | 配列 | `refreshObject`を指定した場合にのみ適用されます。`apexbeforerefresh`イベントおよび`apexafterrefresh`イベントをトリガーするコードによって渡されるデータを指定して、これらのイベントに定義されたすべてのハンドラがこのデータにアクセスできるようにします。「リフレッシュ前」イベントまたは「リフレッシュ後」イベントに定義された動的アクションでは、JavaScriptから`this.data`プロパティを使用してこのデータにアクセスできます。カスタムjQueryイベント・ハンドラの場合、イベント・ハンドラの`pData`パラメータを介してこのデータにアクセスできます。
`clear` | ファンクション | `apexbeforerefresh`イベントのトリガー後で、実際のAjaxコールがトリガーされる前に、DOMをクリアするために使用されるJavaScriptファンクション。
`loadingIndicator` | 文字列 | jQuery | DOMオプション | ファンクション | Ajaxコール中に、隣にロード・インジケータ(進行状況のスピナー)が表示される要素を示します。要素は、jQueryセレクタ、jQueryオブジェクトまたはDOMオブジェクトを使用して指定できます。`loadingIndicator`は、jQueryオブジェクトとしてロード・インジケータを取得するファンクションにすることもでき、作成されたロード・インジケータにjQuery参照を戻す必要があります。次に例を示します。
    function( pLoadingIndicator ) {
        return pLoadingIndicator.prependTo(
            apex.jQuery( "td.shuttleControl",
                gShuttle)
        );
    }
`loadingIndicatorPosition` | String | ロード・インジケータの表示位置を定義する6つのオプション。`loadingIndicator`に渡される値がファンクションでない場合にのみ考慮されます。 `loadingIndicatorPosition`: ロード・インジケータの表示位置を定義する6つのオプション。`loadingIndicator`に渡される値がファンクションでない場合にのみ考慮されます。 `before`: `loadingIndicator`によって定義されるDOM要素の前に表示します `after`: `loadingIndicator`によって定義されるDOM要素の後に表示します `prepend`: `loadingIndicator`によって定義されるDOM要素の先頭の内側に表示します `append`: `loadingIndicator`によって定義されるDOM要素の末尾の内側に表示します `centered`: `loadingIndicator`によって定義されるDOM要素の中央に表示します `page`: ページの中央に表示します。
`queue` | Object | キューおよびキュー・アクションの名前を指定するオブジェクト。名前プロパティには、リクエスト追加先のキューの名前を指定します。 アクション・プロパティは次のいずれかになります。 `wait` - デフォルトのアクションで、リクエストを順次送信するときに使用します。アクションがwaitの場合、リクエストは指定したキューに追加されます。そのキューに、進行中または待機中のリクエストがない場合は、このリクエストが実行されます。それ以外の場合は、前のリクエストが完了するまで、指定したキューで待機します。 `replace` - 指定したキューで進行中または待機中である前のリクエストが、現在のこのリクエストによって古く、または無効になった場合に、replace(置換)アクションが使用されます。現在のリクエストによって、進行中のリクエストが中止され、待機中のリクエストもクリアされて、現在のリクエストが実行されます。待機中のリクエストは却下され、ステータスは`superseded`になります。 `lazyWrite` - このアクションは、サーバーにリクエストをとどめて、データを永続させるときに使用します。これを使用するのは、ユーザー・インタフェースの設定や状態など、重要ではないデータを永続させるときだけです。データが頻繁に変わる可能性があり、直前のデータ値のみ保存しておく場合に使用します。たとえば、スプリッタ位置、ツリーの展開、フォーカス状態などを保存するときに便利です。 キュー名は、データ・ユニットごとに一意です。たとえば、2種類のスプリッタの位置を保存する場合は、一方に対する最新の更新が、もう一方の前回の遅延書込みを上書きしないように、それぞれ一意の名前を使用します。`lazyWrite`キューを使用する場合、`refreshObject`、clear、loadingIndicatorおよび`loadingIndicatorPosition`は意味がなくなる可能性があります。何もロードまたはリフレッシュされないからです。 waitとreplaceのアクションを指定したリクエストを、同じキューで混在させることもできます。waitおよびreplaceアクションでも使用されているのと同じキュー名に対して、`lazyWrite`アクションは使用しないでください。
`target` | 文字列 | DOM要素 | このリクエストが該当するターゲット要素(DOM要素またはjQueryセレクタ)。これは、外側リージョンからセッション・ステート・コンテキストを取得する際に使用されます。

戻り値

promiseオブジェクトが戻されます。Ajaxリクエストが正常に完了すると、promiseのdoneメソッドがコールされます。これがコールされるのは、`pOptions`でコールバック・ファンクションが成功した場合と同じです。promiseのfailメソッドは、Ajaxリクエストがエラーで終わり、内部で検出されたApplication Expressエラーを伴う場合にコールされます。これがコールされるのは、`pOptions`でコールバック・ファンクションがエラーになった場合と同じです。promiseにはalwaysというメソッドもあり、これは実行後とエラー後のどちらでもコールされます。キューのオプションを使用している場合でも、promiseが戻されます。promiseは`jqXHR`オブジェクトではありませんが、abortメソッドがあります。abortメソッドは、キューのいずれかのオプションを使用するリクエストでは機能しません。

例

この例は、`apex.server.process`へのこのコールによって、`MY_PROCESS`というオンデマンド・プロセスがコールされ、スカラー値`x01`が`test` (`apex_application.g_x01`を使用してPL/SQLからアクセス可能)に設定され、セッション・ステートにページ・アイテムの`P1_DEPTNO`および`P1_EMPNO`の値が(jQueryセレクタ構文を使用して)設定されることを示します。成功のコールバックはスタブ・アウトされ、コールが正常に戻された際に起動される独自のコードを開発者が追加するために使用されます。

注意: 成功したコールバックに対する`pData`パラメータには、オンデマンド・プロセスから返信されるレスポンスが含まれます。

    apex.server.process ( "MY_PROCESS", {
            x01: "test",
            pageItems: "#P1_DEPTNO,#P1_EMPNO"
      },{
            success: function( pData )
                // do something here
            }
      } );

## 31.11.5 apex.server.url

このファンクションは、現在のページに対してGETリクエストを発行するためのURLを戻します。

パラメータ

表31-64 apex.server.url

名前 | タイプ | オプション/必須 | 説明
--- | --- | --- | ---
`pData` | Object | オプション。 | URLに含む追加の値を設定するためにオプションで使用可能なオブジェクト。タイプにjQueryセレクタ、jQueryオブジェクト、DOMオブジェクトまたはアイテム名の配列を選択できる特別な属性`pageItems`によって、URLに含むページ・アイテムが指定されます。`apex.show`プロシージャによって提供される追加のパラメータを設定することもできます(たとえば、スカラー・パラメータx01 - x10および配列f01 - f20を設定できます)。
`pPage` | String | オプション。 | 戻されるURLにページIDを設定するためにオプションで使用可能な現在のページのページID。

戻り値

GETリクエストを発行する文字列URLを戻します。

例

この例では、`apex.server.url`へのコールを示します。このページに定義されているDELETEファンクションに対してGETリクエストを発行するためのURLが戻され、スカラー値`x01`が`test` (`apex_application`.`g_x01`を使用してPL/SQLからアクセス可能)に設定され、セッション・ステートにページ・アイテムの`P1_DEPTNO`および`P1_EMPNO`の値が(jQueryセレクタ構文を使用して)設定されます。

    apex.server.url ({
        p_request: "DELETE",
        x01: "test",
        pageItems: "#P1_DEPTNO,#P1_EMPNO" });