2025年5月2日金曜日

チャートのタイトルを動的に変更する

Oracle APEXのチャートのタイトルを動的に変更する方法について調べてみました。設定を確認するために、以下のように動作するAPEXアプリケーションを作成しています。

表EMPをソースとしたバー・チャートを作成しています。選択リストのページ・アイテムで、バー・チャートの表示条件となるJOBを選択し、チャートを更新します。同時にチャートのタイトルを選択したJOBに変更しています。


このアプリケーションのエクスポートは以下に置いてあります。
https://github.com/ujnak/apexapps/blob/master/exports/update-chart-title.zip

チャートのタイトルの変更自体は簡単ですが、その実装方法はOracle APEXの公式なドキュメントに記載されていません。ただし、ChatGPTに聞くと大体教えてくれます。

ChatGPTに「Oracle APEXでJavaScriptでchart widgetを取得する手順を教えて」と聞いたところ、以下のコードを教えてくれました。
var chartWidget = apex.region("myChart").widget();
最後にChatGPTから「何を操作したいか（例：データ更新、再描画、ハイライトなど）も教えていただけますか？」と聞かれたので、「ChartのTitleを更新したい」と伝えたところ、以下のコードを教えてくれました。
var chart = apex.region("myChart").widget();
var currentOptions = chart.ojChart("option");

// タイトルを変更する
chart.ojChart("option", "title.text", "新しいタイトル");

// 必要に応じて再描画（通常は自動で反映されます）
Oracle JETのチャートのリファレンスは以下ですが、Oracle APEXのojChartインターフェース経由でどう使えるのかについては説明されていません。

カード・リージョン、ファセット・リージョン、対話グリッド、マップ・リージョンおよびテンプレート・コンポーネントといったJavaScriptの部分をOracle APEXの開発チームが実装しているコンポーネントについては、APIリファレンスにMethodsの説明があり、それを参照することによりJavaScriptで操作できます。

チャート・リージョンはOracle JETを使用しているため、Oracle APEXの開発チームにオーナーシップがありません。そのため、チャート・リージョンについてはページ・デザイナによる宣言的な設定がサポート範囲で、コードによる操作はサポートされません。そもそも、Oracle JETはOracle Corporationが保守しているオープンソース・プロジェクトであり、Oracle JET自体に一般的な製品サポートは提供されていません。

そういう意味ではコードで操作する場合、チャート・コンポーネントは他のオープンソースのフロントエンドのコンポーネントと同じ扱いになります。メンテナンス性を優先する場合は、使用は避けた方が良い、という点でも同じです。

以下より、今回作成したアプリケーションの実装を紹介します。

アプリケーションはすべてホーム・ページに実装しています。

チャートの表示条件となるページ・アイテムP1_JOBは選択リストとして作成しています。LOVのタイプにSQL問合せを選択し、SQL問合せとして以下を記述しています。LOVの表示値、戻り値ともに表EMPの列JOBに含まれる個別値となります。

select job d, job r from emp group by job

P1_JOBで選択された戻り値をチャートのタイトルとして設定します。

ページ・アイテムが変更されたときに、チャートをリフレッシュする動的アクションを作成します。


チャート・リージョンは識別の名前を給与として作成しています。

ソースの表名にEMPを指定し、WHERE句に:P1_JOB is null or JOB = :P1_JOBを記述しています。送信するページ・アイテムにP1_JOBを設定します。この設定により、リージョンのリフレッシュを実行した際に、P1_JOBが空であれば全従業員の給与がバーチャートに表示され、P1_JOBに値があれば、そのJOBを持つ従業員のみがバー・チャートに表示されます。

チャートをJavaScriptから操作するために、詳細の静的IDにmyChartを設定します。


チャートの属性のタイトルとして&P1_JOB.を設定します。これはチャート、つまりOracle JETのチャート・コンポーネントが表示するタイトルになります。


基本的な設定は以上になります。

これから、チャートのタイトルを描画する処理について考えていきます。

最初にページがロードされると、ページに含まれる置換文字列&P1_JOB.が、ページ・アイテムP1_JOBの値で置き換えられます。

ページ・アイテムP1_JOBのセッション・ステートのストレージはセッションごと(永続)としているため、ページ・ロード時にセッション・ステートに保存されている値が反映されます。これがリクエストごと(メモリーのみ)であれば、（デフォルトや計算が未設定であれば）つねにページ・アイテムの値は空白になります。

ページ・アイテムP1_JOBの選択を変更したときに、動的アクションでチャートをリフレッシュしています。リージョンの送信するページ・アイテムにP1_JOBが設定されていて、そしてセッション・ステートのストレージはセッションごと(永続)であるため、送信された値がセッション・ステートに保存されます。結果として、ページ・ロード時のP1_JOBの値は、直近のチャートのリフレッシュ時に送信されたP1_JOBの値になります。


置換文字列&P1_JOB.の置き換えはページ・ロード時にのみ行われます。チャートの属性のタイトルに設定した&P1_JOB.は、ページ・ロード後はページ・アイテムP1_JOBの値が変わっても、その値が反映されることはありません。


次にチャート・リージョンの属性の詳細の初期化JavaScriptファンクションが実行されます。初期化JavaScriptファンクションでは、属性に設定項目が存在しない設定もできます。

今回のアプリケーションでは以下のように記述しています。ページ・デザイナで設定した値が引数optionsとして渡され、必要な変更をoptionsに適用して戻します。
function( options ) {
    apex.debug.info(options);
    const job = apex.items.P1_JOB.value ? apex.items.P1_JOB.value : "すべてのJOB";
    // const job = apex.items.P1_JOB.value;
    if ( options.title ) {
        // titleが初期化済みであれば、textのみを更新する。
        options.title.text = job;
        apex.debug.info("INIT: title.text is replaced, ", job);
    }
    else
    {
        // そうでない場合は中央揃えも含めてtitleを初期化する
        options.title = {
            "halign": "center",
            "text": job
        };
        apex.debug.info("INIT: title.text is created, ", job);
    };
    return options;
}
optionsにどのような値が設定されているか、または、どのような値が設定可能かについては、ドキュメント化されていないため、JavaScriptコンソールにoptionsを印刷するか、または、チャート・ウィジェットからoptionを取り出して確認します。

apex.region("myChart").widget().ojChart("option")

例えば、JavaScriptコンソールなどから実行します。


初期化JavaScriptファンクションに渡されるoptionsは、ページ・デザイナで設定している内容に限定されます。リージョンの属性のタイトルに値がない場合は、title自体がnullになるため、options.title.textを設定することはできません。そのため初期化JavaScriptファンクションでは、options.titleに設定がない場合は、水平アラインメント(halign）の設定も含めてoptions.titleを設定しています。

初期化JavaScriptファンクションはページ・ロード時に実行されます。リージョンのリフレッシュ時には実行されません。そのため、ページ・アイテムP1_JOBの値が変更されたときは、動的アクションとして同等の処理を実行する必要があります。動的アクションには引数optionsが渡されないため、apex.region("myChart").widget().ojChart()を呼び出して設定を更新します。

チャート・リージョンに必ずタイトルが設定されている場合は、以下のコードでタイトルだけを変更できます。
const job = this.triggeringElement.value ? this.triggeringElement.value : "すべてのJOB";
// const job = this.triggeringElement.value;
apex.region("myChart").widget().ojChart(
    "option",
    "title.text",
    job
);
タイトルが未設定のときがあれば、以下のコードでタイトルを設定できます。
const job = this.triggeringElement.value ? this.triggeringElement.value : "すべてのJOB";
// const job = this.triggeringElement.value;
apex.region("myChart").widget().ojChart(
    "option",
    "title",
    {
        "halign": "center",
        "text": job
    }
);
同じ変更ですが、引数optionを除いて、以下のように呼び出せるようです。
const job = this.triggeringElement.value ? this.triggeringElement.value : "すべてのJOB";
// const job = this.triggeringElement.value;
apex.region("myChart").widget().ojChart(
    { 
        "title": {
            "halign": "center",
            "text": job
        }
    }
);
今回の記事は以上になります。

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

完
投稿者 時刻:
ラベル: , , ,