LottieのアニメーションをOracle APEXのアプリケーションに表示する

LottieのアニメーションをOracle APEXのアプリケーションに表示してみます。以下の４種類の実装をアプリケーションに組み込みます。

• JSONデータを扱うlottie-webを使う
• バイナリ形式のdotLottieも扱えるdotlottie-webを使う
• カスタム要素のlottie-playerを使う
• lottie-playerに加えてlottie-interactivityも使う

これらを実装したAPEXアプリケーションは以下のように動作します。

表示に使用しているLottieのアニメーションは、LottieFilesのStarter Planをサブスクライブして作成しました。

アニメーションのダウンロード形式としてdotLottieおよびLottie JSONを選んで、それぞれMyFirstLottie.lottie、MyFirstLottie.jsonという名前でファイルを作成しています。Optimized形式でダウンロードするためには、有料プランのサブスクライブが必要なようです。

以下より、作成したAPEXアプリケーションについて説明します。

空のAPEXアプリケーションから実装を始めます。アプリケーションの名前はPlay Lottieとしています。

共有コンポーネントの静的アプリケーション・ファイルに、Lottieのアニメーション・ファイルをアップロードします。dotLottieとJSON形式のファイルを、それぞれMyFirstLottie.lottie、MyFirstLottie.jsonとしてアップロードします。

今回はセッション・オーバーライドを使ってJavaScriptの開発を行います。すべての静的アプリケーション・ファイルにチェックを入れ（スクリーンショットには開発したJavaScriptのファイルも表示されています）、Zipとしてダウンロードをクリックします。

チェックした静的アプリケーション・ファイルを含むZIPファイルが、f<アプリケーションID>_static_application_files.zipというファイル名でダウンロードされます。

このファイルを適当なディレクトリに展開し、そのディレクトリを開発ツールで開きます。以下はVS Codeの使用を想定しています。今回の作業では、Lottieというディレクトリに静的アプリケーション・ファイルを展開しました。

セッション・オーバーライドを使った開発を行うために、VS CodeにはLive Serverの拡張を導入しておきます。

Lottie直下にLive Serverの起動に使用するファイルとしてindex.htmlを作成します。

このファイル自体はアプリケーションに組み込まないので、HTMLであれば内容は何でも構いません。

<html><body>Live Server Started.</body></html>

index.html上でコンテキスト・メニューを開きLive Serverを開始します。

ブラウザがhttp://localhost:5500/index.htmlとして、作成したindex.htmlを開きます。

APEXアプリケーションの開発者ツール・バーのセッションより、セッション・オーバーライドを開きます。

セッション・オーバーライドの有効化をオン、ファイルパスのアプリケーション・ファイルにhttp://localhost:5500/を設定します。

以上でJavaScriptの開発準備ができました。これ以降、実行中のAPEXアプリケーションはデータベースに保存されている静的アプリケーション・ファイルの代わりに、ローカルのファイル・システム上のファイルを参照します。

最初にlottie-webを実装します。ページ番号２として空白ページを作成します。画面上のコンポーネントは以下のように配置します。

ページ・プロパティのHTMLヘッダーにimportmapを設定します。

<script type="importmap">
{
    "imports": {
        "lottie-web": "https://esm.sh/lottie-web"
    }
}

JavaScriptのファイルURLとして以下を記述します。

[module, defer]#APP_FILES#js/app-lottie#MIN#.js

JavaScriptのコードをページに埋め込むことはせず、すべてファイルに記述します。ファイル名はapp-lottie#MIN#.jsとして置換文字列#MIN#を含めています。アプリケーションのデバッグ・モードが有効のときは#MIN#は空白となり、app-lottie.jsが参照されます。デバッグ・モードが無効の時は#MIN#は.minに置き換わりapp-lottie.min.jsとしてミニファイされたファイルが参照されます。ローカルにあるファイルapp-lottie.jsにコードを記述しているときに、内容を変更するたびにミニファイはしないと思うので、セッション・オーバーライドを使ってアプリケーションを開発しているときは、つねにデバッグ・モードにしておきます。そうしないと、app-lottie.jsの記述を変更したのに（app-lottie.min.jsが参照されているため）修正が反映されない、または、そもそもミニファイされたファイルapp-lottie.min.jsが存在しないため、JavaScriptのコードがロードされないこともあり得ます。

ボタンをまとめる静的コンテンツのリージョンを作成します。このリージョンにボタンをクリックしたときに呼び出すapex.actionを紐づけるため、静的IDとしてlottie-controlsを設定します。apex.actionはファイルapp-lottie.jsに記述します。

ボタンPLAY、PAUSE、STOPを作成します。動作のアクションは動的アクションで定義を選択します。動的アクションは作成せず、その代わりに詳細のカスタム属性としてdata-action=を設定します。data-action=には、それぞれのボタンに合わせて"PLAY"、"PAUSE"、"STOP"を与えます。ボタンをクリックすると、data-actionに与えた名前のapex.actionが実行されます。

lottie-webで発生したイベントの情報を表示するページ・アイテムとしてP2_EVENTを作成します。

Lottieのアニメーションを表示する要素を記述します。

静的コンテンツのリージョンを作成し、ソースのHTMLコードとして以下を記述します。

<div id="lottie-container" style="width: 600px; height: 600px;"><div>

余計な装飾を省くため、外観のテンプレートはBlank with Attributes (No Grid)を選択します。

ページ上のコンポーネントの配置と設定は以上で完了です。

VS Codeでフォルダjsを作成し、その下にファイルapp-lottie.jsを作成します。ファイルの内容は以下になります。

lottie-webを使った実装は以上で完了です。

続いてページ番号３にdotlottie-webを使った実装を行います。ページ上に配置するコンポーネントはlottie-webのときと同じです。

dotlottie-webを参照するため、ページ・プロパティのHTMLヘッダーにimportmapを記述します。

<script type="importmap">
    {
        "imports": {
            "@lottiefiles/dotlottie-web": "https://esm.sh/@lottiefiles/dotlottie-web"
        }
    }
</script>

JavaScriptのファイルURLに以下を記述します。dotlottie-webを使った実装はファイルapp-dotlottie.jsに記述します。

[module,defer]#APP_FILES#js/app-dotlottie#MIN#.js

dotlottie-webでは、アニメーションを表示する要素はキャンバスになります。静的コンテンツのソースのHTMLコードの記述を以下に変えます。

<canvas id="lottie-canvas" style="width: 600px; height: 600px;"></canvas>

dotlottie-webを使ってLottieのアニメーションを描画するコードは以下になります。ファイルjs/app-dotlottie.jsとして作成します。

dotlottie-webを使った実装は以上で完了です。

ページ番号４にカスタム要素lottie-playerを使った実装を行います。とても簡単です。

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

https://unpkg.com/@lottiefiles/lottie-player@latest/dist/lottie-player.js

静的コンテンツのソースのHTMLコードに以下を記述します。アプリケーション・アイテムとしてAPEX_PATHを作成し、APEX_UTIL.HOST_URL('APEX_PATH')の結果が設定されるようにアプリケーションの計算を設定しておきます。この手順については、こちらの記事に含まれています。

セッション・オーバーライドが有効のときは&APEX_PATH.#APP_FILES#が無効なURLに置き換わります。そのため、セッション・オーバーライドをオフにして動作確認をします。

<lottie-player
    id="firstLottie"
    src="&APEX_PATH.#APP_FILES#MyFirstLottie.json"
    style="width: 600px; height: 600px;"
    loop
    autoplay
    controls
></lottie-player>

以上でカスタム要素lottie-playerを使った実装は完了です。

最後にページ番号５にlottie-interactivityを使った実装を行います。

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

https://unpkg.com/@lottiefiles/lottie-player@latest/dist/lottie-player.js

https://unpkg.com/@lottiefiles/lottie-interactivity@latest/dist/lottie-interactivity.min.js

静的コンテンツのソースのHTMLコードに、４つのlottie-playerを配置するコードを記述します。画面の上下スクロールに合わせて、それぞれのアニメーションの動作を変更します。

ページ・プロパティのJavaScriptのページ・ロード時に実行に、以下を記述します。画面のスクロールに合わせて変更する動作を、それぞれのlottie-playerに対して設定しています。

以上でlottie-interactivityを使った実装も完了です。

ローカルのファイル・システムにあるapp-lottie.jsおよびapp-dotlottie.jsは、共有コンポーネントの静的アプリケーション・ファイルとしてアップロードします。アップロードしたJavaScriiptファイルをスクリプト・エディタで開いて保存すると、自動的にミニファイされたファイルが作成されます。

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

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

https://github.com/ujnak/apexapps/blob/master/exports/play-lottie.zip

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

完

宣言的な動的アクションとJavaScriptによるコーディングの比較

 以前に書いた記事data-parent-elementを実装したサンプルを使って、宣言的な動的アクションとJavaScriptによるコーディングを比べてみます。

サンプル・アプリケーションでは、以下の２つの動的アクションを作成しています。

動的アクションonClick SELECT_JOBのTRUEアクションは以下です。

ボタンSELECT_JOBをクリックしたときに、ページ・アイテムP1_JOBの値をP1_JOB_SELECTに設定する。その後、インライン・ポップアップのリージョンを開く。

動的アクションonChange P1_JOB_SELECTのTRUEアクションは以下です。

ページ・アイテムP1_JOB_SELECTの値を変更したときに、ページ・アイテムP1_JOB_SELECTの値をP1JOBに設定する。その後、インライン・ポップアップのリージョンを閉じる。

上記の処理は、JavaScriptのコードで置き換えることができます。

最初にリージョン役職の選択に、静的IDとしてPOPUP_SELECT_JOBを設定します。

インライン・ポップアップを開く処理をJavaScriptで記述します。

TRUEアクションの識別の名前はインライン・ポップアップを開くとします。アクションとしてJavaScriptコードの実行を選択します。設定のコードとして以下を記述します。

apex.items.P1_JOB_SELECT.setValue(
    apex.items.P1_JOB.getValue()
);
apex.theme.openRegion("POPUP_SELECT_JOB");

宣言的に作成した２つのTRUEアクションと同じ動きになります。

インライン・ポップアップを閉じるJavaScriptのコードは以下になります。

apex.items.P1_JOB.setValue(
    apex.items.P1_JOB_SELECT.getValue()
);
apex.theme.closeRegion("POPUP_SELECT_JOB");

さらに、apex.actionsとして呼び出すように変更してみます。

静的アプリケーション・ファイルとしてpage-actions.jsを作成します。

参照をコピーします。

ページ・プロパティのJavaScriptのファイルURLに、作成した静的アプリケーション・ファイルの参照を記述します。

JavaScriptのコードを記述したファイルは、静的アプリケーション・ファイルとしてAPEXのアプリケーションに含めていますが、作成したファイルpage-actions.jsとMinifyされたファイルpage-actions.min.jsはブラウザからアクセスできれば、別の場所に配置することも可能です。

インライン・ポップアップを開く処理は、以下のカスタム属性の設定に置き換えられます。

data-action="#action$open-inline-popup?source=P1_JOB&target=P1_JOB_SELECT&region=POPUP_SELECT_JOB"

インライン・ポップアップを閉じる処理はJavaScriptのコードを以下に書き換えて、apex.actionsとして実装した処理を呼び出すようにします。

apex.actions.invokeを使用します。

apex.actions.invoke("close-inline-popup", this.browserEvent, this.triggeringElement, {
    source: "P1_JOB_SELECT",
    target: "P1_JOB",
    region: "POPUP_SELECT_JOB"
} );

開発するアプリケーションの規模が大きくなると、宣言的な設定ではアプリケーションの見通しが悪くなります。

サーバー・サイドではプロセス・タイプにコードの実行を選んでPL/SQLコードを記述する代わりに、APIの呼出しを選んでPL/SQLのパッケージ、プロシージャ、ファンクションを指定できるようになりました。

クライアント・サイドではactionとして定義されたコードを呼び出せるようして、JavaScriptのコードをひとつのファイルにまとめることができるようになっています。

アプリケーション開発の容易さとメンテナンスの容易さのトレードオフの結果として、コーディングによる実装を行なうという選択肢もあり得るでしょう。

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

https://github.com/ujnak/apexapps/blob/master/exports/data-parent-element-sample-actions.zip

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

完

カード上のボタンをクリックしてJavaScriptを実行する

  カード・リージョンでは、個々のカードにたいしてアクションを作成できます。作成できるアクションのタイプは以下の３つで、動的アクションはありません。

1. このアプリケーションのページにリダイレクト
2. 別のアプリケーションのページにリダイレクト
3. URLにリダイレクト

APEX 22.2よりインターフェースactionsが追加され、ボタンやリンクのクリックからapex.actionsに登録したJavaScriptのコードが実行できるようになりました。

以下より、actionsインターフェースを使って、カード上のボタンをクリックしてJavaScriptを呼び出す実装を行なってみます。

サンプル・データセットのEMP/DEPTをデータ・ソースとして使い、以下の動作を行うAPEXアプリケーションを作成します。

従業員名に隣にある鉛筆アイコンをクリックするか、またはボタンの従業員番号の設定をクリックすると、従業員番号のテキスト・フィールドに従業員番号を設定します。

アプリケーション作成ウィザードを起動します。アプリケーションの名前はカードアクションとしました。

デフォルトで作成されているホーム・ページを（編集をクリックして）削除し、ページの追加をクリックしてカードのページを追加します。

追加するカードのページ名もカードアクションとします。表またはビューとしてEMPを選択し、レイアウトはグリッドを選択します。タイトル列はENAME、本体列はJOBを指定し、ページの追加をクリックします。

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

アプリケーションが作成されます。これから、カードアクションのページにアクションを実装していきます。

ページ・デザイナにてページ番号１のカードアクションを開きます。

従業員番号を設定するページ・アイテムを、Breadcrumb Barのカードアクションのリージョンに作成します。

識別の名前はP1_EMPNOです。タイプとしてテキスト・フィールドを選択します。ラベルは従業員番号とします。

ページ・プロパティのJavaScriptのファンクションおよびグローバル変数の宣言に、ボタンのクリックで呼び出されるAPEXアクションを記述します。引数empnoに渡された従業員番号をページ・アイテムP1_EMPNOに設定します。

ページ・ロード時に実行に以下の一行を記述します。

apex.actions.add(PAGE_ACTIONS_EMPCARD);

カードのアクションとしてボタン従業員番号の設定を作成します。

識別のタイプはボタン、ラベルは従業員番号の設定とします。リンクのタイプにURLにリダイレクトを選択し、ターゲットとして以下を記述します。

#action$setempno?empno=&EMPNO.

このターゲットの指定により、APEXアクションとして登録されているsetempnoが呼び出され、従業員番号がページ・アイテムP1_EMPNOに設定されます。

従業員名の横に表示されている鉛筆アイコンのボタンは、ボタン・ビルダーを使ってHTMLを生成します。

Button Builder - Universal Theme (oracle.com)

https://apex.oracle.com/pls/apex/apex_pm/r/ut/button-builder

今回の設定は以下です。Button TemplateはIcon、Button LabelはEdit (表示はされません)、Icon Classとしてfa-pencil、StyleをRemove UI Decorationsを選んでいます。

上記の設定で生成されたEntire Markupを使用します。

生成されたマークアップをカードに設定します。

カード・リージョンの属性を開き、タイトルを拡張フォーマットに切り替えます。

HTML式として記述するマークアップには、以下のdata-actionカスタム属性を追加します。

data-action="setempno?empno=&EMPNO."

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

a要素ではhref属性として"#action$アクション名"で呼び出すアクションを指定します。button要素ではカスタム属性data-action="アクション名"で呼び出すアクションを指定します。

アプリケーションを実行すると、記事の先頭のGIF動画の動作をします。

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

https://github.com/ujnak/apexapps/blob/master/exports/card-button-action.zip

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

完