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、successdataTypeオプションのデフォルトは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" });