2024年2月15日木曜日

リージョンにヘルプを表示するボタンを設置する

Oracle APEXでは、ページ・アイテムや対話グリッドや対話モード・レポートの列にヘルプ文書を埋め込むことができます。これらのヘルプ文書の埋め込みについては、以前に記事「APEXアプリケーションへのヘルプ文書の埋め込み」にて、その使い方を紹介しています。

以下より、リージョンに配置したヘルプ（？アイコン）をクリックして、ヘルプをポップアップする機能を実装してみます。Oracle APEXの標準機能としては、リージョンにヘルプを設定する方法はありません。

実装したヘルプは以下のように動作します。


ヘルプに使用するアイコンは、Oracle APEXにバンドルされているフォントFontAPEXから探します。


helpで検索して見つけたfa-question-circle-oをアイコンとして使用することにします。


Size、Scale、Animation、Rotate、Modifierの選択により、アイコンを修飾できます。今回はアイコンの修飾は行いません。

ページにHTMLまたはIconの記述を埋め込むことにより、?アイコンを表示します。


最初に、外観のテンプレートとしてStandardを選択しているリージョンにヘルプを実装します。


ヘルプの表示を、ボタンのクリックで行うように実装します。

レイアウトの位置にEditを選択することにより、ボタンを右上に配置します。外観のボタン・テンプレートとしてIconを選択し、ボタンの表示をアイコンだけにします。テンプレート・オプションのStyleにRemove UI Decorationを選択しボタンとしての修飾を無くし、アイコンだけが表示されるようにします。アイコンはFontAPEXで見つけたアイコンfa-question-circle-oを設定します。

動作のアクションは動的アクションとします。


ボタンをクリックしたときに実行される動的アクションのTRUEアクションとして、JavaScriptコードの実行を選択します。設定のコードには以下を記述します。apex.theme.popupFieldHelpを呼び出すことにより、Oracle APEXが標準で提供しているヘルプと同じ動作でヘルプを表示できます。
const title1 = apex.lang.getMessage("CUSTOM_HELP_R1_TITLE");
const help1 = apex.lang.getMessage("CUSTOM_HELP_R1_HELP");
apex.theme.popupFieldHelp( {title: title1, helpText: help1} );

実際にヘルプとして表示するタイトルやヘルプ本文をアプリケーションに埋め込むことを避けるために、apex.lang.getMessageを呼び出しています。apex.lang.getMessageで取り出す文字列は、共有コンポーネントのテキスト・メッセージ（本来はアプリケーションの翻訳に使用します）に作成します。


テキスト・メッセージを開くと、作成済みのテキスト・メッセージが一覧されます。


作成するテキスト・メッセージの名前にapex.lang.getMessageの引数となる値を設定し、テキストとして取り出す文字列を記述します。言語としてAPEXアプリケーションのプライマリ言語（通常は日本語(ja)）を選択します。アプリケーションの言語に一致しているテキスト・メッセージが選択されます。apex.lang.getMessageより文字列を取り出す場合は、JavaScriptで使用はオンにします。

ヘルプのテキストはHTMLによる修飾が有効なので、ここで設定するテキストにHTMLを記述することができます。


以上で外観のテンプレートがStandardのリージョンに、ヘルプを組み込むことができました。

次に外観のテンプレートがBlank with Attributesのリージョンに、ヘルプを組み込みます。


先ほどの？アイコンはボタンで実装しています。ボタンによる実装の場合、ボタンをクリックした際などに、ボタンの境界が表示されることがあります。


動作に影響しないため気にしなくても良いですが、ボタンの代わりにリージョンを使って実装してみます。

静的コンテンツのリージョンを作成し、ソースのHTMLコードとしてFontAPEXで見つけたアイコンのHTMLを記述します。

<span aria-hidden="true" class="fa fa-question-circle-o"></span>

外観のテンプレートとして、ほとんど修飾のないBlank with Attributes (No Grid)を選択します。親リージョンのテンプレートはBlank with Attributesであるため、レイアウトの位置にEditはありません。そのため、CSSクラスにUniversal Themeが提供しているLayout Modifiersに含まれるu-pullRight u-alignTopを指定します。

　

リージョンであってもクリックのイベントを取ることができます。このアイコンを表示しているリージョンに、タイミングのイベントがクリックの動的アクションを作成します。


TRUEアクションは、先ほどの実装とほぼ同じです。


以上で、リージョンにヘルプを表示するボタンを配置することができました。

簡単なアプリケーションですが、今回作成したアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/sample-region-help.zip

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

完
投稿者 時刻:
ラベル: