2024年6月25日火曜日

対話グリッドのリフレッシュ前後で行の選択を維持する

対話グリッドは単体で編集可能なのでフォームを付けるケースはあまりありませんが(一般的には対話モード・レポートにフォームを付ける)、フォームをつけたときにフォームを閉じると行の選択がリセットされます。この動作自体は、対話グリッドの通常のリフレッシュ処理なのですが、行の選択を維持したいという相談がありました。

実装が思ったよりも大変だったので、記事にしました。

サンプル・データセットのEMP/DEPTに含まれるEMP表をデータ・ソースとした対話グリッドと、フォームを作成しました。以下のように動作します。


対話グリッドを含むページのページ・プロパティに、対話グリッドで選択した行(の配列)を保持するための変数selectedIdsを宣言します。

JavaScriptのファンクションおよびグローバル変数の宣言に以下を記述します。

var selectedIds;

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


イベントのダイアログのクローズを受けて、対話グリッドをリフレッシュするTRUEアクションは作成済みです。

リフレッシュの直前に、以下のJavaScriptのコードを実行するTRUEアクションを作成します。対話グリッドで選択されている行のID(主キーの値)の配列をselectedIdsに保存します。
const model = apex.region("emp").call("getViews", "grid").model;
selectedIds = model.getSelectedRecords().map(
    (rec) => {
        return model.getRecordId(rec);
    }
);
// console.log(selectedIds);

対話グリッドのリフレッシュが完了した後に、selectedIdsに保存した行を選択した状態に戻します。

対話グリッドに動的アクションを作成します。タイミングのイベントはページ変更[対話グリッド]を選択します。ほとんどのリフレッシュ可能なコンポーネントは、イベントとしてリフレッシュ後を選べるのですが、対話グリッドではリフレッシュ後のイベントが発生しません。従って、それに近いイベントとしてページ変更を使います。

また、実行のタイプとしてデバウンスを選択し、ページ変更のイベントが発生してから100ミリ秒待機したのちに処理を開始するように設定します。100ミリ秒というのは、人が気が付かないほどの短時間で、かつ、JavaScriptの処理が空振りしない程度の時間として選んでいます。


TRUEアクションとして実行するJavaScriptコードは以下になります。行の選択はfetchRecordsの処理が完了した後に実行するようにしています。
// console.log('after', selectedIds);
const model = apex.region("emp").call("getViews", "grid").model;
model.fetchRecords(
    apex.region("emp").call("setSelectedRecords", selectedIds)
);

以上で実装は完了です。

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

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

完


2024年6月24日月曜日

Oracle APEX標準の動的コンテンツを使って画像を表示する

htmx、Turbo Frames、Unpolyを使って画像を表示するAPEXアプリケーションを作成してきましたが、画像を表示する程度であれば、Oracle APEXの標準機能である動的コンテンツ・リージョンでできることを思い出しました。

以下よりOracle APEX標準の動的コンテンツを使用した実装を紹介します。

今回作成したアプリケーションも今までと同じく、見かけはhtmxを使ったものと同じです。


以下よりアプリケーションについて簡単に紹介します。

リージョンImageのタイプを動的コンテンツに変更し、ソースのCLOBを返すPL/SQLファンクション本体として以下を記述します。


画像の選択をするために、ページ・アイテムP1_ANIMALを作成し、送信するページ・アイテムとして設定します。


ページ・アイテムP1_ANIMALのタイプは非表示とします。動的アクションで値を設定するため、設定の保護された値はオフにします。


ボタンを押した時に実行するTRUEアクションとして、最初に値の設定を実行します。設定のタイプの設定に静的割当てを選択し、値に表示する動物のなまえを指定します。影響を受ける要素の選択タイプにアイテム、アイテムとしてP1_ANIMALを選択し、静的に割り当てた値をページ・アイテムP1_ANIMALに設定します。初期化時に実行はオフにします。


続いて、リージョンImageのリフレッシュを実行します。影響を受ける要素の選択タイプはリージョン、リージョンはImageです。こちらも初期化時に実行はオフにします。


動的アクションは3つあるので、値の設定でたぬき、シマウマ、レッサーパンダをそれぞれのアクションに設定します。

Oracle APEX標準の動的コンテンツを使った実装の紹介は以上になります。動的コンテンツによる実装の場合は、RESTサービスを作成する必要はありません。

WebSocketやSSEなどOracle APEX単体では実装が困難な機能もあります。そのような場合に、htmxやTurbo Frames(実際にはTurbo Streams)、Unpolyといったライブラリは実装の助けになるでしょう。

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

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

完

Oracle APEXでUnpolyを使用する

Oracle APEXでhtmxを使う方法とTurbo Framesを使う方法を紹介してきたので、Unpolyについても紹介します。

htmx向けのアプリケーションからの変更点を紹介します。

今回作成したアプリケーションも今までと同じく、見かけはTurbo Framsを使ったものと同じです。


以下にアプリケーションの変更点を紹介します。

アプリケーションを実装しているホーム・ページのページ・プロパティの変更から始めます。

JavaScriptのファイルURLの指定は以下になります。UnpolyのJavaScriptのコードをロードします。

https://cdn.jsdelivr.net/npm/unpoly@3.8.0/unpoly#MIN#.js

CSSのファイルURLとして以下を指定します。

https://cdn.jsdelivr.net/npm/unpoly@3.8.0/unpoly#MIN#.css

データ・ロード時に実行に以下のコードを記述します。UnpolyがAjaxコールを発行する際に、Apex-Sessionヘッダーを追加します。
document.addEventListener("up:request:load", (event) => {
    event.request.headers["Apex-Session"] = apex.env.APP_ID + "," + apex.env.APP_SESSION;
    // console.log(event);
});

画像を表示する静的コンテンツのソースのHTMLコードとして、以下を記述します。DIV要素にIDとしてimage_1を与えています。この要素を、REST APIを呼び出して取得した画像で置き換えます。

<div id="image_1"></div>


画像を返すRESTサービスでは、更新対象を示すDIV要素(Turbo Framesのときはturbo-frame要素でした)にIMG要素を含めて、HTMLを返すようにコードを変更します。

モジュール・パスは/unpoly/、テンプレートはimage/:title/:idとし、更新対象とするDIV要素のidを引数に含めました。



UnpolyでのHTML要素の入れ替えをA要素で行います。画像を更新する領域はup-target属性で指定します。
<div id="action_1">
<a class="t-Button" href="apexdev/unpoly/image/たぬき/image_1" up-target="#image_1">たぬき</a>
<a class="t-Button" href="apexdev/unpoly/image/シマウマ/image_1" up-target="#image_1">シマウマ</a>
<a class="t-Button" href="apexdev/unpoly/image/レッサーパンダ/image_1" up-target="#image_1">レッサーパンダ</a>
</div>

Unpolyを使うために実施した変更は以上になります。

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

サンプル・アプリケーションには、以前にAjaxリクエストに認証ヘッダーを追加する方法がわからなかった時に作成した、up.renderを呼び出す動的アクションの実装も含んでいます。

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

完

Oracle APEXでTurbo Framesを使用する

先日、Oracle APEXでhtmxを使用するサンプル・アプリケーションを作成しました。同じアプリケーションをHotwireのTurbo Framesで置き換えてみます。

htmxを使用するアプリケーションの作り方は、こちらの記事で紹介しています。本記事ではTurbo Framesを使用するための変更点を紹介します。

今回作成したアプリケーションは以下のように動作します。見かけはhtmxを使ったものと、ほぼ同じです。


以下にアプリケーションの変更点を紹介します。

アプリケーションを実装しているホーム・ページのページ・プロパティの変更から始めます。

JavaScriptのファイルURLの指定は以下になります。TurboのESモジュールをロードするため、<script type="module"となるように[module]を先頭に付与します。

[module]https://unpkg.com/@hotwired/turbo@8.0.4/dist/turbo.es2017-esm.js

本番環境などでは、このファイルをアプリケーションまたはワークスペースに静的ファイルとして保存し、ミニファイされたファイルをロードする方が良いでしょう。

ページ・ロード時に実行に以下を記述します。画像を取得するRESTサービスのリクエストに、Apex-Sessionヘッダーを含めます。Turboの場合はturbo:before-fetch-requestのイベントを受けて、ヘッダーの追加を行います。
document.addEventListener("turbo:before-fetch-request", (event) => {
    event.detail.fetchOptions.headers["Apex-Session"] = apex.env.APP_ID + "," + apex.env.APP_SESSION;
    // console.log(event);
});


ボタンはすべて、turbo-frame要素の中のA要素として作成します。data-turbo-frameとしてimage_1を指定することにより、idがimage_1のturbo-frame要素を、hrefの呼び出しで受け取ったHTML(今回は画像)で更新します。
<turbo-frame id="action_1">
    <a class="t-Button" href="apexdev/turbo/image/たぬき/image_1" data-turbo-frame="image_1">たぬき</a>
    <a class="t-Button" href="apexdev/turbo/image/シマウマ/image_1" data-turbo-frame="image_1">シマウマ</a>
    <a class="t-Button" href="apexdev/turbo/image/レッサーパンダ/image_1" data-turbo-frame="image_1">レッサーパンダ</a>
</turbo-frame>

画像を描画する領域のHTMLソースとして、turbo-frame要素を記述します。idはimage_1です。
<turbo-frame id="image_1"></turbo-frame>

画像を返すRESTサービスでは、更新対象を示すturbo-frame要素にIMG要素を含めて、HTMLを返すようにコードを変更します。

モジュール・パスは/turbo/、テンプレートはimage/:title/:idとし、更新対象とするturbo-frame要素のidも引数に含めました。



Turbo Framesを使うために実施した変更は以上になります。

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

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

完

2024年6月21日金曜日

Oracle APEXでhtmxを使用する

Oracle APEXのアプリケーションの作成にhtmxを使ってみます。

サンプル・アプリケーションを作成するにあたって、以下のサイトや記事を参考にさせていただきました。

htmxの本家にあるReference
https://htmx.org/reference/

@twrcd1227 (Tomoki Ota)さんによるQiitaの記事
もうjsなんていらない!世界で流行っているHTMXについてまとめてみたhttps://qiita.com/twrcd1227/items/7bce18167fb02ec22729

@tsmd (Takayuki Shimada)さんによるQiitaの記事
htmxとは何なのか? その背景にある思想について
https://qiita.com/tsmd/items/0d07feb8e02cfa213cc4

作成するアプリケーションは以下のように動作します。アプリケーション自体はhtmxを使わなければ作れない、というものではありません。htmxの面白いところは、JavaScriptを書かずに以下ような処理を実装できることです。


最初にクイックSQLの以下のモデルより、画像を保存する表EBMJ_IMAGESを作成します。
# prefix: ebmj
images /unique title
    title vc80 /nn
    content file
レビューおよび実行をクリックし、表が作成されるまで作業を進めます。


表EBMJ_IMAGESが作成されたら、アプリケーションの作成をクリックします。確認画面が開くので、そこでもアプリケーションの作成をクリックします。


生成されたアプリケーションの雛形には、作成した表EBMJ_IMAGESをソースとしたフォーム付き対話モード・レポートのページが含まれています。これはそのまま使用します。htmxを使った画像の表示はホーム・ページに実装します。

アプリケーションの名前をSample htmxとし、アプリケーションの作成をクリックします。


アプリケーションが作成されます。対話モード・レポートとフォームのページでのBLOB列の扱いを修正します。

ページ番号2の対話モード・レポートのページを開きます。


リージョンImagesに含まれる列CONTENTを選択し、BLOB属性に含まれるMIMEタイプ列にCONTENT_MIMETYPE、ファイル名列にCONTENT_FILENAME、最終更新列にCONTENT_LASTUPD、文字セット列にCONTENT_CHARSETを設定します。


ページ番号3のフォームのページを開きます。

リージョンImageに含まれるページ・アイテムP3_CONTENTを選択し、ストレージに含まれるMIMEタイプ列にCONTENT_MIMETYPE、ファイル名列にCONTENT_FILENAME、文字セット列にCONTENT_CHARSET、BLOB最終更新列にCONTENT_LASTUPDを設定します。


以上で表EBMJ_IMAGESに画像をアップロードする準備ができました。

アプリケーションを実行し、いくつか画像をアップロードします。

ナビゲーション・メニューからImagesを開き、レポート上の作成をクリックして適当な画像をアップロードします。


画像を選んでアップロードします。


その他にも、いくつかの画像をアップロードします。今回の作業では、たぬき、シマウマ、レッサーパンダの画像をアップロードしています。


表EBMJ_IMAGESより、画像のタイトルを引数として与え、画像をHTMLのIMG要素として返すRESTサービスを作成します。

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

左ペインのツリーよりモジュールを選択し、モジュールの作成をクリックします。


作成するモジュール名はsample.htmx、ベース・パスは/htmx/とします。

モジュールの作成をクリックします。


モジュールsample.htmxが作成されます。続けてテンプレートを作成します。

テンプレートの作成をクリックします。


URIテンプレートとしてimage/:titleを設定します。:titleがハンドラのコード内で、バインド変数として参照できる引数になります。

テンプレートの作成をクリックします。


リソース・テンプレートが作成されます。続けてハンドラを作成します。

ハンドラの作成をクリックします。


リソース・ハンドラのメソッドはGET、ソース・タイプはPL/SQLを選択します。ソースに以下を記述します。タイトルで表EBMJ_IMAGESを検索し取得した画像より、IMG要素を生成して呼び出し元に返しています。

ハンドラの作成をクリックします。


GETハンドラが作成されます。完全なURLをコピーし、ブラウザまたはPostmanなどのツールより、作成したRESTサービスが正常に動作することを確認します。


RESTサービスが正常に動作することを確認したのち、APEXで認証されたセッション内からの呼び出しに限り、実行を許可するように権限を設定します。

左ペインより権限を選択し、権限の作成をクリックします。


特権定義の名前はsample.htmx、タイトルはsample.htmxとします。ロールとしてRESTful Services、保護されたモジュールとしてsample.htmxを選択します。

権限の作成をクリックします。


権限としてsample.htmxが作成されます。


サインインするユーザーにロールRESTful Servicesを割り当てます。

管理メニューよりユーザーとグループの管理を開きます。


権限を割り当てるユーザーの編集画面を開きます。


グループ割当てのセクションに移動し、グループ割当てとしてRESTful Servicesを選択します。

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


以上で作成したRESTサービスの保護が完了しました。

先ほど実施した動作確認を再度行います。今度は応答が401 Unauthorizedになります。


RESTfulサービスを使った作業は以上で完了です。

アプリケーション・ビルダーに移り、htmxを組み込んだページを作成します。

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

作成済みのリージョンページ・ナビゲーションを削除します。


画像を表示するためのボタンを配置するリージョンを作成します。

識別の名前はButtons、タイプは静的コンテンツです。外観のテンプレートとしてButtons Containerを選択します。


画像を表示するリージョンを作成します。

識別の名前はImage、タイプは静的コンテンツです。外観のテンプレートにBlank with Attributes (No Grid)を選択し、CSSクラスとしてw800 h800 margin-autoを指定します。リージョンの幅と高さを800ピクセルに設定し、中央揃えにしています。

詳細の静的IDとしてimageを設定します。


ページ内でhtmxの機能を使えるように構成します。

ページ・プロパティのJavaScriptのファイルURLに以下を指定します。

https://unpkg.com/htmx.org@2.0.0

ページ・ロード時に実行に以下を記述し、htmxがRESTサービスを呼び出す際に、認証に必要なApex-Sessionヘッダーを追加します。
document.body.addEventListener('htmx:configRequest', function(evt) {
    evt.detail.headers['Apex-Session'] = apex.env.APP_ID + ',' + apex.env.APP_SESSION;
});
表示する画像をリージョン内に収めるために、CSSのインラインに以下を記述します。
img {
  max-width:100%;
  max-height: 100%;
  width: auto;
  height: auto;
}


以上でhtmxが提供する属性を要素に指定できるようになりました。

これから画像を表示するためのボタンを、リージョンButtonsに作成します。

識別のボタン名はBUTTON1、ラベルはたぬきとします。たぬきの画像を表示するボタンになります。

動作のアクションとして動的アクションで定義を選択し、詳細のカスタム属性として以下を記述します。hx-get、hx-target、hx-swapはhtmxが提供している属性です。

hx-get="apexdev/htmx/image/たぬき" hx-target="#image" hx-swap="innerHTML"


これでボタンたぬきをクリックすると、リージョンImageにたぬきの画像が表示されます。


シマウマの画像を表示するボタンを作成します。

識別のボタン名はBUTTON2、ラベルはシマウマ、詳細のカスタム属性として以下を記述します。

hx-get="apexdev/htmx/image/シマウマ" hx-target="#image" hx-swap="innerHTML"


レッサーパンダの画像を表示するボタンを作成します。

識別のボタン名はBUTTON3、ラベルはレッサーパンダ、詳細のカスタム属性として以下を記述します。

hx-get="apexdev/htmx/image/レッサーパンダ" hx-target="#image" hx-swap="innerHTML"


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

htmxには指定できる属性が他にも沢山あります。確かにJavaScriptを書かずに色々な処理を行なうことができるので、巷の話題にあがるのも納得できます。

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

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

完