ラベル Code の投稿を表示しています。 すべての投稿を表示
ラベル Code の投稿を表示しています。 すべての投稿を表示

2022年8月26日金曜日

CKEditor5による画像アップロードを実装する(4) - 画像をオブジェクト・ストレージに保存する

以前にLouis Moreauxさんの記事を読んでCKEditor5で画像の貼り付けをできるようにしました。以下の記事です。

CKEditor5による画像アップロードを実装する(1) - 準備
CKEditor5による画像アップロードを実装する(2) - REST APIの作成
CKEditor5による画像アップロードを実装する(3) - 完成

さらにLouis MoreauxさんはCKEditor5 Image Upload - Part 3として、画像をデータベースではなくオブジェクト・ストレージに保存する方法を記事として公開しています。

CKEditor5に画像を含めると、文書にを表示する際に含まれている画像を同時にダウンロードするようです。そのため、この機能を組み込んだAPEXアプリケーションをリソース制限の厳しいAlways FreeのAutonomous Database上で動かすと、データベースのセッション数の上限に達してしまいます。

少し残念だったので、画像をオブジェクト・ストレージに保存するように変更して、少ないリソースでもアプリが使えるかどうか確認してみます。

以下は、事前に実施する準備作業です。

ユーザー、グループ、ポリシーなどの作成を行います。事前承認リスエストを生成するため、バケットの権限はreadではなくmanageが必要です。

Allow group APEXObjectManagers to read buckets in compartment APEX
Allow group APEXObjectManagers to manage objects in compartment APEX

APEXからOCIオブジェクト・ストレージを操作する(1) - APIユーザーの作成

バケットはapex_file_storageの代わりにimagesを作成します。

REST APIを呼び出す際に指定するWeb資格証明をOCI_API_ACCESSとして作成します。

APEXからOCIオブジェクト・ストレージを操作する(4) - Web資格証明の作成

OCI側の準備は以上になります。これから画像をオブジェクト・ストレージに保存するように、アプリケーションに変更を加えます。


RESTサービスのPOSTハンドラの変更



画像のアップロードを受け付けて、BLOBに保存している処理をオブジェクト・ストレージに保存するように変更します。CKEditor5に戻すURLとしてRESTサービスのGETハンドラではなく、オブジェクト・ストレージにアップロードした画像のURLを返します。

ネームスペース名は適切な値に置き換えます。




置換文字列の準備



コード中で使用する各種パラメータを置換文字列として定義します。

G_OBJECT_STORAGE_URLとして、以下を設定します。リージョン名、ネームスペース名、バケット名の値を置き換えます。

https://objectstorage.リージョン名.oraclecloud.com/n/ネームスペース名/b/バケット名/o/

ネームスペース名のハードコードを避けるために、置換文字列G_NAMESPACEとしてネームスペース名を設定します。



事前承認リクエストの発行



画像をアップロードするときはクリデンシャルを指定していますが、画像を表示する(ダウンロードする)ときはクリデンシャルを指定する方法がありません。バケットの可視性をプライベートにした上で画像をダウンロードするために、事前承認リクエストを発行します。

事前承認リクエストのパスを保存するアプリケーション・アイテムG_PREAUTH_URLを作成します。

名前はG_PREAUTH_URL、有効範囲はアプリケーション、セキュリティのセッション・ステート保護は一番厳しい制限付き - ブラウザからの設定不可を選びます。


このアプリケーション・アイテムに値を設定するアプリケーション・アイテムの計算を作成します。

事前承認リクエストのURLを取得するために、オブジェクト・ストレージのREST APIを呼び出します。

計算アイテムとしてG_PREAUTH_URLを選択します。頻度の計算ポイントは認証後を選択します。計算タイプはファンクション本体、計算として上記のコードを記述します。



対話モード・レポートのソース変更



対話モード・レポートのソースのSQL問合せを以下のSELECT文に変更します。
select
    ID
    , TITLE
    -- , CONTENT
    , replace(CONTENT, :G_OBJECT_STORAGE_URL, :G_PREAUTH_URL) content
    , AUTHOR
    , PUBLISHED
    , CREATED
    , CREATED_BY
    , UPDATED
    , UPDATED_BY
from RTE_DOCUMENTS
以前はapex_session=の引数を画像URLに付加し、APEXセッションでORDSへのGETリクエストの認証を通していました。この部分を、事前承認済リクエストのURLに置き換えています。



editingDowncastコンバーターの変更



CKEditor5内で画像を表示するときは、editingDowncastコンバーターを構成し、画像URLを見つけてapex_session引数を追加していました。今回はその代わりに、見つけた画像URLを事前承認済リクエストのURLに置き換えています。


ページ・アイテムP2_CONTENTの詳細のJavaScript初期化コードを入れ替えます。



画像の紐付けの変更


ドキュメントに含まれるイメージの参照先が、G_IMAGE_URLからG_OBJECT_STORAGE_URLに変更されています。文書と画像を紐づけているプロセス画像の紐付けのPL/SQLコードを以下に変更します。




外部キー制約の変更



表RTE_IMAGESには外部キー制約RTE_IMAGES_DOCUMENT_ID_FKが設定されていて、親である表RTE_DOCUMENTSから文書が削除されると、CASCADE設定により含まれる画像も削除されるようになっていました。オブジェクト・ストレージに保存した画像は自動的には保存されないため、CASCADEからON DELETE SET NULLに変更します。
alter table "RTE_IMAGES" drop constraint "RTE_IMAGES_DOCUMENT_ID_FK";
alter table "RTE_IMAGES" add constraint "RTE_IMAGES_DOCUMENT_ID_FK"
foreign key ("DOCUMENT_ID") references "RTE_DOCUMENTS" ("ID") on delete set null; 
表RTE_IMAGESの列DOCUMENT_IDがNULLの画像は、親となる文書が存在していません。定期的なハウスキーピングのジョブにて、行の削除と同時にオブジェクト・ストレージ上の画像の削除を行なうようにするよ良いでしょう。

以上でCKEditor5による画像のアップロード先/ダウンロード先をオブジェクト・ストレージに変更できました。

今回作成したAPEXアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/ORDS_REST_WKSP_APEXDEV_rteditor_2023_07_04_2.sql
https://github.com/ujnak/apexapps/blob/master/exports/ckeditor-image-sample-obs.zip

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完

対話グリッドの行の追加ボタンを非表示にする

 対話グリッドの操作は主にツール・バー上のボタン、アクション・メニュー、行操作メニューより行います。

本記事では、対話グリッドのツール・バー上のボタン行の追加と行操作メニューの行の追加の表示/非表示を切り替える方法を紹介します。

どの操作も1行のJavaScriptのコードを実行します。

最初にOracle APEX JavaScript API ReferenceのWidgetsのinteractiveGridのページを開きます。

https://docs.oracle.com/en/database/oracle/apex/22.1/aexjs/interactiveGrid.html

ActionsのセクションにあるPre-defined actions used by the Interactive Grid widgetより、表示/非表示を切り替える対象であるアクションの内部名称を見つけます。

ツール・バー上の行の追加はselection-add-rowです。行操作メニューの行の追加はrow-add-rowです。

WebブラウサのJavaScriptコンソールを開き、これらの表示/非表示をコンソールから操作します。

対話グリッドには、静的IDとしてempを設定しています。

最初にツール・バー上の行の追加ボタンを非表示します。

apex.region("emp").call("getActions").hide("selection-add-row");

コマンドの実行によりツール・バー上の行の追加ボタンが消えます。


表示させるにはhideの代わりにshowを呼び出します。

apex.region("emp").call("getActions").show("selection-add-row");

再度、ツール・バー上に行の追加ボタンが表示されます。


行操作メニューの行の追加を非表示にします。

apex.region("emp").call("getActions").hide("row-add-row");

行操作メニューより行の追加が無くなっています。


表示を戻します。

apex.region("emp").call("getActions").show("row-add-row");

行操作メニューに行の追加が含まれています。


行の追加以外のアクションも同様に操作することができます。

以上です。

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完

APEX 22.1の承認コンポーネント(4) - 多段階承認の実装

 OracleのAnanya Chatterjeeさんによる以下の記事が、公式ブログに寄稿されています。

Implementing Multi-Approvals in Oracle APEX 22.1

APEXの承認コンポーネントのタスクは、承認または却下することによって完了します。一旦承認/却下するとタスクは完了し、それ以降の操作はできません。そのため、職制を通した承認といったフローを、ひとつのタスクで扱うことはできません。

Ananya Chatterjeeさんは直属の上司がタスクを承認するときに、その上の階層での承認が必要であれば、承認時に実行されるコードの中で新たにタスクを生成することにより多段階での承認を実装しています。

以前の記事で作成した休暇申請を行なうAPEXアプリケーションに、多段階承認を実装してみます。

APEX 22.1の承認コンポーネント(1) - 概要
http://apexugj.blogspot.com/2022/07/new221-approvals-component-intro.html
APEX 22.1の承認コンポーネント(2) - 基本的なアプリケーションの作成
http://apexugj.blogspot.com/2022/07/new221-approvals-component-basicapp.html
APEX 22.1の承認コンポーネント(3) - ユーザー・データの利用
http://apexugj.blogspot.com/2022/07/new221-approvals-component-userdata.html

最初に承認の階層を定義します。アプリケーションのユーザーは、申請太郎、申請花子、承認太郎、承認花子、管理者です。

申請太郎の直属上司を承認太郎、承認太郎の上司を管理者とします。また、申請花子の直属上司は承認花子、その上司を管理者とします。

表UNI_USERSを作成し、上記の階層をデータとして入力します。SQLワークショップのSQLスクリプトより実行します。



せっかく表UNI_USERSを作成したので、サインインのユーザーがハードコードされている認証スキームを更新します。

共有コンポーネントの認証スキームの固定ユーザー認証を開き、ソースを以下に置き換えます。登録されているユーザーに変更はないので、このソースの置き換えはアプリケーションに影響を与えません。



共有コンポーネントのタスク定義の休暇申請を開きます。

参加者の潜在的所有者の定義を変更します。現在の定義は以下になっています。申請太郎の上司は承認太郎、申請花子の上司は承認花子です。それ以外、つまり承認太郎と承認花子の上司は管理者です。
begin
  if :APEX$TASK_INITIATOR = '申請太郎' then
      return '承認太郎';
  elsif :APEX$TASK_INITIATOR = '申請花子' then
      return '承認花子';
  else
      return '管理者';
  end if;
end;
上記を表UNI_USERSを参照した定義に置き換えます。

タスクの開始者(APEX$TASK_INITIATOR)ではなく、サインインしているユーザー(APP_USER)の上司を潜在的所有者としています。


アクションを更新します。タスクが完了したときのイベント処理で、結果が承認済みのときに実行されるコードを変更します。

イベント時が完了、結果が承認済のアクションを開きます。


アクションのコードを、以下のコードに置き換えます。休暇の申請期間が一週間を超える場合、休暇申請のステータス(表UNI_REQUESTSの列STATUS)をTRANSFEREDにしてタスクを完了し、承認者の上司による承認を求めるタスクを作成しています。




以上で多段階での承認が実装できました。

動作を確認してみます。

申請太郎でサインインし、2022/12/01から2022/12/31までの休暇を申請します。


自分で開始を開くと、承認太郎にタスクがアサインされていることが確認できます。


承認太郎でサインインし私のタスクを開き、アサインされたタスクを承認します。


休暇申請一覧を開くと、表UNI_REQUESTSの列STATUSはTRANSFEREDになっていることが確認できます。


管理者でサインインし私のタスクを開き、アサインされたタスクを承認します。


休暇申請一覧を開くと、表UNI_REQUESTSの列STATUSはAPPROVEDになっていることが確認できます。


以上で多段階での承認の実装が確認できました。


タスクの詳細の更新



本記事での実装では、タスクのパラメータを使っていません。そのため、タスクの詳細のページの詳細に何も表示されません。


ページ・デザイナにてタスクの詳細のページを開き、リージョン詳細のソースを置き換えます。

ソースのSQL問合せを以下に置き換えます。
select reason, start_date, end_date
from uni_requests
where id = (
    select detail_pk from apex_tasks 
    where task_def_static_id = 'LEAVE_REQUEST'
    and application_id = :APP_ID
    and task_id = :P5_TASK_ID
);  

属性の外観のテンプレートをValue Attribute Pairs - RowからValue Attribute Pairs - Columnに変更します。


以上の変更により、タスクの詳細に追加情報(Reason、Start Date、End Date)が表示されます。




自分で開始の一覧の更新



直属上司の上司の承認をとった場合、自分で開始に該当する休暇申請のタスクが2行表示されます。


自分で開始のページを開き、リージョン自分で開始 - レポートのソースのSQL問合せを以下のSELECT文に置き換えます。
select *
from table ( apex_approval.get_tasks ( p_context => 'INITIATED_BY_ME' ) )
where task_id in (
    select max(task_id)
    from apex_tasks
    where application_id = :APP_ID
    and detail_pk in (
        select id from uni_requests where requester = :APP_USER
    )
)
同じ休暇申請の場合、最後に作成されたタスクを一覧の対象にしています。


レポートを実行すると、表示が1行になっていることが確認できます。


Oracle APEX 22.1の承認コンポーネントを使った、多段階承認の実装の紹介は以上になります。

複雑なワークフローの実装であれば、Flows for APEXの利用をお勧めします。しかし、Flows for APEXではBPMNによるワークフローの定義が必須です。BPMNによるワークフローの定義まではしたくないといった場合は、このように承認コンポーネントの複数のタスクを連結することでワークフローを実装できます。

今回作成したアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/simple-approvals-component-multilevel.zip

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完

2022年8月23日火曜日

影響を受ける要素に設定された数値の合計を計算する

 動的アクションのアクションには、影響を受ける要素というプロパティがあります。影響を受ける要素に複数のページ・アイテムを設定し、そのページ・アイテムが保持している値の合計を計算してみます。

ページの構成は以下になります。

ページ・アイテムP1_ARG_1、P1_ARG_2、P1_ARG_3、P1_SUMすべて、タイプは数値フィールドです。合計を計算するボタンB_CALCを作成し、そのボタンをクリックしたときに動作するアクションとして、以下のJavaScriptを実行します。

// 影響を受ける要素として設定されているページ・アイテムの値を数値として、すべて配列に取り出す。
let args = this.affectedElements.toArray().map( elem => Number(elem.value) );
// 合計を計算する。
const sum = args.reduce(
    ( previousValue, currentValue ) => previousValue + currentValue,
    0
);
// 合計をページ・アイテムに設定する。
apex.items.P1_SUM.setValue(sum);

このとき、TRUEアクションであるJavaScriptコードの実行の影響を受ける要素として、選択タイプをアイテム、アイテムとしてP1_ARG_1、P1_ARG_2、P1_ARG_3を指定します。


TRUEアクションの影響を受ける要素は、アクションが値の設定の場合は、値が設定されるページ・アイテムを指定します。また、リフレッシュの場合は、リフレッシュされるリージョンを指定します。英語ではAffected Elementsなので、影響を受ける要素と翻訳されていますが、実際はthis.affectedElementsに渡される要素というだけで、どのように影響を受けるかはコードに依存します。JavaScriptでコードを書く場合、this.affectedElementsをどのように扱うかは、コード中で決めることができます。

今回のように、必ずしもページ・アイテムP1_SUMを影響を受ける要素として指定する必要はなく、影響を受ける要素はJavaScriptのコードが書きやすくなるように指定できます。

以上です。

簡単ですが今回作成したAPEXアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/sample-affected-elements.zip

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完

2022年8月22日月曜日

パラメータを受け取るレポートのソース設定

 レポートのソースとなる表/ビューまたはSQL問合せに、ページ・アイテムの値をパラメータとして適用する実装方法はいくつかあります。最近では、Oracle Database 19cにバックポートされた新機能SQLマクロも活用できます。

従業員名を選択するページ・アイテムを作成し、選択した従業員と同じ部門に所属する従業員をレポートに一覧します。

以下の実装方法を試してみます。

  1. SQL問合せにバインド変数を使う
  2. V関数を使ったビューにする
  3. SQL問合せを返すファンクション本体を使う
  4. SQLマクロを使う
  5. アプリケーション・アイテムを使う
  6. アプリケーション・コンテキストを使う
どの実装方法でも、以下の動作をするページになります。



準備


テスト用のデータとして、サンプル・データセットのEMP/DEPTに含まれる表EMPを使用します。

SQLワークショップのユーティリティのサンプル・データセットより、EMP/DEPTのデータセットをインストールします。言語は英語でも日本語でも構いません。今回の例では英語を選択しています。アプリケーションの作成は行いません。


アプリケーション作成ウィザードを起動します。

アプリケーションの名前をパラメータ付きレポートとします。ホーム・ページの編集を開いて、削除します。代わりにページを作成するため、ページの追加をクリックします。


追加するページはクラシック・レポートですが、対話モード・レポートを選択します(追加ページを開いて、クラシック・レポートを選ぶこともできます)。


ページ名はバインド変数とします。アプリケーションの作成後に、バインド変数を使ったレポートのソースを実装します。表またはビュー、クラシック・レポートを選択します。表またはビューとしてEMPを選択します。データの編集は行わないため、フォームを含めるにチェックは入れません。

ルックアップ列を開き、ルックアップ・キー1としてMGR、表示列1としてEMP.ENAMEを指定します。次にルックアップ・キー2としてDEPTNO、表示列2としてDEPT.DNAMEを指定します。作成されたレポートの列MGRに従業員名であるENAMEの値、列DEPTNOに部門名である列DNAMEの値が数値の代わりに表示されます。

以上の設定を行い、ページの追加をクリックします。


アプリケーションの作成を実行します。


アプリケーションが作成されました。


最初に最も一般的な方法である、バインド変数を使った実装をページ番号1のホーム・ページに行います。その他の実装は、作成したページ番号1をコピーして新たなページを作成し、そのページを改変します。


SQL問合せにバインド変数を使う



リージョンEmployeesに従業員を選択するページ・アイテムP1_ENAMEを作成します。

識別の名前としてP1_ENAME、タイプとして選択リストを選びます。ラベルはEnameとします。LOVのタイプとしてSQL問合せを選択し、SQL問合せとして以下を記述します。

select ename d, ename r from emp

追加値の表示はOFF、NULL値の表示はONとし、NULL表示値として-- 従業員を選択--と記述します。


ページ・アイテムP1_ENAMEの値を変更した際にレポートをリフレッシュするため、P1_ENAMEに動的アクションを作成します。

作成した動的アクションの識別の名前はonChange Refresh EMPとします。ページ・アイテムに動的アクションを作成すると、タイミングはデフォルトで、イベントは変更、選択タイプはアイテム、アイテムはP1_ENAMEになります。


TRUEアクションはリフレッシュに変更し、影響を受ける要素の選択タイプとしてリージョンを選び、リージョンとしてEmployeesを選択します。


クラシック・レポートのリージョンEmployeesを選択し、ソースのタイプを表/ビューからSQL問合せに変更します。SQL問合せとして、選択した従業員と同じ部門の従業員が一覧されるよう、以下のSELECT文を記述します。
select
    empno
    , ename
    , job
    , mgr
    , hiredate
    , sal
    , comm
    , deptno
from emp
where deptno in (
    select deptno from emp where ename = :P1_ENAME
)
送信するページ・アイテムとしてP1_ENAMEを指定します。


以上で、バインド変数を使った検索の絞り込みは完成です。

これが最も一般的な実装でしょう。


ページのコピーを作成する



ページのコピーを実行します。作成メニューからコピーとしてのページを実行します。


次のコピーとしてのページを作成として、このアプリケーションのページを選択します。

次へ進みます。


コピー元ページとして、1.バインド変数を選択します。新規ページ番号は2、新規ページ名はV関数を使ったビューとします。

次へ進みます。


ナビゲーションのプリファレンスとして、新規ナビゲーション・メニュー・エントリの作成を選択します。新規ナビゲーション・メニュー・エントリは、ページ名がデフォルトとして設定されます。

次へ進みます。


ラベルなどの値は変更せず、コピーを実行します。


ページのコピーが作成されます。コピーされたページを改変して、それぞれの実装を確認します。


V関数を使ったビューにする



ページのコピーをページ番号2、ページ名をV関数を使ったビューとして作成します。

以下の定義にて、ビューemp_in_same_dept_vを作成します。
create or replace view emp_in_same_dept_v(empno, ename, job, mgr, hiredate, sal, comm, deptno)
as
select
    empno
    , ename
    , job
    , mgr
    , hiredate
    , sal
    , comm
    , deptno
from emp
where deptno in 
(
    select deptno from emp where ename = V('P2_ENAME')
);
ビューを定義しているSELECT文にバインド変数は使えないため、代わりにV関数を使用しています。

レポートのソースのタイプを表/ビューに変更し、表名としてビューEMP_IN_SAME_DEPT_Vを指定しています。送信するページ・アイテムはP2_ENAMEです。


以上で、V関数を使ったビューによる実装は完成です。バインド変数を使った実装と、動作に違いはありません。

ただし、このようなビューの実装はほとんど使い道がありません。
  1. ページ・アイテム名としてP2_ENAMEが埋め込まれていて、ビューとして再利用ができない。
  2. V関数が値を返すには、APEXセッションが開始している必要がある。(APEX_SESSION.CREATE_SESSIONまたはATTACHが呼び出されている必要がある)。
  3. 2、3より、このビューを使った単体テストの実施が難しい。
  4. V関数による値の取得は遅い。
V関数のパフォーマンスについては、Srihari Ravvaさん(Oracle APEXの開発チームの方)が彼のブログ記事 - Oracle APEX SYS_CONTEXT vs V Function - で検証しています。

V関数はつねにセッション・ステートとして保存されている値を返すと思っていたのですが、実際は、送信されたページ・アイテムの値を返すようです。それが無い場合、セッション・ステートの値を返します。また、ページ・アイテムP2_ENAMEのソースのセッション・ステートの保持がリクエストごと(メモリーのみ) - つまりセッション・ステートとして保存されない - であってもV関数は送信されたページ・アイテムが設定されていると、その値を返します。

とはいえ、他に実装の選択肢がある場合、V関数の使用は避けるべきです。


SQL問合せを返すファンクション本体を使う



ページのコピーをページ番号3、ページ名をファンクション本体として作成します。

従業員名を引数として、同じ部門に所属する従業員を一覧するSELECT文を生成するファンクションgen_select_emp_in_same_deptを作成します。SQLインジェクションを抑止するため、DBMS_ASSERT.ENQUOTE_LITERALを使用します。

create or replace function gen_select_emp_in_same_dept(
    p_ename in varchar2
)
return varchar2
as
    l_stmt varchar2(32767);
begin
    l_stmt := 'select empno, ename, job, mgr, hiredate, sal, comm, deptno from emp';
    l_stmt := l_stmt || ' where  deptno in (select deptno from emp where ename = ' || dbms_assert.enquote_literal(p_ename) || ')';
    return l_stmt;
end gen_select_emp_in_same_dept;

ソースのタイプをSQL問合せを返すファンクション本体に変更し、ソースとして以下を記述します。

return gen_select_emp_in_same_dept(:P3_ENAME);

送信するページ・アイテムとしてP3_ENAMEを指定します。


以上で実装は完了です。

この実装では、リテラルの異なるSQLが毎回生成されているため、SELECT文のパース処理もその度に実行されています。そのため、パフォーマンス面に悪い影響があります。

また、gen_select_emp_in_same_deptはOracle APEXのアプリケーションの中からでなくても実行できるため単体テストが可能ですが、返されるのがSELECT文であるため、動的SQLとして実行させる必要があります。


SQLマクロを使う



ページのコピーをページ番号4、ページ名をSQLマクロとして作成します。

従業員名を引数として、同じ部門に所属する従業員を一覧するSELECT文を生成するSQLマクロmacro_select_emp_in_same_deptを作成します。
create or replace function macro_select_emp_in_same_dept(
    p_ename in varchar2
)
return clob sql_macro
as
    l_stmt clob;
begin
    l_stmt := 'select empno, ename, job, mgr, hiredate, sal, comm, deptno from emp';
    l_stmt := l_stmt || ' where  deptno in (select deptno from emp where ename = p_ename)';
    return l_stmt;
end macro_select_emp_in_same_dept;

ソースのSQL問合せを、SQLマクロを使ったSELECT文に変更します。
select
    empno
    , ename
    , job
    , mgr
    , hiredate
    , sal
    , comm
    , deptno
from macro_select_emp_in_same_dept(:P4_ENAME)
送信するページ・アイテムとしてP4_ENAMEを指定します。


SQLマクロを使ったSQLは、単体での実行も可能です。

引数に従業員名としてALLENを指定し、SQLコマンドで上記のソースであるSELECT文を実行した結果になります。



アプリケーション・アイテムを使う



ページのコピーをページ番号5、ページ名をアプリケーション・アイテムとして作成します。

V関数を使ったビューで作成したビューEMP_IN_SAME_DEPT_Vでは、ページ・アイテムP2_ENAMEを内部で参照しています。そのため、ページが変わると再利用ができません。この部分をアプリケーション・アイテムに置き換えます。

アプリケーション・アイテムG_ENAMEを作成します。

共有コンポーネントのアプリケーション・アイテムを開きます。


作成済みのアプリケーション・アイテムが一覧されます。作成をクリックします。


アプリケーション・アイテムの名前をG_ENAMEとします。有効範囲はアプリケーション、セキュリティのセッション・ステート保護として、一番保護が厳しい、制限付き - ブラウザから設定不可を選択します。

アプリケーション・アイテムの作成をクリックします。


アプリケーション・アイテムG_ENAMEが作成されます。


アプリケーション・アイテムG_ENAMEの値で、一覧する従業員を制限するビューEMP_IN_DEPT_Vを作成します。ビューEMP_IN_SAME_DEPT_VのP2_ENAMEをG_ENAMEに置き換えています。
create or replace view emp_in_dept_v(empno, ename, job, mgr, hiredate, sal, comm, deptno)
as
select
    empno
    , ename
    , job
    , mgr
    , hiredate
    , sal
    , comm
    , deptno
from emp
where deptno in 
(
    select deptno from emp where ename = V('G_ENAME')
);

ページ・アイテムP5_ENAMEの値が変更されたときに実行される動的アクションの、リフレッシュの前にTRUEアクションを作成します。

識別のアクションとしてサーバー側のコードを実行を選択します。設定の言語としてPL/SQL、PL/SQLコードとして、以下を記述します。ページ・アイテムP5_ENAMEの値をアプリケーション・アイテムG_ENAMEに設定しています。

:G_ENAME := :P5_ENAME;

送信するアイテムにP5_ENAMEを設定します。戻すアイテムの指定は、画面に戻す値です。G_ENAMEは画面に戻す値では無いので、戻すアイテムとして指定する必要はありません。


レポートのソースの表/ビューとして、EMP_IN_DEPT_Vを指定します。送信するページ・アイテムの指定は不要です。ページ・アイテムP5_ENAMEの値は、onChange Refresh EMPとして作成した動的アクションでサーバーに送信済みです。


以上で実装は完了です。

ビューのコードに埋め込んだアイテムがアプリケーション・アイテムであるため、ビューEMP_IN_DEPT_Vの再利用ができるようになっています。ただし、APEXセッションが開始されている必要があること、V関数のパフォーマンスが良く無い点については変わりありません。


アプリケーション・コンテキストを使う



ページのコピーをページ番号6、ページ名をアプリケーション・コンテキストとして作成します。

アプリケーション・コンテキストを扱う権限をAPEXのワークスペース・スキーマに割り当てます。

grant create any context to <APEXワークスペース・スキーマ>;
grant execute on dbms_session to <APEXワークスペース・スキーマ>;

今回の作業ではAutonomous Databaseを使用しているため、データベース・アクションのSQLより以下のコマンドを実行しました。APEXのワークスペース・スキーマの名前はwksp_apexdevです。

grant create any context to wksp_apexdev;
grant execute on dbms_session to wksp_apexdev;



APEXにて、以下のSQLスクリプトを実行します。アプリケーション・コンテキストEMP_DEPT_CTX、アプリケーション・コンテキストを操作するパッケージEMP_DEPT_CTX_PKG、アプリケーション・コンテキストを使ったビューEMP_IN_DEPT_APPCTX_Vを作成しています。

アプリケーション・コンテキストを使用する場合、動的アクションによるリフレッシュは利用できません。アプリケーション・コンテキストに値を設定したデータベース・セッションと、レポートのリフレッシュの際に発行されたAjaxコールを処理するデータベース・セッションが異なることがあるためです。アプリケーション・コンテキストに設定した値は、同一のデータベース・セッションからのみ参照することができます。

そのため、ページ・アイテムP6_ENAMEの設定の選択時のページ・アクションをRedirect and Set Valueに変更します。作成済みの動的アクションは削除します。


レンダリング前にプロセスを作成し、アプリケーション・コンテキストに値を設定します。

作成したプロセスの識別の名前はコンテキストの設定とします。タイプはコードの実行です。ソースのPL/SQLコードとして、以下を記述します。

emp_dept_ctx_pkg.set_ename(:P6_ENAME);

アプリケーション・コンテキストEMP_DEPT_CTXにENAMEとして、ページ・アイテムP6_ENAMEの値を設定します。


ソースの表名にEMP_IN_DEPT_APPCTX_Vを指定します。


ページ・アイテムP6_ENAMEを切り替えるたびに、変更が保存されていない旨の警告が表示されます。その警告を抑止するため、ページ・プロパティのナビゲーションの保存されていない変更の警告をOFFに変更します。


以上で、アプリケーション・コンテキストを使った実装は完了です。

アプリケーション・コンテキストを使用すると、V関数のような速度の低下は発生しないようです。そのため、ビューを作る必要がある場合は、V関数ではなくアプリケーション・コンテキストを使用するのが望ましいです。

また、以下のマニュアルに記載があるAPP_ID、APP_USER、APP_SESSIONといったSYS_CONTEXT変数として参照可能な組み込み置換文字列は、パフォーマンス上の利点よりV関数ではなくSYS_CONTEXT変数として参照することが推奨されています。

Oracle APEXアプリケーション・ビルダー・ユーザーズ・ガイド


おおむね実装方法としての推奨は、バインド変数、SQLマクロ、アプリケーション・コンテキストの順になりますが、要件が変わればこの順番も変わります。特に複雑なSQLで単体テストを行う必要がある場合は、SQLマクロやアプリケーション・コンテキストを使ったビューを使った実装は、検討する価値があるでしょう。

以上になります。

今回作成したAPEXアプリケーションのエクスポートを以下に置きました。grant create contextやexecute on dbms_sessionは、アプリケーションのインポート前に実施しておきます。
https://github.com/ujnak/apexapps/blob/master/exports/sample-report-with-parameter.zip

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完