2021年1月7日木曜日

Oracle APEXアプリケーションのデプロイメントに使用できる設定の紹介

幸運なことに作成したOracle APEXのアプリケーションを使う人が増え、色々機能を追加していくと、次第にページが増えていきます。ある程度ページが増えてくると、アプリケーションを更新するのが辛くなります。

基本的にOracle APEXアプリケーションのデプロイメントの単位はアプリケーションなので、それに大量のページが含まれていると、その内の1ページだけの変更であっても、エスクポートは全ページで、インポートも全ページの置き換えになります。また、変更が1ページであっても、それに伴って共有コンポーネントも変更しているかもしれませんし、改変したアプリケーションと現行のアプリケーションとの差分を、稼働しているアプリケーションに適用する、というのも難しい作業です。置き換える単位がアプリケーションであれば、テストの単位もアプリケーションとなるのが通常でしょう。

本記事では、上記のような難しさを軽減するために、比較的容易に採用できる方法について紹介します。項目は以下になります。

  1. 例題アプリケーションの作成
  2. アプリケーションの分割
  3. セッションの共有
  4. ホーム・ページ、ログイン・ページの共有
  5. ナビゲーションの更新
  6. 共有コンポーネントのサブスクリプション
  7. 別名の付け替えと可用性の設定
  8. その他の利用可能な機能

最初に例題となるアプリケーションを作成し、そのアプリケーションに対して、ここでリストした作業を実施していきます。

例題アプリケーションの作成

SQLワークショップのサンプル・データセットより、プロジェクト・データをインストールし、それを元にアプリケーションを作成します。

SQLワークショップのユーティリティに含まれるサンプル・データセットを開きます。

プロジェクト・データのインストールをクリックします。

データセットの説明が表示されます。次へ進みます。

インストールされるデータセットがリストされます。確認してデータセットのインストールを実行します。

ロード結果が表示されます。そこからアプリケーションの作成を起動します。

言語を日本語(ja)に変更し、それ以外はそのままにしてアプリケーションの作成を行います。

以上で例題にするアプリケーションが完成しました。

アプリケーションの分割

作成されたアプリケーションを以下に示すように、アプリケーションの別名dm-projects-001と別名dm-projects-002の、2つのアプリケーションに分割します。

Home, Dashboard, Statuses, Project Statusはdm-projects-001、Projects, Milestones, Tasks Project Task, Task Calendarはdm-projects-002、それ以外のページは双方のアプリケーションに残します。

作成されているアプリケーションをコピーします。タスクからこのアプリケーションのコピーを実行します。

新規アプリケーション名はDemonstration - Projects - Homeとします。サポートするオブジェクトの定義のコピーは不要なので、OFFです。次へ進みます。

確認画面からアプリケーションのコピーを実行します。

これで同一のアプリケーションが、ワークスペースに2つ存在することになります。最初にアプリケーションDemonstration - Projects - Homeをアプリケーション・ビルダーで開き、別名をdm-projects-001と設定します。これからの説明は、簡易URLはONとOFFのどちらでも有効ですが、簡易URLがサポートされているバージョンであればONにするべきでしょう。設定ののち、変更の適用をクリックします。

このアプリケーションから、ページ3, 4, 5, 6, 7を削除します。ページ・デザイナにて、ひとつひとつページを開いて、削除していきます。

カスケード削除の確認を要求された場合は、いいえ - 対応するリスト・エントリを削除しないを選びます。そしてページを完全に削除を実行します。

アプリケーションdm-projects-001よりページを削除したら、次にアプリケーションDemonstration - Projectsを開き、別名をdm-projects-002として設定し、こちらからはページ1, 2, 8, 9を削除します。

以上でアプリケーションの分割は完了です。次から、分割したアプリケーションを一体で動作するように設定を行なっていきます。

セッションの共有

それぞれのアプリケーションをアプリケーション・ビルダーで開き、共有コンポーネントの認証スキームを開きます。

カレントの認証スキームを開き、セッション共有の設定を変更します。Cookie名は任意の値(ここではORA_WWV_APP_CUSTOM_PROJECTSとしています)ですが、それ以外はOracle APEXをホストしているサーバーの環境によって決まる値ですので、ご自身の環境に合った値を設定してください。

  • タイプ: カスタム
  • Cookie名: ORA_WWV_APP_CUSTOM_PROJECTS
  • Cookieパス: /pls/apex/
  • Cookieドメイン: apex.oracle.com
  • セキュア: ON

分割したアプリケーションの両方に同じ設定を行うことで、クッキーに設定されるセッション識別子をアプリケーションで共有します。

ホーム・ページ、ログイン・ページの共有

今回はDemonstration - Projects - Home(別名dm-projects-001)のアプリケーションにホーム・ページを残しているため、別名dm-projects-002のアプリケーションは、ホーム・ページとログイン・ページとしてdm-projects-001のものを使うようにします。

dm-projects-002のアプリケーションのアプリケーション定義のユーザー・インターフェースを開き、属性のホームURLとログインURLを変更します。

  • ホームURL: f?p=dm-projects-001:home:&SESSION.
  • ログインURL: f?p=dm-projects-001:LOGIN:&APP_SESSION.::&DEBUG.:::

&APP_ID.置換文字列は自分自身のアプリケーションIDを意味するので、これを分割したアプリケーションであるdm-projects-001へ置き換えます。また、ホームURLのページが1として数値で設定されていたので、別名のhomeに置き換えています。アプリケーションIDやページIDとして指定する部分には、できるだけ数値は使わない方がアプリケーションのメンテナンスが容易になります。

こちらについては、アプリケーションdm-projects-002だけの変更になります。アプリケーションに認証が必要なアクセスがあった場合、および、ホームページに移動する場合は、アプリケーションdm-projects-001へ遷移するようになります。

ナビゲーションの更新

ページ1, 2はアプリケーションdm-projects-001、ページ3, 4, 5, 6, 7はアプリケーションdm-projects-002をアクセスするよう、ナビゲーション・メニューを更新します。

共有コンポーネントのリストを開きます。この中のデクストップ・ナビゲーション・メニューとページ・ナビゲーションを変更します。

他にも変更すべきリストがあるのですが、今回の例題の確認には影響がないため、そのままにします。

デスクトップ・ナビゲーション・メニューを開いて、グリッド編集をクリックします。


分割されたアプリケーションを指すエントリのターゲットに、アプリケーションの別名を指定します。

アプリケーションdm-projects-001では、以下のターゲットを変更します。HomeとDashboardはそのままでも大丈夫なのですが、ページ番号をページの別名に置き換えています。
  • Home: f?p=&APP_ID.:home:&APP_SESSION.::&DEBUG.:
  • Dashboard: f?p=&APP_ID.:dashboard:&APP_SESSION.::&DEBUG.:
  • Projects: f?p=dm-projects-002:projects:&APP_SESSION.::&DEBUG.:
  • Milestones: f?p=dm-projects-002:milestones:&APP_SESSION.::&DEBUG.:
  • Tasks: f?p=dm-projects-002:tasks:&APP_SESSION.::&DEBUG.:
  • Tasks Calendar: f?p=dm-projects-002:tasks-calendar:&APP_SESSION.::&DEBUG.:
アプリケーションdm-projects-002では、以下のターゲットを変更します。
  • Home: f?p=dm-projects-001:home:&APP_SESSION.::&DEBUG.:
  • Dashboard: f?p=dm-projects-001:dashboard:&APP_SESSION.::&DEBUG.:
  • Projects: f?p=&APP_ID.:projects:&APP_SESSION.::&DEBUG.:
  • Milestones: f?p=&APP_ID.:milestones:&APP_SESSION.::&DEBUG.:
  • Tasks: f?p=&APP_ID.:tasks:&APP_SESSION.::&DEBUG.:
  • Tasks Calendar: f?p=&APP_ID.:tasks-calendar:&APP_SESSION.::&DEBUG.:

ページ・ナビゲーションも同様に変更します。ページ・ナビゲーションはホーム・ページでのみ使用されるので、dm-projects-001だけ変更します。

以下のターゲットを変更します。

  • Dashboard: f?p=&APP_ID.:dashboard:&APP_SESSION.::&DEBUG.:
  • Projects: f?p=dm-projects-002:projects:&APP_SESSION.::&DEBUG.:
  • Milestones: f?p=dm-projects-002:milestones:&APP_SESSION.::&DEBUG.:
  • Tasks: f?p=dm-projects-002:tasks:&APP_SESSION.::&DEBUG.:
  • Tasks Calendar: f?p=dm-projects-002:tasks-calendar:&APP_SESSION.::&DEBUG.:

アプリケーションにたいして簡易URLを設定していても、ナビゲーションに指定するURLについてはf?p=形式のURLを使用できます。簡易URLの形式で指定するにはワークスペース名を含める必要があるなど、ナビゲーションの宛先URLとしては使いにくいのでf?p=形式で指定できるのは助かります。

ページの遷移にまつわる設定は以上で完了です。アプリケーションを実行して動作を確認してみます。

どちらのアプリケーションを実行しても、ログイン・ページはアプリケーションdm-projects-001に含まれるページが開きます。


ログインすると以下のエラーが発生しました。


コピーとして作成したアプリケーション(今回の手順ではdm-projects-001がコピー)の、共有コンポーネントのアプリケーション・アクセス制御を開きます。


ユーザー・ロール割当ての追加を実行します。アプリケーション作成時に追加したアクセス制御の機能が有効な範囲はアプリケーション単体で、コピーしたアプリケーションやエクスポート/インポートしたアプリケーションにユーザー・ロールの割当てはコピーされません。


今現在ログインしているユーザー名を指定し、アプリケーション・ロールとして管理者とコントリビュータにチェックを入れ、割当ての作成を行います。


 アプリケーション・ロールがユーザーに割当たったことを確認します。


アプリケーション・ロールを有効にするためには再度ログインする必要があります。エラーが表示されているページのURLよりsession=を取り除いてアクセスする、ブラウザを一旦閉じるなどして、セッションを初期化してログインし直します。

サイド・メニューやホーム・ページのナビゲーションをクリックして、アプリケーション自体も遷移すること、アクセスするアプリケーションが変わっても再認証が求められないことを確認します。



共有コンポーネントのサブスクリプション


共有コンポーネントはサブスクリプションの設定によって、異なるアプリケーションに作成されている共有コンポーネントの定義を流用することができます。

サブスクリプションの元となる共有コンポーネントを保持するためのアプリケーションを名前Demonstration - Project - Root、別名dm-projects-rootとして作成します。dm-projects-001をコピーします。アプリケーションのコピーの手順、別名の設定については、すでに説明済みですので、そちらの手順に沿って行います。


他のアプリケーションからサブスクライブされている共有コンポーネントを保持しているアプリケーションは、入れ替えや削除を行うと影響が大きいので、エンドユーザーに提供する画面などを含まず、別のアプリケーションとすることを推奨します。今回は例題なので、作成したコピーからのページ削除の実施は省きます。

続いて、共有コンポーネントのLOVにサブスクリプションの設定を行なってみます。アプリケーションdm-projects-001をアプリケーション・ビルダーで開き、共有コンポーネントのLOVを開き、EBA_PROJECTS.NAMEを開きます。


サブスクリプションとして、マスターLOVの参照元を設定します。リフレッシュにチェックが入っていると、変更を適用したときにマスターLOVの設定で上書きされます。


サブスクリプションの設定がされていると、リストにサブスクライブ元となるアプリケーションIDが表示されます。


再度、EBA_PROJECTS.NAMEを開きます。


マスターLOVおよび、それをサブスクライブしているLOVの双方で、それぞれLOVの設定を変更することが可能です。LOVのリフレッシュを実行するまでは、マスターLOVの設定で上書きされることはありません。

サブスクリプションをサポートしている共有コンポーネントでは、親となるアプリケーションにコンポーネントを作成し、そのアプリケーションからコンポーネントをサブスクライブするように設定することで、設定作業の冗長化を避けることができます。

別名の付け替えと可用性の設定


小さな単位に分割したアプリケーションのコピーを作成して、アプリケーションの改良といった作業を進めることもできます。

例えばアプリケーションdm-projects-001のコピーを作成し、Dashboardページを改良することができます。新規アプリケーション名はDemonstration - Projects - Newとします。


作成したアプリケーションのコピーは、別名としてdm-projects-001-newを設定します。

コピーしたアプリケーションを実行します。アプリケーションを実行してサイド・メニューやナビゲーションを辿ると別のアプリケーションへ遷移することがあるので注意が必要です。

以下のようにレイアウトを変えてみました。(Dashboardの改良自体が本題ではないので、どのように変更してもかまいません)。


アプリケーションの別名を入れ替えることにより、利用中のアプリケーションと更新したアプリケーションを交換することができます。

アプリケーションの定義を開き、別名dm-projects-001をdm-projects-001-oldに変更し、その後、dm-projects-001-newをdm-projects-001へ変更します。

先に、現在利用中のアプリケーションの別名を変更します。


続いて、機能を変更したアプリケーションの別名を変更します。


以上でアプリケーションの入れ替えが完了です。入れ替えたアプリケーションに問題があれば、別名の割り当てを元に戻せば、以前の状態に戻ります。(同時にバージョンやアプリケーション・グループなども更新すると、対応としてはより良くなります)。

このままの状態であれば、URLを意図的に指定することで、以前のアプリケーションと新しいアプリケーションの両方にアクセスできます。古いアプリケーションのアプリケーション定義を開き、可用性を定義することで、古いアプリケーションへのアクセスを禁止し、新しいアプリケーションの利用を強制することができます。

可用性のステータスとして使用不可(URLにリダイレクト)を選択し、使用できないアプリケーションに対するメッセージとして、リダイレクト先となるURLを指定します。


URLは簡易URLが使用される場合は簡易URLで、そうでない場合はf?p=の形式で指定します。リダイレクト先となるアプリケーションは別ワークスペースや別インスタンスのアプリケーションでも指定可能ですし、単なるHTTPのリダイレクト先ですので、Oracle APEXのアプリケーションでなくても指定できます。

ブックマークされたURLがすでに簡易URLの場合は、アプリケーションの指定は名称によるので、別名の入れ替えだけでブックマークはそのまま有効です。そのため、可用性の設定は必ずしも必要ではありません。簡易URLが導入される前のf?p=形式で、アプリケーションIDとして数値が使われている場合は、可用性の設定により新しいアプリケーションにリダイレクトさせることが可能になり、以前のブックマークにアクセスするとエラーが発生するといったことを抑制できます。

その他の利用可能な機能


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


アプリケーション・アイテムをアプリケーション間で共用するには、有効範囲をグローバルとします。


APEXコレクション


APEXコレクションはアプリケーション間では共用できません。そのため分割したアプリケーション間でデータの受け渡しを行うには、APEXコレクションの代わりに実表を作るなどの対応が必要になります。

APEX_PAGE.GET_URL


ページ遷移のターゲットとなるURLの生成には、APEX_PAGE.GET_URLをできるだけ使用し、APEX_UTIL.PREPARE_URLの使用は避けます。APEX_UTIL.PREPARE_URLを使用してチェックサムをつけるには、引数として指定するURL(p_url)を、文字列として作る必要があります。

APEX_UTIL.HOST_URL


ターゲットを指定する完全なURLを作成する際にAPEX_PAGE.GET_URLが使えない場合は、APEX_UTIL.HOST_URLを使用し、サーバー名などの直書きを避けます。アプリケーションをコピーすることで別名を変更したり、エクスポート/インポートすることで開発環境と本番環境の間でアプリケーションをコピーしたときに、URLを直書きしていると手作業で修正しなければなりません。

毎回APEX_UTIL.HOST_URLを呼び出すことを避けるために、認証後や新規インスタンス(新規セッション)開始時に、アプリケーション・アイテムへアプリケーションの計算によって値を設定しておくこともできます。


ビルド・オプション


アプリケーションのテストに使用するページ、リージョンなど、本番利用時にはアクセス不可にするためにビルド・オプションが使えます。

例えば、以下のようにテスト中を示す静的コンテンツのリージョンをページに追加します。


共有コンポーネントのビルド・オプションを開きます。


ビルド・オプションとしてテストに使用、ステータスを含める、として作成します。


作成したリージョン(リージョンに限らず、ほとんどのコンポーネントにはビルド・オプションの指定があります)の構成のビルド・オプションとしてテストに使用を選択します。


これでテスト中です。と表示しているリージョンとビルド・オプションが紐づけられました。

ビルド・オプションのステータスを除外に変更します。変更を適用します。


この状態で最初のページを表示すると、リージョンが表示されないことが確認できます。


ビルド・オプションによる除外は、サーバー側の条件とは異なり、除外されたコンポーネントはアプリケーションに存在自体していない扱いになります。

ビルド・オプションのその他の機能やSQLclでのLiquibaseの使用など、より進んだOracle APEXのアプリケーションのデプロイメントについては、また記事を改めて紹介したいと思います。

完

2021年1月5日火曜日

Oracle APEXでWebコンポーネントを扱う

 Oracle IndiaのSrihari RavvaさんがWeb Components in Oracle APEXとして、WebコンポーネントをOracle APEXで扱う方法を紹介しています。面白いトピックなので、自分でも試してみました。

環境に依存せずに作業を試行できるよう、いくつか手順を変えています。特にJavaScriptから呼び出すRESTful APIを独自のものから、Oracle APEXのRESTful APIのサンプルとして提供されているoracle.example.hrを使うようにしています。

確認作業は以下の順番で行います。

  1. Oracle APEX Builder Extension by FOSを導入する。
  2. RESTfulサービスのサンプルをインストール(またはリセット)する。
  3. 空のアプリケーションを作成する。
  4. 静的アプリケーション・ファイルに、WebコンポーネントとなるJavaScriptのコードを記述する。
  5. 静的リージョンを作成し、動作を確認する。
  6. 動的アクションを作成し、動作を確認する。
1、2、3が準備作業、4、5、6が元記事に記載のあるWebコンポーネントにまつわる作業です。

Oracle APEX Builder Extension by FOSを導入する



FOEX GmbHが開発した、Oracle APEXの静的アプリケーション・ファイル、静的ワークスペース・ファイルやプラグインのファイルを、Monaco Editorで直接編集可能にするブラウザの拡張機能です。

こちらよりChromeまたはFirefoxのウェブストアへ移動し、拡張機能を導入します。

この拡張機能を導入しなくても、手元で編集したファイルを静的アプリケーション・ファイルとしてアップロードすることもできます。

RESTfulサービスのサンプルをインストール(またはリセット)する


SQLワークショップよりRESTfulサービスを開きます。


RESTfulサービスは、Oracle REST Data Servicesによって実装されています。Oracle APEXでは、サービスを作成するためのユーザー・インターフェースのみ提供しています。Oracle REST Data Servicesによって、Oracle APEXのワークスペースに紐づいているスキーマが扱えるよう、ORDSにスキーマを登録を実行します。

今回はサンプル・サービスをそのまま利用するので、サンプル・サービスのインストールをONにし、スキーマ属性の保存を実行します。


以上でサンプル・サービスが利用可能になっています。すでにRESTfulサービスが有効になっている場合は、サンプル・サービスのリセットを実施します。


警告が表示されます。oracle.example.hrモジュールおよび表EMPとDEPTが削除され、再作成されることに注意してください。困る場合は、検証の際に使用する従業員の情報を調整することにして、リセットせずに作業を進めましょう。リセットすることに問題がなければ、サンプル・サービスのリセットを実行します。


ORDSハンドラ定義を開いて、完全なURLを確認します。今回使用するREST APIは、モジュールoracle.example.hrのURIテンプレートemployees/:id、メソッドはGETです。


Webコンポーネントの中から、この完全なURLに従業員番号(EMPNO)を引数として与えて呼び出します。スクリーンショットに表示されている完全なURLは、それぞれの環境で異なります。

空のアプリケーションを作成する


今回の検証を実装するアプリケーションを作成します。アプリケーション・ビルダーより作成を実行します。

新規アプリケーションをクリックします。

アプリケーションの名前は任意ですが、今回はWebコンポーネント検証としています。その他は何もせず、アプリケーションの作成を実行します。

以上でアプリケーションの準備も完了しました。

JavaScriptのコードを記述する


静的アプリケーション・ファイルに、WebコンポーネントとなるJavaScriptのコードを記述します。共有コンポーネントの静的アプリケーション・ファイルを開きます。


Oracle APEX Builder Extension by FOSがインストールされているとEdit Filesの領域が表示されます。Create Fileをクリックします。


File Nameとしてemployee-info.jsを指定し、Createを実行します。


以下のコードを貼り付け、Saveを実行します。
// JavaScriptコード
// temlate要素を生成する。
const template = document.createElement('template');
// 従業員情報を表示するテンプレートとなるHTMLとCSSを記述する。
// Shadow DOMにになるので、ここで定義されたCSSはカスタム要素のemployee-data内でのみ有効。
// ページレベルで定義されているCSSはカスタム要素には適用されない。
template.innerHTML = `
  <style>
  div.employee-data {
    background: #F5F4F2;
    width: 400px;
    margin-bottom: 10px;
    border-bottom: purple 8px solid;
    padding: 4px;
  }
  div.employee-data h2{
    color: purple;
  }
  </style>
  <div class="employee-data">
    <h2></h2>
    <div class="empno">EMPNO: <span></span> </div>
    <div class="job">JOB: <span></span> </div>
  </div>
`;
// カスタム要素のためのクラスを定義する。
// 一般的にはカスタム要素の名前が custom-element であれば、 CustomElement をクラス名とする。
// 今回は employee-info がカスタム要素なので、クラス名は EmployeeInfo となる。
class EmployeeInfo extends HTMLElement {
  constructor() {
    // かならず super をコンストラクタの先頭で呼び出す。HTMLElementとして正しく初期化される。
    super();
    // Shadow DOMをアタッチする。これによりカスタム要素が独立する。
    this.attachShadow({ mode: 'open' });
    // テンプレートをクローンし、ShadowRootに追加する。
    this.shadowRoot.appendChild(template.content.cloneNode(true));
    // RESTful APIを呼び出し従業員データを取得する。
    // 従業員番号(empno)の属性を引数として、RESTful APIを呼び出す。
    // RESTful APIの応答をテンプレートの穴埋めに使用する。
    fetch('https://apex.oracle.com/pls/apex/your_workspace/hr/employees/' + this.getAttribute('empno')).then(response => response.json()).then(data => {
      this.shadowRoot.querySelector('h2').innerText = data.ename;
      this.shadowRoot.querySelector('div.empno > span').innerText = data.empno;
      this.shadowRoot.querySelector('div.job > span').innerText = data.job;
    });
  }
}
// カスタム要素 employee-info と クラス EmployeeInfo を関連づける。
window.customElements.define('employee-info', EmployeeInfo);

employee-info.jsを保存すると、employee-info.js.mapおよびemployee-info.min.jsも作成されます。

処理内容については、コードのコメントを参照してください。

静的リージョンで動作確認をする

ページ・デザイナでホーム・ページ(Page 1)を開きます。HTMLヘッダーとして以下を設定し、ホーム・ページのロード時に、先ほど静的アプリケーション・ファイルとして作成したJavaScriptのファイルを読み込みます。

<script type="module" src="#APP_IMAGES#employee-info.min.js"></script>

静的アプリケーション・ファイルを標準のJavaScriptのファイルURLではなく、HTMLヘッダーのscriptタグで読み込んでいます。これは、スクリプトをmoduleとして認識させ、グローバルから参照できないようにするためです。

次にリージョンを作成し、名前はWeb Components、タイプは静的コンテンツとします。ソースのテキストには以下を設定します。

<employee-info empno="7839"></employee-info>

リージョンの設定ができたら、ページの保存と実行を行い、動作を確認します。

以下のように、従業員KINGが表示されたら、手順通り実装できています。


動的アクションを使って動作確認をする


Webコンポーネントの表示に動的アクションを使います。再度、新規にリージョンを作成します。名前はWeb Components - Dynamic Action、タイプは静的コンテンツです。ソースのテキストには以下を設定します。

<div id="employee_data_container"></div>

表示する従業員を指定するため、ページ・アイテムの作成を実行します。名前はP1_EMPLOYEES、タイプはチェック。ボックス・グループ、ラベルはEmployeesとします。LOVのタイプは静的値とします。


LOVの静的値として、以下のペアを設定します。

表示値

戻り値

BLAKE

7698

CLARK

7782

JONES

7566

SCOTT

7788


サンプルのRESTfulサービスが初期状態でない場合は、表示値としている従業員が存在しない場合もあります。存在する従業員を探してLOVの値を登録してください。

最後に動的アクションを登録します。左ペインから動的アクション・ビューを開き、動的アクションを作成します。

名前はDisplay Employee Dataとし、タイミングとして、イベントは変更、選択タイプはjQueryセレクタ、jQueryセレクタとしてinput[name=P1_EMPLOYEES]を指定します。


実行されるアクションとして、JavaScriptコードの実行を指定し、設定のコードに以下を設定します。

// チェック・ボックスより従業員番号を取得する
let empNo = $(this.triggeringElement).val();
// 従業員番号に対応するemployee-infoのタグを探して取得する。
let employeeNode = $("employee-info[empno=" + empNo + "]");
if ($(this.triggeringElement).is(':checked')) {
    // 要素が既に存在するか確認する。存在する場合は表示する。
    if (employeeNode.length == 1)
        employeeNode.show();
    else
        // そうでない場合は、要素を追加する。
        $('#employee_data_container').append('<employee-info empno="' + empNo + '"></employee-info>');
}
else {
    // チェックが外れたときは非表示にする。
    employeeNode.hide();
}

動的アクションの設定が完了したら、ページの保存と実行を行います。この記事の先頭にあるGIF動画の動作を確認できるはずです。

以上でOracle APEXでのWebコンポーネントの実装についての記事は終了です。

実際にはより複雑な実装になるかと思いますが、元記事を読んで、基本的な実装手順について参考になる内容だと思いました。また、Oracle APEXのプラグインとして実装することで、サーバー側の条件や認可スキームなども活用できるようになり、より便利なものになるでしょう。

完

2021年1月4日月曜日

対話グリッドの列の計算方法について

 Stefan Dobreさんによるこちらの記事 How to dynamically compute Interactive Grid Columns in #orclAPEX 20.2 の紹介です。

記事に記載されている実装を行うことで、理解してみました。色々と応用ができますし、同様の処理を大量の動的アクションで実装していた方は、ずっと分かりやすく書き換えることができるでしょう。

この機能は、Oracle APEXを20.2以降よりサポートされています。

以下が確認作業の順番です。

  1. 表とアプリケーションの作成
  2. CSVファイルのロード
  3. 計算によって導出される列を、対話グリッドのSQLに追加
  4. 対話グリッド上で、列の計算を行うコードを追加
1から2までは準備作業になります。Oracle APEXによるアプリケーション作成について経験のある方にとっては、冗長かもしれません。

表とアプリケーションの作成


サンプルの受注一覧のデータより、商品(PRODUCT_NAME)の価格(PRICE)と数量(QUANTITY)より、売り上げ(REVENUE)を計算します。売り上げは

REVENUE = PRICE * QUANTITY

として計算するため、表の列には含みません。

クイックSQLに与える設定は、以下とします。
# prefix: dmt
orders
  product_name vc255 /nn
  price num
  quantity num
SQLワークショップよりクイックSQLを開き、左側に上記のモデルを入力します。

SQLの生成、SQLスクリプトを保存、レビューおよび実行を順次実行します。


SQLスクリプトが開きます。DDLの変更は不要なので、そのまま実行します。確認画面が開くので、即時実行をクリックします。


表DMT_ORDERSが作成されます。続けてアプリケーション作成を実行します。


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

作成するアプリケーションの名前は対話グリッドの計算とします。デフォルトで追加されているページをすべて削除し(編集をクリックして削除を実行)、代わりにページの追加をクリックして対話グリッドを追加します。


対話グリッドのページ名も対話グリッドの計算とします。表またはビュー、編集を許可を選択し、表またはビューとして表DMT_ORDERSを選択します。

ページの追加をクリックします。


以上の設定を行い、アプリケーションの作成を実行します。

アプリケーションが作成されます。今回の作業はページ番号1の対話グリッドの計算のページに対して実施します。



CSVファイルのロード



ロードするCSVファイルを、以下よりダウンロードします。

https://apex.oracle.com/pls/apex/japancommunity/r/simcontents/download?id=SampleOrders.csv

次にSQLワークショップのユーティリティより、データ・ワークショップを開きます。データのロードをクリックして開きます。


ファイルのアップロード(デフォルトで選択されています)より、ファイルの選択をクリックして、先ほどダウンロードしたSampleOrders.csvを選択します。


ロード先を既存の表、表としてクイックSQLで作成した表DMT_ORDERS、ファイル・エンコーディングは日本語(Shift JIS)を指定します。最初の行にヘッダーが含まれるはチェックする、列デリミタの,(カンマ)、囲み文字の"(ダブルクォート)は、デフォルトのままとします。

データのロードを行う前に、構成をクリックします。


受注番号のマップ先としてID(Number)、製品はPRODUCT_NAME(Varchar2)、単価はPRICE(Number)、数量はQUANTITY(Number)を指定します。単価と数量にはグループ・セパレータとして,(カンマ)、小数点文字として.(ピリオド)を指定します。私がテストしたときは、小数点文字のデフォルトが,(カンマ)になっていたので、設定変更は必須です。

表DMT_ORDERSに含まれる4つの列をマップして、変更の保存を行います。


構成が保存されたので、データのロードを実行します。


103行のデータがロードされていれば、ロードは成功です。続けてアプリケーションの作成を実行します。



列REVENUEをSQLに追加



対話グリッドのページをページ・デザイナで開き、対話グリッドのリージョンを左ペインより選択します。ソースのタイプをSQL問合せに切り替え、SQL問合せを以下の列REVENUEを追加したものに更新します。
select ID,
       PRODUCT_NAME,
       PRICE,
       QUANTITY,
       NVL(PRICE,0) * NVL(QUANTITY,0) as REVENUE
from DMT_ORDERS

列REVENUEが追加されます。元記事によると、今回のソリューションは編集可能な列にのみ適用可能なので、タイプを表示のみに設定することは不可です。しかし、列REVENUEは計算された結果でありユーザーからの入力は禁止したいので、外観のCSSクラスにis-readonlyを指定します。また、データベースのアップデート操作に含まれないよう問合せのみをONにします。


変更を保存して、ページを実行します。


この状態で列Price、Quantityを変更して、保存をクリックすると列Revenueに計算結果が反映されることが確認できます。

次に、保存をクリックせず、PriceやQuantityを変更するとすぐにRevenueが更新される実装を行います。


対話グリッド上の列の計算



Oracle APEX 20.2から利用可能になったcalcValueとdependsOnの機能を使用します。

列REVENUEのプロパティである詳細の列初期化JavaScriptファンクションに以下を記述します。


dependsOnとして、この列REVENUEが依存している列を指定します。REVENUEはPRICEとQUANTITYの積なので、dependsOnはPRICEとQUANTITYになります。

dependsOnで指定された列、PRICEまたはQUANTITYが変更されたときに呼び出されるファンクションをcalcValueとして記述します。戻り値が列REVENUEの値になります。

以上のコードを設定して、期待した動作になるか確認してみましょう。列REVENUEを計算しているJavaScriptのコードの部分については、理解が難しいところはないかと思います。


おまけ:書式マスクについて


数値列である列PRICEとQUANTITYに以下のような書式マスクの設定がされていると、3桁ごとに区切り文字として,(カンマ)が含まれます。

999G999G999G999G999G999G999G999G999G990

このままではparseInt()で適切な整数として変換されないので、replaceAll(",","")でカンマを取り除いています。

列PRICEやQUANTITYを変更すると列REVENUEが更新されますが、この計算結果には,(カンマ)が含まれません。一旦、対話グリッドを保存すると書式マスクが適用され、,(カンマ)が表示されます。

対話グリッドの計算結果としても,(カンマ)を含めるには、Intl.NumberFormatを使って以下のように記述することで対応できます。

以上で、対話グリッドの列の計算方法の紹介は終了です。

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

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

完