APEX 24.2のテンプレート・コンポーネントのグループ化のサポートとアバターの複数対応について

Oracle APEX 24.2のテンプレート・コンポーネントの以下の新機能を確認します。

• グループ化のサポート
• Content Rowのグループ・ヘッダー
• Avatorの複数(レポート)対応

これらの機能を確認するために、サンプル・データセットの国のデータを使用します。

APEX 24.2で新設されたレポート・グループが定義されているテンプレート・コンポーネントであれば、グループ化できます。標準のテンプレート・コンポーネントではContent Rowだけがグループ化をサポートしているようです。

以下よりテンプレート・コンポーネントの新機能を確認します。

空のAPEXアプリケーションを作成し、ホーム・ページにタイプがContent Rowのリージョンを作成します。

ソースのSQL問合せに以下を設定します。

select
    c.country_id
    ,c.name country_name
    ,'fa-flag-' || lower(c.iso_alpha2) icon
    ,c.capital
    ,c.population
    ,r.name region_name
from eba_countries c join eba_country_regions r 
    on c.region_id = r.id

グループ化を適用するには、グループ化する列を選択し、外観のグループをオンにします。SELECT文のGROUP BY句に与える列にあたります。

今回の例では列REGION_NAMEでグループ化します。

グループ化を設定した場合、主キー列の設定が必須になります。今回の例では列COUNTRY_IDのソースの主キーをオンにします。

Content Rowのリージョンの属性を設定します。グループ化するため、外観の表示は複数(レポート)になります。設定のTitleは&COUNTRY_NAME.、Descriptionに以下を記述します。

Capital: &CAPITAL. Population: &POPULATION.

Display Avatarをオンにし、AvatarのTypeにIcon、Iconに&ICON.、ShapeにNo Shape、SizeにLargeを設定します。これらの設定は、それぞれの行に適用されます。

グループ化の設定は、Groupingのセクションで行います。この部分がAPEX 24.2の新機能のContent Row Group Headers(Content Rowのグループ・ヘッダー)の設定です。

Titleに&REGION_NAME.、Iconにfa-map-oを設定します。

一般にグループ化する場合、並替え基準(SELECT文のORDER BY句)も設定します。今回は並替え基準のタイプに静的値を選択し、ORDER BY句にREGION_NAME,COUNTRY_NAMEを設定しています。最初に現れる列はグループをオンにした列である必要があります。

以上の設定を行うと、Content Rowのリージョンは以下のように表示されます。

Avatarについても、同じSQL問合せを設定して確認します。

Avatarの属性を開きます。属性の表示に複数(レポート)を選択します。APEX 24.2以前は、単一(部分)のみでした。

設定のSpacingがAutoのときは、配置されているAvatar（今回は国旗のアイコン）が、リージョンの横幅に合わせて均等に配置されます。

SpacingがStackのときは、Avatarが重なります。

Avatarのようにグループ化をサポートしていないテンプレート・コンポーネントに対してグループを設定すると、以下のようにグループ・テンプレートがない、というエラーが発生します。

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

簡単なアプリケーションですが、説明に使用したアプリケーションのエクスポートを以下に置きました。

https://github.com/ujnak/apexapps/blob/master/exports/sample-content-row-grouping.zip

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

完

D3をOracle APEXのアプリケーションに組み込む

今までにObservable Plot、Plotly.js、billboard.jsといったD3をチャート描画に使用しているライブラリを、Oracle APEXのアプリケーションに組み込んでみました。これらのライブラリを使うとチャートを簡単に表示できますが、やはりD3でなければ表示できないチャートはあります。

今回の記事では、Oracle APEXのアプリケーションでD3を使ってチャートを描画してみます。テンプレート・コンポーネントの作成はせず（D3によるチャート描画のユースケースで、テンプレート・コンポーネントが必要なケースは無いと思います）、D3のExamplesにあるチャートをいくつか、Oracle APEXのページに実装してみます。

最初にチャート描画に使うJSONデータを保存する表を作成し、その表を元に初期のAPEXアプリケーションを作成します。

SQLワークショップのクイックSQLの以下のモデルより、表EBAJ_D3_GRAPHSを作成します。データの名前となる列NAMEと、JSON形式のデータを保持する列GRAPH_DATAを含みます。

# prefix: ebaj
d3_graphs
    name vc80 /nn
    graph_data json

レビューおよび実行をクリックします。

表EBAJ_D3_GRAPHSを作成するDDLを確認します。列GRAPH_DATAのデータ型はCLOBになっています。効率の面からいうと、JSONやBLOB型が望ましいのですが、APEXのアプリケーション作成ウィザードはデータ型がCLOBのときはタイプがテキスト領域のページ・アイテムを作成し、BLOBのときはファイル選択のページ・アイテムを作成します。今回の用途ではテキスト領域を作成して欲しいので、CLOBのまま変更しません。

スクリプト名を設定し、実行をクリックします。確認画面が表示されるので、即時実行をクリックします。

表が作成されます。続けてアプリケーションの作成をクリックします。確認画面が表示されるので、再度アプリケーションの作成をクリックします。

アプリケーション作成ウィザードが開きます。名前をIntegrating D3に変更します。デフォルトで表EBAJ_D3_GRAPHSをソースとしたフォーム付き対話モード・レポートのページが作成されます。

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

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

D3のExamplesに含まれるHierarchical edge bundling IIのチャートを、Oracle APEXのページに実装します。

画面右上にある３点アイコンよりメニューを開き、ViewのShow filesを実行します。

Filesのパネルが開き、データファイルであるflare.jsonが含まれていることが確認できます。３点アイコンのボタンをクリックし、Downloadを実行します。

ファイルをダウンロードしたら、作成したAPEXアプリケーションを実行し対話モード・レポートのページを開きます。

作成をクリックします。

Nameにファイル名であるflare.json、Graph Dataにダウンロードしたflare.jsonの内容をコピペします。

作成をクリックします。

対話モード・レポートのページに戻ると、ORA-6502が発生しています。これは、登録したJSONデータが長すぎて対話モード・レポートの１行に表示できる文字数の制限（32k）を超えたために発生しています。

今回はエラーを回避できれば良いので、アクションの列を開き、Graph Dataを表示対象の列から外します。

flare.jsonが登録されていることが確認できます。

チャートのデータを保存できたので、これからチャートを実装します。

空白のページを作成します。名前はHierarchical edge bundling IIとします。

HTMLヘッダーに以下のimportmapを記述します。

<script type="importmap">
    {
        "imports": {
            "d3": "https://cdn.jsdelivr.net/npm/d3/+esm"
        }
    }
</script>

データベースからJSONデータを取り出す際に呼び出すAjaxコールバックを作成します。

識別の名前はGET_DATA、タイプはコードの実行です。ソースのPL/SQLコードとして以下を記述します。

D3のチャートを描画するリージョンを作成します。

識別の名前はD3、タイプに静的コンテンツとします。ソースのHTMLコードに以下を記述します。ほとんどD3のExamplesそのままですが、書式を素のJavaScriptで動作するように若干の修正を加えています。

以上で実装は完了です。ページを実行すると、以下のようにチャートが表示されます。

作成したページをコピーし、Force-directed graphを実装してみます。

ダウンロードしてデータベースに取り込むファイルはmiserable.jsonです。

静的コンテンツのリージョンのHTMLコードとして、以下を記述します。invalidationの呼び出しをコメントアウトしたくらいで、ほとんどコードは改変していません。

ページを実行すると以下のように表示されます。

同様にページをコピーしWorld tourを実装してみます。

ダウンロードしてデータベースの取り込むファイルはcountries-110m.jsonです。

World tourでtopojsonのクライアント・ライブラリを使用しています。そのため、importmapを以下に変更します。

<script type="importmap">
    {
        "imports": {
            "d3": "https://cdn.jsdelivr.net/npm/d3/+esm",
            "topojson-client": "https://cdn.jsdelivr.net/npm/topojson-client/+esm"
        }
    }
</script>

フォーカスが当たっている国の名前を表示するページ・アイテムとして、P6_NAMEを作成しています。

静的コンテンツのリージョンのHTMLコードとして、以下を記述します。countries-110m.jsonをデータベースから読み込むコードや、canvasのコードをdiv要素（myChart）の子要素となるように、コードを追加しています。

ページを実行すると以下のように表示されます。

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

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

https://github.com/ujnak/apexapps/blob/master/exports/integrating-d3.zip

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

完

billboard.jsをOracle APEXのアプリケーションに組み込む

billboard.jsをOracle APEXのアプリケーションに組み込んでみます。

Oracle JETやその他のチャート描画ライブラリの組み込み作業で表示したチャートと、同じチャートを表示してみます。

直接billboard.jsで描画

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

https://cdn.jsdelivr.net/npm/d3/dist/d3.min.js

https://cdn.jsdelivr.net/npm/billboard.js/dist/billboard.min.js

CSSのファイルURLに以下を記述します。

https://cdn.jsdelivr.net/npm/billboard.js/dist/billboard.min.css

静的コンテンツのリージョンの名前をbillboard.jsとし、ソースのHTMLコードに以下を記述します。

<div id="myChart"></div>

チャートに描画するデータを保持するページ・アイテムとしてP1_VALUEを作成します。タイプは非表示です。

ページ・アイテムP1_VALUEに計算を作成し、ページの描画前にデータを設定します。計算のタイプとしてSQL問合せ(単一の値を返す)を選択し、SQL問合せに以下を記述します。

select
    json_arrayagg(
        json_object(
            'ename' value ename,
            'sal'     value sal
        )
    order by empno asc )
from emp where deptno = 10

チャートを描画するJavaScriptのコードを、ページ・プロパティのページ・ロード時に実行に記述します。

以上で実装は完了です。ページを実行すると以下のように表示されます。

テンプレート・コンポーネントの作成

billboard.jsのバー・チャートを描画するテンプレート・コンポーネントについて、設定内容を説明します。

テンプレート・コンポーネントの名前はbillboard.js Bar Chartとしました。テンプレートの部分には以下を記述しています。

カスタム属性としてCSS Classes、Groups, Value、Color、Width、Heightを作成しています。Groupsのタイプはテキストで、Y軸となる属性とX軸となる属性を,(カンマ)で区切って指定します。今回の実装ではename,salを指定します。Valueのタイプはセッション・ステート値、Colorはカラー、Orientationは選択リストとします。WidthとHeightは両方とも整数です。

カスタム属性Orientationの静的LOVとして、horizontalの戻り値にtrue、verticalの戻り値にfalseを設定します。これはaxis属性のrotatedの値になります。

ディレクトリをjs、ファイル名をscript.jsとして、カスタム要素a-billboard-js-bar-chartの実装を記述します。

ロードするファイルURLのカスケード・スタイルシートに以下を記述します。

https://cdn.jsdelivr.net/npm/billboard.js/dist/billboard.min.css

JavaScriptに以下を記述します。

https://cdn.jsdelivr.net/npm/d3/dist/d3.min.js

https://cdn.jsdelivr.net/npm/billboard.js/dist/billboard.min.js

#PLUGIN_FILES#js/script#MIN#.js

以上でテンプレート・コンポーネントは完成です。

リージョンにbillboard.jsのテンプレート・コンポーネントを実装します。

ページ・アイテムP2_VALUEは、最初に作成したP1_VALUEと同じ設定で作成します。

識別の名前をbillboard.js、タイプをbillboard.js Bar Chartとします。

リージョンの属性を開き、Groupsとしてename,sal、ValueとしてP2_VALUE、Colorとして#309fdbを設定します。Orientationはhorizontalです。

以上で実装は完了です。ページを実行すると以下のように表示されます。

対話モード・レポートへの組み込み

対話モード・レポートのソースのSQL問合せとして以下を記述します。

select
    dname,
    json_arrayagg(
        json_object(
            'ename' value ename,
            'sal'     value sal
        )
    order by empno asc ) value,
    '' chart
from emp_dept_v group by dname

対話モード・レポートの列CHARTを選択し、識別のタイプをbillboard.js Bar Chartに変更します。

設定のGroupsにename,sal、ValueにVALUE、Colorに#309fdb、Orientationにhorizontalを設定します。Widthは400、Heightに200を設定します。

以上で実装は完了です。ページを実行すると以下のように表示されます。

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

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

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

完

Plotly.jsをOracle APEXのアプリケーションに組み込む

Plotly.jsをOracle APEXのアプリケーションに組み込んでみます。

Oracle JETやその他のチャート描画ライブラリの組み込み作業で表示したチャートと、同じチャートを表示してみます。

直接Plotly.jsで描画

Plotly.jsのGetting started in JavaScriptのページを参照して、実装を進めます。バー・チャートの表示はこちらのページにある例を元にしています。バー・チャートのリファレンスはこちらです。

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

https://cdn.plot.ly/plotly-2.34.0.min.js

静的コンテンツのリージョンの名前をPlotly.jsとし、ソースのHTMLコードに以下を記述します。

<div id="myChart" class="w600 h400"></div>

チャートに描画するデータを保持するページ・アイテムとしてP1_GROUPS、P1_VALUEを作成します。タイプは非表示です。

ページ・アイテムP1_GROUPSに計算を作成し、ページの描画前にデータを設定します。計算のタイプとしてSQL問合せ(単一の値を返す)を選択し、SQL問合せに以下を記述します。

select
    json_arrayagg(
        ename
    order by empno asc )
from emp where deptno = 10

ページ・アイテムP1_VALUEにも計算を作成し、ページ描画前に値を設定します。SQL問合せに以下を記述します。

select
    json_arrayagg(
        sal
    order by empno asc )
from emp where deptno = 10

チャートを描画するJavaScriptのコードを、ページ・プロパティのページ・ロード時に実行に記述します。

以上で実装は完了です。ページを実行すると以下のように表示されます。

テンプレート・コンポーネントの作成

Plotly.jsのバー・チャートを描画するテンプレート・コンポーネントについて、設定内容を説明します。

テンプレート・コンポーネントの名前はPlotly.js Bar Chartとしました。テンプレートの部分には以下を記述しています。

カスタム属性としてCSS Classes、Groups、Value、Color、Orientation、Width、Heightを作成しています。GroupsとValueのタイプはセッション・ステート値、Colorはテキスト、WidthとHeightは両方とも整数です。

チャートの向きの指定であるOrientationの静的LOVは、horizontalの戻り値としてh、verticalの戻り値としてvを設定します。

ディレクトリをjs、ファイル名をscript.jsとして、カスタム要素a-plotly-js-bar-chartの実装を記述します。

ロードするファイルURLのJavaScriptに以下を記述します。

https://cdn.plot.ly/plotly-2.34.0.min.js

#PLUGIN_FILES#js/script#MIN#.js

以上でテンプレート・コンポーネントは完成です。

リージョンにPlotly.jsのテンプレート・コンポーネントを実装します。

ページ・アイテムP2_GROUPSとP2_VALUEは、最初に作成したP1_GROUPSとP1_VALUEと同じ設定で作成します。

識別の名前をPlotly.js、タイプをPlotly.js Bar Chartとします。

リージョンの属性を開き、GroupsとしてP2_GROUPS、ValueとしてP2_VALUE、Colorとして#309fdb、Orientationとしてhorizontalを設定します。

以上で実装は完了です。ページを実行すると以下のように表示されます。

対話モード・レポートへの組み込み

対話モード・レポートのソースのSQL問合せとして以下を記述します。

select
    dname,
    json_arrayagg(
        ename
    order by empno asc ) groups,
    json_arrayagg(
        sal
    order by empno asc ) value,
    '' chart
from emp_dept_v group by dname

対話モード・レポートの列CHARTを選択し、識別のタイプをPlotly.js Bar Chartに変更します。

設定のCSS Classesにw130、GroupsにGROUPS、ValueにVALUE、Colorに#309fdb、Orientationにhorizontalを設定します。Widthは400、Heightに300を設定します。

以上で実装は完了です。ページを実行すると以下のように表示されます。

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

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

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

完