ヘルパとコントローラ

最終更新日: 2024年6月17日
R8 | R9

ヘルパのスクリプト

「画面 > スクリプト」では実行タイミングを指定して、スクリプトを記述することができます。

スクリプトの入力

Wagby Designer で記述するスクリプトは「呼び出されるタイミング」を指定します。これは「ヘルパ」と「コントローラ」に大別されます。この二つの役割は次のとおりです。

ヘルパ コントローラ
タイミング モデル（1件のデータ）を処理している間。 ユーザによるボタン操作（アクション）
記述する内容 主にモデルの操作。SQLを使わずにモデルの値を直接、操作することができる。 主にユーザから入力された値の取得と、画面遷移。
トランザクションとの関係 トランザクション境界の内部である。（トランザクションは開始されている。）更新系のヘルパでは、モデルへの値の変更は自動的にデータベースに反映される。 トランザクションは開始されていない、または終了後である。
ロールバック 例外 BusinessLogicException をスローすることで、現在のトランザクションをロールバックさせることができる。 できない。
SQLを利用する データベースとの接続を行うsessionオブジェクト(*1)が利用できる状態にあるため、SQL(*2)を利用できる。(*3) データベースとの接続を行うsessionオブジェクトをスクリプト内で用意し、使い終わったら必ずクローズ処理を行う必要がある。(*4)(*5)
1. その実体は HibernateSession です。
2. 正確には Hibernate に最適化された HQL (Hibernate Query Language) です。
3. ヘルパで更新系のSQLを使う場合、自モデルの値の変更は行わないようにしてください。スクリプトの終了後に、メモリ上のモデル（ストアモデル）の値でデータベースが更新されます。
4. 詳細はSQLを利用するをお読みください。
5. コントローラでは自モデル、他モデルを問わず更新系のSQLを使うことができます。ここでトランザクションは開始されていないか、または終了しているため、いったん更新されたデータに対して再度、更新を行うという動作になります。

ヘルパの詳細

入力したスクリプトから、拡張子 ".js" のファイルが生成されます。実ファイルは wagbyapp/webapp/$(APPNAME)/WEB-INF/script/モデルIDフォルダ の中に用意されます。

※ $(APPNAME) は、プロジェクト識別子です。標準は "wagby" となっています。
タイミング 説明 生成されるファイル
登録 「初期値 > 登録時」を行ったあとに呼び出されます。登録直前のデータを修正することができます。この処理を行った後のデータが、データベースに保存されます。 <モデルID>Helper_beforeInsert.js
登録(初期データ作成) 「初期値 > 登録画面表示時」を行ったあとに呼び出されます。新規登録用のデータを修正することができます。この処理を行った後のデータが、登録画面に表示されます。（このタイミングではデータベースへは保存されません。） <モデルID>Helper_initialize.js
登録後9.2.2 登録処理が成功したあとに呼び出されます。例えば成功時にのみメールを送信したい、といった処理を記述できます。すでにデータは保存されているため、データを変更することはできません。（自データだけでなく、他データの変更もここでは行えません。） <モデルID>Helper
_afterCommittedInsertion.js
更新 「初期値 > 更新時」を行ったあとに呼び出されます。更新直前のデータを修正することができます。この処理を行った後のデータが、データベースに保存されます。 <モデルID>Helper_beforeUpdate.js
更新後9.2.2 更新処理が成功したあとに呼び出されます。例えば成功時にのみメールを送信したい、といった処理を記述できます。すでにデータは保存されているため、データを変更することはできません。（自データだけでなく、他データの変更もここでは行えません。） <モデルID>Helper
_afterCommittedUpdation.js
コピー9.2.0 コピー登録画面を開いたとき、コピー処理の後で呼び出されます。コピーされた値を書き換えることができます。[コピー登録時に枝番を設定する例...] <モデルID>Helper_copy.js
詳細画面表示 「初期値 > 詳細画面表示時」を行ったあとに呼び出されます。表示直前のデータを修正することができます。この処理を行った後のデータが、詳細画面に表示されます。（データベースには反映されません。表示の直前で内部のデータを改変する必要がある場合に利用できます。例えば一部のデータを表示時に隠す、などです。）このスクリプトで値を更新する処理を記述することはできません。また、このスクリプトは一回のリクエスト処理中に何度も呼び出されることがあります。そのため複数回呼び出されても動作が変わらないようにしてください。 <モデルID>Helper_beforeShow.js
詳細画面表示(登録) 親子モデル同時更新画面利用時、親の登録画面を開くときに呼び出されます。(スクリプト内では親モデルIDに対応したオブジェクトを利用できます。) 注:親モデルに計算式もしくは参照連動項目が含まれている必要があります。これらが含まれていない場合、このスクリプトは呼び出されません。 <親モデルID>Helper_beforeShowInInsert.js
詳細画面表示(更新) 更新画面を開くときに呼び出されます。また、親子モデル同時更新画面利用時に親の更新画面を開くときに呼び出されます。(この場合、スクリプト内では親モデルIDに対応したオブジェクトを利用できます。) 注:親モデルに計算式もしくは参照連動項目が含まれている必要があります。これらが含まれていない場合、このスクリプトは呼び出されません。 <親モデルID>Helper_beforeShowInUpdate.js
詳細画面表示(一覧) 親子モデル同時更新画面利用時、親の一覧画面を開くとき、親の各データごとに呼び出されます。(スクリプト内では親モデルIDに対応したオブジェクトを利用できます。) このスクリプトで値を更新する処理を記述することはできません。 <親モデルID>Helper_beforeShowInShowList.js
詳細画面表示(アップロード更新) アップロード更新でデータを1件処理した直後に呼び出されます。(計算式または参照連動項目が含まれているモデルのみ有効) <モデルID>Helper_beforeShowInUploadUpdate.js
計算 定義済みの計算式を実行したあとに、このスクリプトが呼び出されます。 <モデルID>Helper_calc.js
一括更新 画面機能 > 一括更新 の処理内容を記述します。 ShowList<モデルID>Controller_do_updateRule.js
帳票内容の編集 Excel/PDF帳票の前に呼び出されます。出力内容を修正することができます。 ReplaceMapHelper_remake.js
帳票出力後 Excel/PDF帳票出力後に呼び出されます。実際にはコントローラのスクリプトとなります。例えば出力後に "帳票出力日" を設定したいという場合、EntityService を使ってモデルを取得し、更新するようにしてください。 Show<モデルID>Controller_print.js
帳票出力後(一覧) Excel/PDF帳票出力後に呼び出されます。実際にはコントローラのスクリプトとなります。例えば出力後に "帳票出力日" を設定したいという場合、EntityService を使ってモデルを取得し、更新するようにしてください。 ShowList<モデルID>Controller_print.js
入力チェック 標準で用意している必須チェックや文字数チェックのあとに呼び出されます。独自のチェック処理を追加することができます。 <モデルID>PInputCheckHelper_input_check.js
入力チェック(検索)9.0.0 検索フォームで呼び出されます。独自のチェック処理を追加することができます。 <モデルID>CpInputCheckHelper_input_check.js
入力チェック(一覧更新) 標準で用意している必須チェックや文字数チェックのあとに呼び出されます。独自のチェック処理を追加することができます。 <モデルID>UlpInputCheckHelper_input_check.js
入力フィルタ 標準で用意している入力フィルタ処理のあとに呼び出されます。独自のフィルタ処理を追加することができます。 <モデルID>PFilterHelper_filter.js
入力フィルタ(検索) 標準で用意している入力フィルタ処理のあとに呼び出されます。独自のフィルタ処理を追加することができます。 <モデルID>CpFilterHelper_filter.js
入力フィルタ(一覧更新) 標準で用意している入力フィルタ処理のあとに呼び出されます。独自のフィルタ処理を追加することができます。 <モデルID>UlpFilterHelper_filter.js
論理削除 判定ルールを独自に決めることができます。 <モデルID>Helper_logicalDelete.js
ダウンロード 検索条件（クライテリア）をカスタマイズするタイミングとして用意されています。「検索」とは別のスクリプトです。p.requestは空となっており、Webフォームからのパラメータを取得することはできません。 Download<モデルID>CriteriaConverter_convert.js
ダウンロード(開始時) ダウンロード処理の開始時に一回だけ呼び出されます。 Download<モデルID>_processStart.js
ダウンロード(終了時) ダウンロード処理の終了時に一回だけ呼び出されます。 Download<モデルID>_processEnd.js
ダウンロード(1件出力前) ダウンロードするファイルの内容を加工することができます。 Download<モデルID>_outputCsv.js
アップロード更新(開始時) アップロード更新処理の開始時に一回だけ呼び出されます。 UploadUpdate<モデルID>_processStart.js
アップロード更新(終了時) アップロード更新処理の終了時に一回だけ呼び出されます。 UploadUpdate<モデルID>_processEnd.js
アップロード更新(1件読み込み前) アップロード更新でデータを1件読み込む前に呼び出されます。ファイルの内容を加工することができます。 UploadUpdate<モデルID>_readRowDataInFileProcessor.js
アップロード更新(1件読み込み後) アップロード更新でデータを1件読み込んだ直後に呼び出されます。 UploadUpdate<モデルID>_AfterRead.js
アップロード更新(1件処理後)9.2.0 アップロード更新でデータを1件処理した直後に呼び出されます。 UploadUpdate<モデルID>_AfterUpdate.js
アップロード更新(ヘッダ読み込み時) スクリプトでヘッダ行を指定することができます。 UploadUpdate<モデルID>_readHeader.js
検索(初期値) 検索条件の初期値を設定することができます。一度設定された検索条件は再利用されるため、このスクリプトは "初回の検索条件の設定" でのみ呼び出されます。 <モデルID>CHelper_initialize.js
検索(前処理) 検索処理の直前に呼び出されます。クライテリアのカスタマイズではなく、コンディションモデルの値を書き換えるという場合は、こちらを使ってください。なお、ここでコンディションモデルを書き換えても画面上は反映されません。 <モデルID>CHelper_beforeSearch.js
検索 検索条件（クライテリア）をカスタマイズするタイミングとして用意されています。ダウンロード時の検索は別途「ダウンロード」のタイミングに記述する必要があります。

※ 全文検索機能を適用したモデルはクライテリアを利用しないため、このスクリプトは呼び出されません。		 <モデルID>CriteriaConverter_convert.js
検索(一覧更新) UpdateList<モデルID>CriteriaConverter_convert.js
検索(サブウィンドウ検索) SearchList<モデルID>CriteriaConverter_convert.js
検索(カレンダビュー) CalendarView<モデルID>CriteriaConverter_convert.js
検索(帳票画面) ReportList<モデルID>CriteriaConverter_convert.js
削除 削除処理の直前に呼び出されます。なおアップロード更新処理からは、この削除スクリプト(beforeDelete)は呼び出されません。 <モデルID>Helper_beforeDelete.js
削除後9.2.2 削除処理が成功したあとに呼び出されます。例えば成功時にのみメールを送信したい、といった処理を記述できます。すでにデータは削除されているため、データを変更することはできません。（自データだけでなく、他データの削除もここでは行えません。） <モデルID>Helper
_afterCommittedDeletion.js
プレゼンテーションモデルからストアモデルへの変換 プレゼンテーションモデルからストアモデルへの変換の前に preprocess() を、変換の後に process() を呼び出します。 <モデルID>PHelper_p2s.js
ストアモデルからプレゼンテーションモデルへの変換 ストアモデルからプレゼンテーションモデルへの変換の前に preprocess() を、変換の後に process() を呼び出します。絞り込みで利用した例を紹介しています。 <モデルID>PHelper_s2p.js
コンディションモデルのプレゼンテーションモデルからコンディションモデルへの変換9.2.2 コンディションモデルのプレゼンテーションモデルからコンディションモデルへの変換の前に preprocess() を、変換の後に process() を呼び出します。 <モデルID>CpHelper_p2s.js
コンディションモデルからコンディションモデルのプレゼンテーションモデルへの変換9.2.2 コンディションモデルからコンディションモデルのプレゼンテーションモデルへの変換の前に preprocess() を、変換の後に process() を呼び出します。 <モデルID>CpHelper_s2p.js
ファイル項目ダウンロード ファイル項目のダウンロード処理の直前に呼び出されます。モデルやモデル項目に関わらず、すべてのファイル項目で呼び出されます。 DownloadFile_beforeDownload.js
ファイル項目アップロード ファイル項目のアップロード処理の直後に呼び出されます。モデルやモデル項目に関わらず、すべてのファイル項目で呼び出されます。 UploadFile_afterUpload.js

ワンポイント

処理を行う前に呼び出す場合は関数 preprocess を用意することができます。

スクリプトと画面の関係

スクリプトは、用意する画面と関連しています。そのため、例えば詳細画面を作成しないモデルでは"詳細画面表示"や"削除"に関するスクリプトは生成されません。

コントローラのスクリプト

画面に用意されたボタン押下のタイミングで実行されるスクリプトです。コントローラのスクリプトは、次に遷移する画面を返します。詳細は「スクリプトを使った画面遷移」で説明します。

スクリプトと画面の関係

スクリプトは、用意する画面と関連しています。そのため、例えば詳細画面を作成しないモデルでは、画面"詳細"に関するスクリプトは生成されません。

共通スクリプト

「環境タブで設定できる共通スクリプト」をお読みください。

トランザクション

複数の登録、更新、削除処理を一つの塊としてデータベースにコミットまたはロールバックすることをトランザクションといいます。Wagby はトランザクションを実現するために二つの方法を提供しています。

(1) 関連するモデルが定義で定まっている場合

Wagby が標準で提供するモデル参照という仕組みを用いて自身に紐づくモデルが定まっている場合、簡単にトランザクションのスクリプトを作成することができます。自身の変更にあわせて（自身に）紐づくモデルの更新を同時に行うことができます。

このトランザクション処理はモデル項目詳細定義で記述します。詳細は「モデル間の計算（トランザクション）」で説明します。

トランザクション制御時のスクリプト

トランザクションスクリプトで（自身に紐づくモデル以外の）任意のモデルを操作する方法も提供しています。この場合は Dao クラスを使います。[詳細...]

(2) 開発者が自由にトランザクションのコードを記述する場合

開発者は直接、Wagbyが生成する EntityService というクラスを使ってトランザクションのコードを記述することができます。 詳細は「Service/Daoクラス、ヘルパ、SQLを利用する」で説明します。

キャメル記法

項目ID

スクリプト内の項目IDには次のルールが適用されます。

  • 名前に "_" （アンダースコア）が含まれている場合（これを「複合語」と呼びます）、その "_" を除去し、その次の文字を大文字とします。例えば "customer_id" は "customerId" になります。"kana_name" は "kanaName" になります。
  • 複合語でなければ変換されません。例えば "item1" は "item1" のままです。
  • アンダースコアを取り除いたあとの先頭が小文字で、二文字目が大文字の場合、先頭も大文字となります。例えば "p_number" は "pNumber" となったあと、最終的に "PNumber" になります。
  • 項目IDに小文字が(1文字以上)含まれる場合、先頭は小文字になります。このルールから、項目IDの先頭が大文字であっても、そのあとに小文字が含まれる場合は先頭は小文字になります。例えば "Item1" は先頭が大文字の "I" ですが、そのあとに小文字があるため、スクリプトでは "item1" となります。

モデルID

スクリプトファイル名に含まれるモデルIDや、画面遷移を指定する場合のアクション名に含めるモデルIDは、次のルールが適用されます。

  • 先頭は大文字になります。例えばモデルID が "customer" の場合、スクリプトファイル名は "Customer" で始まります。
  • 詳細画面を意味するアクション名の接頭語 "show" を付与したものは "showCustomer" になります。モデルIDが "my_funny_valentine" の場合は "showMyFunnyValentine" になります。

例外

ヘルパ

ヘルパ系のスクリプトでは、例外 BusinessLogicException をスローすることで、現在のトランザクション処理をロールバックさせることができます。 

throw new Packages.jp.jasminesoft.jfc.core.exception.BusinessLogicException("エラーメッセージ");

なお、スクリプトによってエラーメッセージとロールバックの挙動は変わります。

タイミング エラーメッセージの扱い ロールバック
登録 "データベースへの登録処理に失敗しました。" に続いて、エラーメッセージが表示される。 ロールバックされる。
登録(初期データ作成) エラーメッセージが表示される。
更新 "データベースへの更新処理に失敗しました。" に続いて、エラーメッセージが表示される。
詳細画面表示 "データベースへのアクセスに失敗しました。" に続いて、エラーメッセージが表示される。(*9) (トランザクションは開始されていない)
詳細画面表示(登録) 親子モデル同時更新画面の親モデル登録画面表示時にエラーメッセージが表示される。(*9) (トランザクションは開始されていない)
詳細画面表示(更新) 親子モデル同時更新画面の親モデル更新画面表示時にエラーメッセージが表示される。(*9) (更新画面が表示されない)
詳細画面表示(一覧) 画面そのものが表示されません。(*9) (一覧画面が表示されない)
詳細画面表示(アップロード更新) アップロード更新実行後、画面にエラーメッセージが表示される。すべてエラー行としてカウントされる。エラー処理結果ファイルにメッセージが記録される。 処理は正常に実行されるが、エラー行は更新されない。
計算 "データベースへのアクセスに失敗しました。" に続いて、エラーメッセージが表示される。(*10) 登録、更新処理であればロールバックされる。
一括更新 複数のエラーメッセージがまとめて表示される。 ロールバックされる。
帳票内容の編集 画面にメッセージは表示されない。ログに表示される。帳票処理自体は行われる。 ロールバックされない。
帳票出力後
帳票出力後(一覧)
入力チェック エラーメッセージが表示される。 ロールバックされる。
入力チェック(一覧更新) "(対象モデル名)に、X件の入力エラーデータがあります。" と表示される。一覧更新の対象行に "エラー" という文字が表示されており、マウスオーバーでエラーメッセージが表示される。
入力フィルタ エラーメッセージが表示される。 ロールバックされる。
入力フィルタ(検索) エラーメッセージが表示される。 検索されない。
入力フィルタ(一覧更新) エラーメッセージが表示される。 ロールバックされる。
論理削除 "データベースの削除処理に失敗しました。" のあとにエラーメッセージが表示される。 ロールバックされる。
ダウンロード ログファイルに Download<モデルID>ProcessBean クラスの outputAllData メソッドで例外発生という警告として表示される。画面にはエラーメッセージは表示されない。 処理は継続されるがダウンロードファイルにデータは含まれない。
ダウンロード(開始時) "データベースへのアクセスに失敗しました。" のあとにエラーメッセージが表示される。 処理は停止する。ダウンロードされない。
ダウンロード(終了時) ログファイルに DbDownloadBaseProcessBean クラスの processEnd メソッドで例外発生という警告が記録される。画面にはエラーメッセージは表示されない。 処理は終了する。ダウンロードファイルにデータは含まれている。
ダウンロード(1件出力前) ログファイルに DbDownloadProcessorImpl_Csv クラスの outputCsv メソッドで例外発生という警告が記録される。画面にはエラーメッセージは表示されない。 処理は終了する。ダウンロードファイルにデータは含まれている。
アップロード更新(開始時) アップロード更新実行後、エラーメッセージが表示される。 処理は実行されない。
アップロード更新(終了時) 画面にエラーメッセージが表示される。 処理は正常に実行される。
アップロード更新(1件読み込み前) アップロード更新実行後、エラーダイアログが表示される。ダイアログにエラーメッセージが表示される。 処理は実行されない。
アップロード更新(1件読み込み後) アップロード更新実行後、エラー行としてカウントされる。エラー処理結果ファイルにメッセージが記録される。 処理は正常に実行されるが、エラー行は更新されない。
アップロード更新(ヘッダ読み込み時) アップロード更新実行後、エラーダイアログが表示される。ダイアログにエラーメッセージが表示される。 処理は実行されない。
検索(初期値) エラーメッセージが表示される。（グリッド形式の場合、最初の画面遷移のみ "不適切なパラメータが指定されました。" というメッセージが表示される。） 検索は行われない。
検索(前処理) エラーメッセージが表示される。（グリッド形式の場合、最初の画面遷移のみエラーメッセージが表示される。） 検索は行われない。
検索 エラーメッセージが表示される。（グリッド形式の場合、最初の画面遷移のみエラーメッセージが表示される。） 検索は行われない。
検索(一覧更新) エラーメッセージが表示される。（グリッド形式の場合、エラーはログに記録されるが、画面そのものが表示されなくなる。） 検索は行われない。
検索(サブウィンドウ検索) 参照先モデルのスクリプトが呼び出される。サブウィンドウにエラーメッセージが表示される。 サブウィンドウ側の検索は行われる。
検索(カレンダビュー) エラーメッセージが表示される。 検索は行われない。
検索(帳票画面) 「帳票出力」ボタン押下時、エラーメッセージが表示される。 帳票出力は行われない。
削除 エラーメッセージが表示される。 ロールバックされる。
ストアモデルからプレゼンテーションモデルへの変換 エラーメッセージが表示される。 ロールバックされる。
プレゼンテーションモデルからストアモデルへの変換
ファイル項目ダウンロード エラーメッセージは表示されない。ログレベル INFO で "Correspond download file check." というメッセージの後、エラーメッセージが記録される。 ファイルのダウンロードは行われる。
ファイル項目アップロード エラーダイアログが表示される。ログレベル INFO で "Correspond upload file check." というメッセージの後、エラーメッセージが記録される。 アップロードしたファイルは無視される。
9. 利用者が意図しない状況となるため、このスクリプトで BusinessLogicException 例外を発生させないようにしてください。
10. 詳細画面ではエラーとなりますが、一覧表示画面では画面そのものが表示されなくなります。

コントローラ

コントローラ系のスクリプトでは、例外 BusinessLogicException に格納するメッセージは、画面遷移情報として扱われます。これは return 命令で画面遷移情報を返すことと同じです。画面にエラーメッセージとして表示されることはありません。

呼び出されるスクリプトファイル名を確認する

次の方法で、どのようなスクリプトファイルがどのタイミングで呼び出されるかを調べることができます。

  1. ビルドされたアプリケーションの webapps\$(APPNAME)\WEB-INF\classes フォルダに含まれる jfcbase.properties をテキストエディタで開きます。
  2. 次の行を見つけ、先頭の ";" を除きます。
    （修正前） 
    ;jp.jasminesoft.jfc.ScriptCodeRunner.isOutputStatusToConsole=true
    ;jp.jasminesoft.jfc.ScriptCodeRunner4Controller.isOutputStatusToConsole=true
    （修正後） 
    jp.jasminesoft.jfc.ScriptCodeRunner.isOutputStatusToConsole=true
    jp.jasminesoft.jfc.ScriptCodeRunner4Controller.isOutputStatusToConsole=true

  3. アプリケーションを起動します。
  4. アプリケーションを操作するたびに、Tomcatのコンソールに、どのスクリプトファイルを実行しようとしたかが表示されます。（ファイルが存在しなければ実行されることはありません。）