日日是Oracle APEX: プラグイン

ラベル プラグイン の投稿を表示しています。すべての投稿を表示

2025年11月20日木曜日

JSON Regionプラグインを使用して東京都こどもDX子育て支援制度レジストリのJSONを編集する

Oracle AI Database 26aiには、JSONをそのままJSONとして保存できるJSONコレクション表というオブジェクトがあります。このJSONコレクション表に東京都のオープンデータ「東京都こどもDX_子育て支援制度レジストリ」を保存し、簡単なレポートとフォームのページを作成してみます。

保存先がリレーショナル表の場合は、APEXの標準コンポーネントを使うことができます。今回はJSON形式のデータをJSONコレクション表に保存し、JSONのまま操作します。JSONのまま操作するために、Uwe Simonさんが作成されたJSON Regionプラグインを使用します。

Oracle APEXでは共有コンポーネントとしてJSONソースがあります。JSONソースを作成することにより、JSONコレクション表からAPEXのデータ・ソースを定義できます。ただし、JSONソースはデータ・プロファイル（JSONの属性を列として見せる定義）が静的に定義されています。JSONデータの属性の追加や削除に対応するには、データ・プロファイルを更新する必要があります。この作業はアプリケーションの開発者が実施し、APEXアプリケーションの更新を伴います。

リージョン・プラグインのJSON Regionは、JSONデータとJSONスキーマの定義から、動的にフォームを生成します。フォームに表示するアイテムやレイアウトは、JSONスキーマによって決まります。これは、アプリケーションに静的に記述したり、JSONデータから動的に生成したり、SELECT文を実行してデータベースから取り出したり、色々な方法で決めることができます。フォームのアイテムやレイアウトの自由度には制限がありますが、表示するデータに依存したフォームの生成が可能です。

作成するAPEXアプリケーションは以下のように動作します。アプリケーションの動作や見かけは、データソースがリレーショナル表のときと違いはありません。

以下よりAPEXアプリケーションの作成手順を紹介します。

最初に東京都の子育て支援制度をJSONのまま保存する、JSONコレクション表TOKYO_KOSODATESHIENSEIDOを作成します。

create json collection table tokyo_kosodateshienseido with etag;

APEXのSQLコマンドから実行します。

東京都オープンデータカタログサイトの東京都こどもDX_子育て支援制度レジストリのページを開き、JSON形式のデータのURLを確認します。本記事では2025年8月20日時点のデータを参照しています。

SQLコマンドで以下のコードを実行し、JSONデータのダウンロードとJSONコレクション表への投入を実施します。

実行結果には１行が挿入されました。と表示されています。PL/SQLブロックを実行したときは、このように表示されます。表に挿入された行数ではありません。

データの準備ができたので、APEXアプリケーションの作成に移ります。

空のAPEXアプリケーションを作成します。名前は東京都子育て支援制度とします。

APEXアプリケーションが作成されます。JSON Regionプラグインの導入から始めます。

APEX Worldのサイトを開き、Plug-insのタブを選択します。Plug-in typeにRegionを選択し、Search KeywordにJSONを入れてプラグインを検索します。

JSON-Region 0.9.8.0（バージョンは変わるかもしれません）が見つかるので、それを開きます。

Downloadをクリックし、プラグインやサンプル・アプリケーションを含むZIPファイルをダウンロードします。

2025年11月20日時点では、simonuwe-oracle-apex-json-region-rel-0.9.8.0-0-g67958cf.zipというファイル名で、ファイルがダウンロードされました。

このファイルを解凍しておきます。

APEXに戻り、共有コンポーネントのプラグインを開きます。

インポートをクリックします。

インポートするファイルとして、ダウンロードしたZIPファイルに含まれているplug-in/region_type_plugin_json_region_uwesimon_selfhost_e.sqlを選択します。ファイル・タイプはプラグインです。

次へ進みます。

ファイルのインポートが完了しました。次へ進みます。

プラグインをインストールします。

コンポーネント設定SQL-Query for referenced JSON-schemaのデフォルト値の設定を求められます。必須ではなく、後からでも変更できるので空白のままとします。

変更の適用をクリックします。

コンポーネント設定のページに移ります。

すでにJSON-Regionプラグインは作成されています。

JSONコレクション表TOKYO_KOSODATESHIENSEIDOをソースとした、対話モード・レポートとフォームのページを作成します。

ページの作成をクリックします。

対話モード・レポートを選択します。

レポート定義の名前は支援制度一覧、フォーム・ページを含めるをオンにし、フォーム・ページ名として支援制度を設定します。ページ番号はそれぞれ、２、３とします。

データ・ソースのソース・タイプにSQL問合せを選択し、SQL SELECT文を入力に以下を記述します。

select json_value(data,'$._id') "_id", data from tokyo_kosodateshienseido

次へ進みます。

主キー列に_id (Varchar2）を選択します。MongoDBと互換性を持つためだと思われますが、JSONコレクション表は属性"_id"として、一意キーが設定されています。

ページの作成をクリックします。

対話モード・レポートとフォームのページが作成されます。

APEXアプリケーションを実行します。

対話モード・レポートにはJSONがそのまま表示されています。任意の行の編集アイコンをクリックし、ドロワーを開きます。

ドロワーが開いたら、JSONは変更せずに、変更の適用をクリックします。

以下のエラーが発生します。これは、更新するJSONに"_id"属性が含まれていることが原因です。

ORA-54059: 不変列("WKSP_APEXDEV"."TOKYO_KOSODATESHIENSEIDO"."RESID")は別の値に更新できません

JSONコレクション表を操作するプロセス・フォーム支援制度の前に、プロセスRemove _idを作成します。タイプはコードを実行です。

ソースのPL/SQLコードに以下を記述し、受信したデータより"_id"属性を削除します。

select json_transform(:P3_DATA, remove '$._id') into :P3_DATA;

サーバー側の条件のボタン押下時にSAVEを指定します。

プロセスRemove _idを追加することで先ほどのエラーは発生しなくなり、フォームでJSONデータを更新できるようになります。

これから、ページ・アイテムP3_DATAに含まれるJSONデータからフォームを生成します。

ページ・アイテムP3_DATAの下にリージョンを作成します。

識別の名前はJSON Region、タイプに先ほど導入したプラグインであるJson-Regionを選択します。

Json-Regionの属性を開きます。

設定のJSON-itemにJSONデータが含まれるページ・アイテムP3_DATAを選択します。JSONスキーマのSourceとして、Generate Schemaを選択します。この設定では、JSONスキーマはP3_DATAに保存されているデータから生成されます。

その他は用途によって変更します。以下ではHide JSON-itemをオンにしているので、JSONデータを保持しているP3_DATAが非表示に変わります。

先ほどと同様の手順でフォームを開くと、JSONデータの代わりに自動的に生成されたフォームが開きます。

このままでは見辛いので、JSONスキーマを定義して表示されるページ・アイテムを限定します。

設定のSourceをStaticに変更し、Static Schemaに以下を記述します。

Column Widthに12を指定します。Universal Themeは横幅を12分割して配置を決めています。列幅に12を設定すると、１列すべてを１つのページ・アイテムが占有します。つまり、１列に１つだけページ・アイテムが配置されます。

先ほどと同様の手順でフォームを開きます。今度はJSONスキーマの定義に従ったフォームが開かれます。

編集も可能です。変更の適用をクリックします。

フォームのデータに一切変更を加えていないくても、JSON Regionの設定にあるKeep additional attributesやRemove NULLS from JSONといった設定により、属性が削除されることがあります。また、JSON Regionが更新するのはページ・アイテムP3_DATAに読み込まれたJSONデータであり、データベースはP3_DATAの値で更新されます。JSON_TRANSFORMを呼び出して更新する場合と異なり、JSONデータは全体が更新されます。

本記事のテーマであるJSON Regionの組み込みは以上で完了です。

対話モード・レポートの表示がJSONそのままではいけないので、属性ごとに列として表示されるように変更します。

JSONコレクション表からJSONデータガイドを生成し、それを元にビューを作成します。

SQLコマンドで以下のスクリプトを実行し、ビューTOKYO_KOSODATESHIENSEIDO_Vを作成します。

対話モード・レポートのソースのSQL問い合わせを、作成したビューTOKYO_KOSODATESHIENSEIDO_Vを参照するように変更します。

select * from tokyo_kosodateshienseido_v

対話モード・レポートで新しく認識された列は、デフォルトでは表示されません。

アクション・メニューの列を開き、新しく認識された列をレポートに表示します。

選択した列が対話モード・レポートに表示されます。これでJSONの属性がそれぞれ列として表示されるようになりました。

編集アイコンをクリックすると、ORA-1403が発生します。

これは対話モード・レポートでは主キーの値（属性"_id"の値）が大文字なのに対して（JSONデータガイドを元に作成したビューが列"_id"を大文字で返す）、フォームでは小文字で扱うためです。

フォームが"_id”の値を小文字で受け取るように、プロセス初期化フォーム支援制度の前にP3__IDの値を小文字に変換するプロセスを作成します。

識別の名前はLower P3__IDとします。ソースのPL/SQLコードに以下を記述します。

:P3__ID := lower(:P3__ID);

サーバー側の条件のタイプにアイテムはNULLではないを選択し、アイテムとしてP3__IDを設定します。

以上でAPEXアプリケーションは完成です。アプリケーションを実行すると、記事の先頭のGIF動画のように動作します。

今回作成したAPEXアプリケーションのエクスポートを以下に置きました。

https://github.com/ujnak/apexapps/blob/master/exports/sample-json-region-plugin.zip

JSON RegionのプラグインとしてダウンローしたZIPには、プラグインの他にもサンプル・プログラムなどが含まれています。便利なプラグインなので、使い方を学ぶことをお勧めします。

今回の記事は以上になります。

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

完

2024年2月2日金曜日

ポーランドのPretius社の開発者が作成したPretius Drawing Pluginを使ってみる

ポーランドに本社があるPretius Software Sp. z o.o.（Sp. z o.o.はポーランド語で有限会社のこと）に所属しているAPEX開発者のTomáš Kucharzykさんが、Pretius Drawing Pluginという、図面を書くリージョン・プラグインをGitHubに公開しています。

このプラグインの使い方を理解するために、プラグインを組み込んだAPEXアプリケーションを作成してみました。

作成したAPEXアプリケーションは以下のように動作します。

このプラグインの開発者より、以下の２本の紹介記事が公開されています。

Pretius Drawing Plugin: Free office layout planner for Oracle APEX apps

https://pretius.com/blog/pretius-drawing-plugin/

Build a train reservation system using Oracle APEX and Pretius Drawing Plugin

https://pretius.com/blog/apex-train-reservation-system/

Pluginの詳細はGitHubで公開されています。プラグインやインストールに必要なスクリプトもGitHubよりダウンロードします。

https://github.com/Pretius/pretius-drawing-plugin

ユーザー・マニュアルはこちらです。

https://github.com/Pretius/pretius-drawing-plugin/blob/main/user_manual.md

以下より、サンプル・アプリケーションの作り方を紹介します。

クイックSQLの以下のモデルを元に、表PLAN_TYPE、TYPE_COMPONENT、PDP_SHEETS、PDP_SHEET_COMPONENTSを作成します。

表PLAN_TYPEおよびTYPE_COMPONENTは、Pretius Drawing Pluginの動作に必要な表で、このプラグインのインストール・スクリプトtype_component.sqlに、これらの表を作成するDDLが含まれています。オリジナルでは以下の定義が含まれていないため、Oracle APEXのアプリケーションとして扱いにくいので修正しています。

表PLAN_TYPE、TYPE_COMPONENTの主キー列IDの値を自動生成する。
表TYPE_COMPONENTのPLAN_TYPE_IDと表PLAN_TYPEのIDで外部キー制約を付ける。
監査列の値を設定するトリガーを作成する。

表PDP_SHEETSには図面の名前を登録し、表PDP_SHEET_COMPONENTSには、その図面に含まれる図形を保存します。

クイックSQLのモデルからSQLスクリプトの生成、実行までの一連の操作を実施します。

最終的に上記４つの表と関連する索引やトリガーが作成されます。

Pretius Drawer PluginのGitHubのページを開き、スクリプトtype_components.sqlをダウンロードします。ダウンロードしたtype_components.sqlを、SQLスクリプトにアップロードして実行します。

すでに表PLAN_TYPEとTYPE_COMPONENTが作成済みのため、CREATE TABLE文とALTER TABLE文の実行は失敗します。INSERT文が成功していれば問題ありません。

SQLコマンドより以下のALTER文を実行します。自動生成される主キーの値を、type_component.sqlによってインストールされたIDの最大値に続く連番で生成されるようにしています。SQLコマンドでは、SQLの実行は１度に１行なので、１行ずつ実行します。

alter table plan_type modify id generated by default on null as identity (start with limit value);
alter table type_component modify id generated by default on null as identity (start with limit value);

以上でデータベースの準備ができました。

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

アプリケーションの名前はSample Pretius Drawingとします。

空白ページを追加します。ページ名はView Drawingとします。

ページの追加の方法として追加ページにある複数のレポートを選び、表PDP_SHEETS、PLAN_TYPEおよびTYPE_COMPONENTのフォーム付き対話モード・レポートを追加します。ページPlan TypeとType Componentは管理ページとして設定します。

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

ページ・タイプの複数のレポートは、追加ページを開くと現れます。

管理ページとして設定は、編集ダイアログの詳細に含まれています。

アプリケーションが作成されたら、Pluginが使用するAPEXコレクションの名前をアプリケーション定義の置換文字列G_COLLECTIONに設定します。今回の作業ではMY_COLLECTIONとしました。

表PDP_SHEETS、PLAN_TYPE、TYPE_COMPONENTの編集フォームに、監査列がページ・アイテムとして含まれています。これらの値はトリガーにより設定するように変更したため、ページ・アイテムがあるとページ送信時にエラーが発生します。

フォームのページを開き、監査列に対応するページ・アイテムをすべてコメント・アウトします。

ページ番号４（ページ名Pdp Sheet）、６（Plan Type）、８（Type Component）が、コメント・アウトする監査列のページ・アイテムを含むページです。

Pretius Drawing PluginのGitHubのページより、プラグインのファイルregion_type_plugin_pretius_drawing_plugin.sqlをダウンロードします。

ダウンロードしたファイルをプラグインとしてインストールします。

共有コンポーネントのプラグインを開きます。

インポートをクリックします。

インポートするファイルとしてregion_type_plugin_pretius_drawing_plugin.sqlを選択します。ファイル・タイプはプラグインです。

次へ進みます。

プラグインはすぐにインストールします。次へ進みます。

プラグインのインストールをクリックします。

プラグインがインストールされ、一覧にPretius Drawing Pluginが表示されます。

ページ・デザイナでホーム・ページを開き、Pretius Drawing Pluginを使った図面を描くリージョンを作成します。

デフォルトで作成されているリージョンページ・ナビゲーションを選択し、図面を描くリージョンに変更します。

識別のタイトルをDrawに変更し、タイプとしてアプリケーション・コンポーネントのPretius Drawing Pluginを選択します。

ソースのタイプはSQL問合せとし、SQL問合せとして以下を記述します。

リージョンの属性を開き、Collection nameに置換文字列&G_COLLECTION.を設定します。Editable (with Editor)はYesです。Pretius Drawing Pluginは、APEXコレクションにデータを保存します。

この時点でページを保存し、一旦実行してみます。

あらかじめPretius Drawing Pluginに含まれている図形を使って、図面の記述ができるようになっています。

適当にパレットから図形を選択し、図面に配置します。Saveをクリックすると、APEXコレクションに図形が保存されます。

APEXコレクションに保存されているデータを確認するために、対話モード・レポートを作成します。ソースのタイプはSQL問合せ、SQL問合せはPretius Drawing Pluginのリージョンのソースに設定したSELECT文と同じ文を記述します。

Pretius Drawing PluginでSaveを実行したときのイベントを取る方法がわからないため、図面を更新した後に対話モード・レポートをリフレッシュすることはできません。図面を保存した後にページをリロードする必要はありますが、図面がどのようなデータをを元に表示されているかを、レポートから確認することができます。

これからPretius Drawing Pluginが扱うAPEXコレクションと、表PDP_SHEET_COMPONENTSの間で、データの取り出し（Load）や保存（Save）を行う処理を追加します。

ナビゲーション・メニューよりPdp Sheetsを開き、いくつか図面を作成します。

今回の記事では、オフィス図、駐車場、簡単な図形の３つの図面を作成しました。

ページ・デザイナでホーム・ページを開きます。

図面を選択するページ・アイテムや、ロードや保存を行うボタンを配置するリージョンを作成します。

識別のタイトルはControls、タイプは静的コンテンツです。外観のテンプレートにItem Containerを選択し、テンプレート・オプションのAlignmentにStretchを選びます。

図面を選択するページ・アイテムを作成します。

識別の名前はP1_SHEET、タイプは選択リスト、ラベルはSheetとします。レイアウトのリージョンにControlsを選び、位置はItemとします。

LOVのタイプにSQL問合せを選択し、SQL問合せとして以下を記述します。

select sheet_name d, id r from pdp_sheets

追加値の表示はオフ、NULL値の表示はオン、NULL表示値として-- Select Sheet --を記述します。

リージョンControlsにボタンLOAD、SAVEおよびCLEARを作成します。ボタンLOADの位置はButton Start、SAVEとCLEARはButton Endに配置します。動作のアクションはデフォルトのページの送信とします。

どれも作業中の図面または保存済みの図面を上書きする操作なので、確認の要求をオンにします。確認のメッセージにAre you sure?と記述し、スタイルに危険を選択します。

これらのボタンから呼び出される処理を定義します。

プロセス・ビューを開きます。

図面のロードするプロセスを作成します。名前はLoad、タイプとしてコードを実行を選び、ソースのPL/SQLコードとして以下を記述します。

サーバー側の条件のボタン押下時にLOADを選択します。

同様に図面を保存するプロセスを作成します。名前はSave、タイプとしてコードを実行を選び、ソースのPL/SQLコードとして以下を記述します。

サーバー側の条件のボタン押下時にSAVEを選択します。

編集中の図面をクリアするプロセスを作成します。名前はClear、タイプとしてコードを実行を選び、ソースのPL/SQLコードとして以下の１行を記述します。

apex_collection.create_or_truncate_collection(:G_COLLECTION);

サーバー側の条件のボタン押下時にCLEARを選択します。

以上で図面を編集するページは完成です。

ページView Drawingは、APEXコレクションではなく表PDP_SHEET_COMPONENTSを参照して図面を表示するページにします。図面の編集は行いません。

ページ・デザイナでページ番号２のView Drawingを開きます。

表示する図面を選択するページ・アイテムP2_SHEETを作成します。

図面の選択なので、設定はページ・アイテムP1_SHEETとほぼ同じです。設定の選択時のページ・アクションとして値のリダイレクトと設定を選び、詳細の保存されていない変更の警告を無視にします。

図面を表示するリージョンを作成します。

識別の名前はDraw、タイプはPretius Drawing Pluginを選択します。ソースのSQL問合せとして以下を記述します。

外観のテンプレートにBlack with Attributesを選択します。

リージョンの属性を開き、Collection nameに&G_COLLECTION.、Editable(With Editor)にNoを設定します。図面の表示にAPEXコレクションを参照することはなく、図面の編集も行わないためAPEXコレクションが操作されることはないはずですが、Collection nameの指定は必須です。

以上で表PDP_SHEET_COMPONENTSを参照して図面を表示するページも作成できました。

APEXアプリケーションとしては以上で完成です。

作成したAPEXアプリケーションを使って、独自の図形を登録して図面を記述してみます。

管理メニューからPlan Typeを開きます。新規のプランを作成します。

作成をクリックします。

Plan TypeのNameは簡単な図形とします。作成をクリックします。

Plan Type簡単な図形が作成されたことを確認して、ダイアログを閉じます。

Type Componentに図形をいくつか追加します。

Type Componentを開きます。

作成をクリックします。

Plan Typeは簡単な図形、Nameは赤い円とします。

Codeに以下を記述します。

<div onClick="select()" id="drag" class="component drag circle-red"></div>

CSSにCSSクラスcircle-redの定義を記述します。

.circle-red {
  width: 100px;
  height: 100px;
  border-radius: 50%;
  background-color: red;
}

同様に青い四角も作成します。

Codeは以下です。

<div onClick="select()" id="drag" class="component drag box-blue"></div>

CSSの記述は以下です。

.box-blue {
  width: 100px;
  height: 100px;
  border-radius: 0%;
  background-color: blue;
}

これらの図形を使って図面を記述した操作が、記事の先頭のGIF動画です。

今回作成したAPEXアプリケーションのエクスポートを以下に置きました。

https://github.com/ujnak/apexapps/blob/master/exports/sample-pretius-drawing.zip

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

完

登録: 投稿 (Atom)