2022年8月3日水曜日

CKEditor5による画像アップロードを実装する(2) - REST APIの作成

CKEditor5にて画像の貼り付けを行なったときに発行される、画像のアップロード要求を受け付けて表RTE_IMAGESに保存する処理と、画像のダウンロード要求を受け付けるREST APIを作成します。

作成するREST APIは、以下の記事で紹介しているREST APIとほとんど同じです。APEXセッションによる保護の設定についても同じです。

Oracle REST Data ServicesのマニュアルにあるImage Galleryのサンプル・アプリを作成する

以下より、今回作成しているアプリケーションのためのREST APIを作成します。

記述する作業は、画像のアップロードとダウンロードに関するものに限定します。それ以外の作業は、上記の記事が参考になります。


画像のアップロードを受け付けるAPIを作成する



SQLワークショップのRESTfulサービスを開きます。

左ペインにてモジュールを選択し、モジュールの作成を実行します。


モジュール名としてrteditor、ベース・パスとして/rteditor/を設定し、モジュールの作成を実行します。本番環境で使用するといったものではないため、公開はONにしておきます。


モジュールrteditorが作成されます。続けて、テンプレートの作成を実行します。


URIテンプレートとしてimageを入力します。テンプレートの作成を実行します。


テンプレートimageが作成されます。ハンドラの作成を実行します。


メソッドにPOSTを選択し、ソースに以下を記述します。

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


ハンドラが作成されます。完全なURLはAPEXアプリケーションで使用するため、記録しておきます。


以上で画像をアップロードするAPIの実装は完了です。


画像をダウンロードするAPIを作成する



左ペインにてモジュールrteditorを選択し、テンプレートの作成を実行します。


URIテンプレートとしてimage/:idを設定します。

画像のアップロードを受け付けるREST APIは、自分自身のURLに画像のIDを付加したURLを、画像のダウンロードURLとして返しています。そのため、ここで指定するテンプレートは(アップロードのテンプレートがimageなので)必ずimage/:idとします。

テンプレートの作成を実行します。


テンプレートimage/:idが作成されます。ハンドラの作成を実行します。


メソッドとしてGET、ソース・タイプとしてMedia Resourceを選択します。ソースに以下の1行を記載します。

select content_type, image from rte_images where id = :id

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


ハンドラが作成されました。


以上で画像をダウンロードするAPIの実装は完了です。


REST APIを保護する



作成したREST APIを、APEXで認証されたセッションからのみ呼び出しができるように保護します。マニュアルでは、ファースト・パーティ認証として説明されています。

ロールは新規作成せず、デフォルトで作成されているRESTful Servicesを使います。


左ペインにて権限を選択します。権限の作成をクリックします。


権限の名前をrteditor、タイトルは画像付き文書とします。ロールとしてRESTful Services、保護されたモジュールとしてrteditorをそれぞれ選択し、権限の作成をクリックします。


以上でモジュールrteditorのREST APIの保護が設定されました。

ユーザーとグループの管理を開き、モジュールrteditorのREST APIを呼び出すAPEXユーザーにRESTful Servicesのロールを割り当てます。


ロールを割り当てるユーザーの設定を開き、グループ割当てのセクションでRESTful Servicesを割り当てます。

変更の適用を実行します。


これで、グループ割当て(ロール)としてRESTful Servicesが割り当たったユーザーでサインインしたAPEXアプリケーションより、作成したREST APIを呼び出すことができるようになりました。

2022年8月2日火曜日

CKEditor5による画像アップロードを実装する(1) - 準備

Louis MoreauxさんがCKEditor5の画像アップロードを行う方法を、CKEditor5 Image Uploadという記事にしていました。Oracle APEX 22.1から使用できます。この機能を使って、画像を含んだ文書の編集を行うアプリケーションを作成してみます。

Oracle APEX 23.1より、リッチ・テキスト・エディタはCKEditor5からTinyMCEに置き換えられています。本記事ではCKEditor5を使った画像アップロードを実装します。

作成するアプリケーションは、以下のような動作になります。機能の実装を目的としていて、細かいユーザー・インターフェースの調整などは省略しています。


元記事の説明は、根幹となる機能の実装方法に限られています。そのため、元記事だけで完全なアプリケーションを作るのは難しいです。できるだけ、手順を追えば同じアプリケーションを作成できるように説明します。


文書と画像を保存する表を作成する



文書を保存する表RTE_DOCUMENTSと画像を保存する表RTE_IMAGESを作成します。表の作成にはクイックSQLの以下のモデルを使います。
# prefix: rte
# pk: guid
documents /auditcols
    title    vc200
    content  clob
    author   vc80
    published date
    
images
    document_id /fk documents
    content_type vc200
    image blob
    created date /nn
    created_by vc255 /nn
SQLワークショップのユーティリティのクイックSQLを開きます。左側に上記のモデルを記述し、SQLの生成、SQLスクリプトを保存、レビューおよび実行を順番に実施します。


SQLスクリプトのレビュー画面が開きます。

クイックSQLの不具合だと思われますが、監査列の生成を指定していないにも関わらず、列にCREATED、CREATED_BYが含まれていると、対応したトリガーを作成するCREATE TRIGGER文が生成されます。このトリガーrte_images_biuは不要なので、create trigger文を削除します。

[2024年10月9日追記]
APEX 24.1.5で確認したところ、クイックSQLでトリガーrte_images_biuは作成しなくなりましたが、表rte_imagesの列created_byの型がdateになってしまいます。DDLを実行する前にvarchar2(255 char)に変更する必要があります。

SQLスクリプトの修正後、実行をクリックします。


確認画面が開きます。即時実行をクリックします。


4行の実行が成功し、エラーがなければ表RTE_DOCUMENTSとRTE_IMAGESが問題なく作成されています。


表の作成は以上で完了です。


基本的なアプリケーションを作成する



作成した表RTE_DOCUMENTS、RTE_IMAGESの基本的な操作を行うアプリケーションを作成します。Oracle APEXのアプリケーション作成ウィザードを実行します。

アプリケーションの名前を画像付き文書とします。ホームの編集をクリックして開き、削除します。


ホーム・ページの編集画面です。削除をクリックします。確認のダイアログが表示されるので、OKをクリックします。


表RTE_DOCUMENTSを一覧するレポートのページと、編集を行うフォームのページを作成します。ページの追加をクリックします。


対話モード・レポートを選択します。


対話モード・レポートのページ名は画像付き文書とします。表またはビュー、対話モード・レポートを選択します。

表またはビューとしてRTE_DOCUMENTSを選択し、フォームを含めるにチェックを入れます。詳細のホームページとして設定にチェックが入っていることを確認します。

以上で、ページの追加をクリックします。


表RTE_IMAGESのメンテナンスを行う画面を追加します。エンド・ユーザーがこの画面を使用する予定はありません。

先ほどと同様に、ページの追加をクリックします。


追加ページを開いて、複数のレポートを選択します。


表名の一覧より、RTE_IMAGESのみにチェックをいれます。ページの追加をクリックします。


追加されたページImagesの編集をクリックします。


詳細を開き、管理ページとして設定にチェックを入れます。以上で、変更の保存をクリックします。


ページImagesのアイコンがスパナに変わります。

以上のページ構成で、アプリケーションの作成を実行します。


アプリケーションが作成されます。これから色々な機能を実装するページは、ページ番号1の画像付き文書と、2のDocumentです。




アプリケーションを調整する



監査列のコメント・アウトと、フォームに含まれるページ・アイテムのレイアウトを調整します。

ページ番号1の対話モード・レポートのページを開き、列CREATED、CREATED_BY、UPDATED、UPDATED_BYを選択します。その後にプロパティ・エディタの構成のビルド・オプションとしてコメント・アウトを選択し、保存を実行します。


続いてページ番号2のフォームのページを開き、ページ・アイテムP2_CREATED、P2_CREATED_BY、P2_UPDATED、P2_UPDATED_BYを選択し、構成のビルド・オプションでコメント・アウトを選択します。


ページ・アイテムP2_TITLEのタイプがテキスト・フィールドであることを確認します。異なる場合はテキスト・フィールドに変更します。


ページ・アイテムP2_CONTENTの位置を、P2_PUBLISHEDの下に移動します。


ページ・アイテムP2_CONTENTの識別のタイプをリッチ・テキスト・エディタに変更します。APEX 23.1よりリッチ・テキスト・エディタの実装としてTinyMCEが採用されていますが、今回は設定のライブラリとしてCKEditor [Deprecated]を選択します。

設定の書式にMarkdownを選択します。HTMLも選択できますが(Louis Moreauxさんの記事はHTMLを使っています)、クロスサイト・スクリプティングの影響を軽減するためにMarkdownを選んでいます。最小高はデフォルトの180ピクセルから変更しません。


ページ・アイテムP2_PUBLISHDがP2_AUTHORの右隣に配置されるよう、レイアウトの新規行の開始をOFFにします。


ページの外観のダイアログ・テンプレートをDrawerからModal Dialogに変更します。

以上で変更を保存します。


この状態でアプリケーションを実行し、動作を確認します。ページ番号2はモーダル・ダイアログのページなので、アプリケーションに一旦戻ってから、アプリケーションを実行します。

これまでの実装では、以下のような動作になります。標準的な対話モード・レポートとフォームの組み合わせです。


準備作業はここまでです。

次の記事では、画像のアップロードとダウンロードを行うREST APIを作成します。

Tab入力の移動先を変更する

 ボタン上でTab入力を行ったときに、デフォルトの移動先を変更する方法を紹介します。使用しているアプリケーションは、こちらの記事で作成したものです。

最初にボタンのHTML要素を取得するため、詳細の静的IDを設定します。

以下では、ボタンB_SUBMITに静的IDとしてB_SUBMITを設定しています。


ページ・プロパティのJavaScriptのファンクションおよびグローバル変数の宣言として、以下を記述します。

document.getElementById("B_SUBMIT").onkeydown = function(event) {
    if (event.key == "Tab") {
        apex.items.P1_TEXT.setFocus();
        event.preventDefault();
    }
};

event.preventDefault();を呼び出さないとTabのデフォルトの動作も発生するため、フォーカスを当てた次のページ・アイテムにフォーカスが移動します。今回のコード例ではページ・アイテムP1_TEXTにフォーカスを移動していますが、event.preventDefault();を呼び出さないと、その次のP1_LISTにフォーカスが移動します。

完

2022年8月1日月曜日

Enterの入力でページ・アイテムのフォーカスを移動する

 キーボードのEnterを入力した時点で、次のページ・アイテムにフォーカスを移動する方法を考えてみました。


上記では、ページ・アイテムとして上から、テキスト・フィールド、選択リスト、ポップアップLOV、日付ピッカーが並んでいます。Enterを入力すると、次のページ・アイテムにフォーカスを移動します。

それぞれのページ・アイテムに、ほぼ同様の動的アクションを作成しています。

タイミングのイベントとして、キー・ダウン、選択タイプはアイテム、アイテムとして自分自身を指定します。(ページ・アイテムP1_TEXTの動的アクションのタイミングのアイテムはP1_TEXTにします。)

イベントとしてはキー・プレスも取れますが、ポップアップLOVではEnterのキー・プレスのイベントを取ることができませんでした。キー・ダウンを取る必要があります。

クライアント側の条件としてJavaScript式を選択し、JavaScript式に以下を記述します。Enterが入力されたときに限り、TRUEアクションが実行されます。

this.browserEvent.originalEvent.key == "Enter"


TRUEアクションとしてフォーカスの設定を選び、影響を受ける要素の選択タイプをアイテム、アイテムとしてフォーカスの移動先のアイテムを選択します。

ページ・アイテムP1_TEXTでEnterを押された場合は、フォーカスをページ・アイテムP1_LISTに移動するので、ここではP1_LISTを指定します。

初期化時に実行は必ずOFFにします。


実際に受け取ったイベントを確認するために、以下のJavaScriptを実行してメッセージを表示しています。

apex.message.showPageSuccess(
    this.browserEvent.originalEvent.key +
    " on " +
    this.triggeringElement.id
);

ページ・アイテムP1_LISTから、ページ・アイテムP1_LOVへフォーカスを移動しています。

ページ・アイテムP1_LOVから、ページ・アイテムP1_DATEへフォーカスを移動しています。


ページ・アイテムP1_DATEから、ページ・アイテムP1_TEXTへフォーカスを移動しています。


以上で、最初のGIF動画のような動作になります。

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

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

追記


それぞれ動的アクションを設定すると見通しが悪いという場合は、ページ・プロパティのJavaScriptのファンクションおよびグローバル変数の宣言に以下を記述することで同じ動作になります。
// P1_TEXT to P1_LIST
document.getElementById("P1_TEXT").onkeydown = function(event) {
    if (event.key == "Enter") {
            apex.items.P1_LIST.setFocus();
    }
};
// P1_LIST to P1_LOV
document.getElementById("P1_LIST").onkeydown = function(event) {
    if (event.key == "Enter") {
            apex.items.P1_LOV.setFocus();
    }
};
// P1_LOV to P1_DATE
document.getElementById("P1_LOV").onkeydown = function(event) {
    if (event.key == "Enter") {
            apex.items.P1_DATE.setFocus();
    }
};
// P1_DATE to P1_TEXT
document.getElementById("P1_DATE").onkeydown = function(event) {
    if (event.key == "Enter") {
            apex.items.P1_TEXT.setFocus();
    }
};

完

ページ・アイテムの書式を検証する

 前回の記事で、主キーの書式を検証する方法について説明を省いていたので、その方法について少し紹介してみます。

必ずしも主キーである必要はなく、書式の決まった列のデータが対象になります。

前回の記事を元にして、表NK_TESTの列CODEを対象とします。

列CODE(ページ・アイテムとしてはP3_CODE)の書式を、英大文字3文字と数値4文字を"-"で連結した文字列に限定します。以下がコードの例になります。

ABC-2323

XEF-9981


チェック制約を使う


データベースの表にチェック制約を適用し、指定した書式以外でのデータ入力を禁止します。以下の正規表現と一致すると、書式が正しいと判断します。

^[A-Z]{3}\-[0-9]{4}$

以下のALTER文を実行し、列CODEにチェック制約CODE_FORMAT_CHECKを作成します。

alter table nk_test add constraint code_format_check check (regexp_like(code,'^[A-Z]{3}\-[0-9]{4}$','c'));

書式の正しくないCodeを入力し、発生するエラーを確認します。


ORA-2290が発生し、そのメッセージがそのまま表示されます。

エラー処理ファンクションを定義することにより、表示されるエラー・メッセージを変更することは可能です。

APEXに限らず、どのような方法によるデータ入力でも、列CODEの書式が正しいことが保証される点は良いことです。他方、APEXアプリケーションからみると、データを送信するまで入力値の検証が行われないこと、エラー・メッセージがユーザーに分かりにくいというデメリットがあります。


ページ・アイテムの検証を使う


ページ・アイテムP3_CODEに検証を作成します。

作成した検証の識別の名前を書式の検証とします。検証のタイプは式、言語にPL/SQLを選択し、PL/SQL式として以下の正規表現を使った式を記述します。

regexp_like(:P3_CODE,'^[A-Z]{3}\-[0-9]{4}$','c')

今回は主キー項目ということもあり、常に実行はONにします。

エラーのエラー・メッセージとして以下を記述します。

#LABEL#の書式が正しくありません。

表示位置としてフィールドおよび通知でインライン表示を選択し、関連づけられたアイテムをP3_CODEとします。

以上の設定で、発生するエラーを確認してみます。

エラーの表示位置としてフィールドおよび通知でインライン表示を選択しているため、ページ自体とページ・アイテムにインラインでエラー・メッセージが表示されます。

開発者によってエラー・メッセージを定義できるのは良い点です。ただし、データを送信するまで書式の検証が行われない点に違いはありません。


動的アクションを使う


値が変更される都度、動的アクションで書式の検証を行います。

ページ・アイテムP3_CODEに動的アクションを作成します。TRUEアクションとしてJavaScriptコードの実行を選択し、設定のコードに以下を記述します。


動的アクションによる検証では、値の変更が確定した時点でエラー・メッセージが表示されます。


また、正しい書式のデータを入力し直すと、エラー・メッセージが消去されます。データの送信は不要です。


あらゆる場合で、表NK_TESTの列CODEに保存される値の書式を保証するわけではありませんが、APEXアプリケーションの利用者からみた使いやすさという点で、メリットがあります。


大文字入力を強制する



ユニバーサル・テーマのコンテント・モディファイアを使うと、ページ・アイテムの入力を大文字に強制することができます。製品コードなどには英大文字を使う場合が多いと思うので、設定しておくと便利でしょう。

詳細のCSSクラスにu-textUpperを指定すると、入力する英字がキーボードの設定に関わらず大文字になります。


以上、ページ・アイテムの書式の検証方法の紹介でした。

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

完