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

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

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

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

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

https://apex.oracle.com/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を指定します。

https://apex.oracle.com/pls/apex/r/apex_pm/ut/layout-modifiers

　

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

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

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

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

https://github.com/ujnak/apexapps/blob/master/exports/sample-region-help.zip

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

完

APEX 23.1の新機能コンテキスト依存ヘルプの日本語対応

 Oracle APEX 23.1の新機能に、コンテキスト依存ヘルプというものがあります。

Oracle APEXのオンライン・ヘルプにドキュメントの表示というボタンが含まれている場合ががあります。このボタンをクリックすると、今までは製品ドキュメントのトップ・ページが開いたのですが、23.1からは関連するページが開かれるようになっています。

便利になりましたが、いかんせん英語のドキュメントが開きます。

仕組みを調べて、日本語のドキュメントが開くようにしてみました。

製品ドキュメントの位置は、管理サービスにサインインした後、インスタンスの設定より実施します。

インスタンスの設定のヘルプのセクションに、ヘルプのURLの指定が含まれます。

今までは、ボタンドキュメントの表示をクリックしたときに、このヘルプのURLとして設定されているURLを開いていました。23.1からは、製品ドキュメントを開く際に?context=コンテキストという引数が与えられています。

例えば、本記事の最初の画像にある製品ドキュメントは、以下のURLより呼び出されています。

https://apex.oracle.com/doc231?context=4000:510

このコンテキストの値と呼び出されるURLの対応は、以下のファイルに記述されています。

https://docs.oracle.com/en/database/oracle/apex/23.1/context-sensitive-help.js

コンテキストとURLの対応は英語のドキュメントが元になっています。とはいえ、URLやアンカーは日本語のドキュメントでも維持されているはずなので、この対応をそのまま使います。

一番最初に、コンテキストとURLの対応を保存する表CSH_CONTEXT_SENSITIVE_HELPを作成します。

create table csh_context_sensitive_help
(
    context varchar2(40) not null,
    url     varchar2(400) not null
);

context-sensive-help.jsを読み込んで、コンテキストとURLの対応を作成した表CSH_CONTEXT_SENSITIVE_HELPに書き込みます。JavaScriptのファイルの位置はAPEXのバージョンに依存して変更されます。また、内容に関してもAPEXがバージョン・アップされると変更される可能性はあります。

SQLワークショップのSQLコマンドより実行します。

コンテキスト依存ヘルプのリクエストを受け付けて、適切な製品ドキュメントのURLを返すRESTサービスを作成します。

SQLワークショップのRESTfulサービスを開き、モジュールの作成を実行します。

モジュール名はContext Sensitive Help、ベース・パスは/help/とし、モジュールの作成をクリックします。

モジュールContext Sensitive Helpが作成されます。完全なURLにモジュール名が含まれているようですが、表示上の問題なので無視できます。

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

URIテンプレートとしてpageを指定します。

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

テンプレートpageが作成されます。

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

作成するハンドラのメソッドとしてGETを選択します。ソース・タイプはPL/SQLです。ソースとして、以下を記述します。Oracle APEX 23.1の製品ドキュメントはまだ日本語訳が無いため、代わりにOracle APEX 22.2の日本語ドキュメントのURLをC_BASE_URLに設定しています。

パラメータとしてcontextを受け付け、表CSH_CONTEXT_SENSITIVE_HELPよりリダイレクト先を見つけて、クライアントにリダイレクトを要求しています。

リダイレクト先をHTTPの応答ヘッダーのLocationとして返すため、パラメータを追加します。

行の追加をクリックし、パラメータをひとつ追加します。

追加したパラメータの名前はLocation、バインド変数はlocation、アクセス・メソッドはOUT、ソース・タイプとしてHTTP HEADER、データ型としてSTRINGを指定します。

以上でハンドラの作成を実行します。

作成されたハンドラの完全なURLをコピーします。

このURLをAPEXのインスタンスの設定のヘルプのURLとして設定します。

管理サービスにサインインし、ヘルプのURLを変更します。

以上の変更で、コンテキスト依存ヘルプとして日本語の製品ドキュメントが開くようになります。

本記事は以上になります。

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

完