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

2023年6月2日金曜日

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がバージョン・アップされると変更される可能性はあります。

 declare
     /*
      コンテキスト依存ヘルプを保存する表の定義
      create table csh_context_sensitive_help
      (
         context varchar2(40) not null,
         url     varchar2(400) not null
      );
     */
     C_CONTEXT_SENSITIVE_HELP_JS constant varchar2(80) := 'https://docs.oracle.com/en/database/oracle/apex/23.1/context-sensitive-help.js';
     l_cshelp_js clob;
     l_page_obj  clob;
     l_start pls_integer;
     l_end   pls_integer;
     l_indexes json_object_t;
     l_keys    json_key_list;
     l_arr     json_array_t;
     l_size    pls_integer;
     l_context csh_context_sensitive_help.context%type;
     l_url     csh_context_sensitive_help.url%type;
 begin
     l_cshelp_js := apex_web_service.make_rest_request(
         p_url => C_CONTEXT_SENSITIVE_HELP_JS
         ,p_http_method => 'GET'
     );
     /* find start and end position of pageDocMappger object within JS code */
     l_start := instr(l_cshelp_js, '{');
     l_end   := instr(l_cshelp_js, '}');
     l_page_obj := substr(l_cshelp_js, l_start, (l_end - l_start + 1));
     l_indexes := json_object_t.parse(l_page_obj);
     l_keys := l_indexes.get_keys;
     for i in 1..l_keys.count
     loop
         l_arr := l_indexes.get_array(l_keys(i));
         l_size := l_arr.get_size;
         for j in 1..l_size
         loop
             l_context := l_arr.get_string(j-1);
             l_url     := l_keys(i);
             dbms_output.put_line(l_context || ' = ' || l_url);
             insert into csh_context_sensitive_help values(l_context, l_url);
         end loop;
     end loop;
     commit;
 end;

view raw load-context-sensitive-help.sql hosted with ❤ by GitHub

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よりリダイレクト先を見つけて、クライアントにリダイレクトを要求しています。

 declare
     C_BASE_URL constant varchar2(40) := 'https://docs.oracle.com/cd/F79039_01/';
     l_context apex_t_number;
     l_url     csh_context_sensitive_help.url%type;
 begin
     /* 例外が発生したらマニュアルのトップ・ページを開く。 */
     l_url := C_BASE_URL;
     begin
         select url into l_url from csh_context_sensitive_help where context = :context
         fetch first 1 rows only;
         /*
          * コンテキストに対応したページが見つかった。
          * URLがプロトコルで始まっていたら、APEXのドキュメントの代わりに自前のページを表示する
          */
         if not (l_url like 'https://%' or l_url like 'http://%') then
             l_url := C_BASE_URL || l_url;
         end if;
     exception
         when others then
             null;
     end;
     :status_code := 302;
     :location := l_url;
 end;