コーディングガイドライン

基本構成

esmJSPlugin

グローバルオブジェクトです。 screenオブジェクト、utilオブジェクトを格納しています。

const esmJSPlugin = esmJSPlugin;

独自仕様

eventHook

特定のイベントが発生した際に関数を実行する機構です。
以下のような、メソッド名がonから始まる API を利用することでeventHookを登録することができます。

• Screen.onEntered：対象画面に遷移した時に関数を実行します
• Item.onMounted：インスタンスが初期化された時に関数を実行します

// 顧客登録・変更画面のインスタンスを取得
const customerSaveScreen = esmJSPlugin.screen.sheetSave("customer");

// 顧客登録・変更画面に遷移した時に関数を実行
customerSaveScreen.onEntered(function (screen) {
  console.log("customerSaveScreen entered.");

  // 顧客名項目を取得
  const customerNameItem = screen.getSheetItemByLabel("顧客名");

  // 顧客名項目初期化時に関数を実行
  customerNameItem.onMounted(function () {
    console.log("customerNameItem mounted.");
  });
});

Warning

eventHook のコールバック関数はfunctionで記述してください。

onから始まる API は、これを用いて登録されたeventHookを解除する関数を返します。

const customerSaveScreen = esmJSPlugin.screen.sheetSave("customer");
const unregister = customerSaveScreen.onEntered(function () {
  console.log("entered");
  unregister(); // 解除
});

またListenableのメソッドを利用して解除することもできます。

const customerSaveScreen = esmJSPlugin.screen.sheetSave("customer");
customerSaveScreen.onEntered(function () {
  console.log("entered");
  customerSaveScreen.unlistenAll(); // 解除
});

eventHook のクリーンアップ

Screenインスタンスのメソッドから取得したTargetインスタンスについて、これに紐づくeventHookはScreen.onLeftのタイミングで自動的に解除されます。
したがって以下のように明示的に解除しなくても、onEnteredのたびにeventHookが重複して登録されることはありません。

let unregister;
esmJSPlugin.screen.sheetSave("customer").onEntered(function (screen) {
  const customerNameItem = screen.getSheetItemByLabel("顧客名");

  unregister = customerNameItem.onMounted(function () {
    // 顧客登録変更画面で、顧客名項目初期化時に値を出力する
    console.log(customerNameItem.value);
  });
});

esmJSPlugin.screen.sheetSave("customer").onEntered(function () {
  unregister(); // 不要
});

ただし、画面に遷移してから離れるまでに複数回発生するようなイベントに対してeventHookを登録する場合など、適切なクリーンアップ処理が必要なケースもあります。

// 顧客タイプの切り替えによって表示する項目が変更されるたびに実行される
esmJSPlugin.screen.sheetSave("customer").onSheetItemsUpdated(function (screen) {
  const customerNameItem = screen.getSheetItemByLabel("顧客名");
  customerNameItem.onMounted(function () {
    // 顧客登録変更画面で、顧客名項目初期化時に値を出力する
    console.log(customerNameItem.value);
  });
});

この例では 表示項目が変更(onSheetItemsUpdated)されるたびにcustomerNameItemに対して多重にeventHookが登録されてしまうため、適切にeventHookの解除をする必要があります。

let unregister;

// 顧客タイプの切り替えによって表示する項目が変更されるたびに実行される
esmJSPlugin.screen.sheetSave("customer").onSheetItemsUpdated(function (screen) {
  // 前回のonSheetItemsUpdatedで登録されたcustomerNameItemに対するeventHookがあれば解除
  if (unregister) {
    unregister();
  }

  const customerNameItem = screen.getSheetItemByLabel("顧客名");

  unregister = customerNameItem.onMounted(function () {
    // 顧客登録変更画面で、顧客名項目初期化時に値を出力する
    console.log(customerNameItem.value);
  });
});

関連情報

• Listenable

chainAPI

chainAPI は JS プラグインを書く際の特殊記法です。
メソッドチェーンによって自然言語的に処理を記述することが可能です。

使用例

esmJSPlugin.screen.sheetDetail("customer").onEntered(function (screen) {
  const header = screen.getHeader();
  const flgItem = screen.getSheetItemByLabel("存続フラグ");

  this.useChainAPI(function (chainAPI) {
    chainAPI
      .onMounted(flgItem); // 存続フラグ項目が初期化されたとき
      .ifSelectionLabelEqualsTo("倒産"); // もし選択したラベルが倒産なら
      .setBackgroundColor(header, "gray"); // ヘッダーの背景色をグレーにする
  });
});

詳しくはこちらで説明しています。

sheetNameの確認方法

screenのメソッドでの対象画面の指定等、アプリの指定にはsheetNameを利用します。
以下にデフォルトアプリのsheetNameを列挙します。

アプリ名	sheetName
顧客	customer
名刺	businesscard
案件	businessplan
取引	deal
活動	activity
商品	product
社員	employee
スケジュール	schedule
タスク	task
マイルストーン	milestone

拡張アプリのsheetNameは、アプリ設定画面のオブジェクト名で確認できます。

itemKeyの確認方法

SheetSaveScreen.getSheetItemやSheetDetailScreen.getSheetItemではアプリ項目の指定のためにitemKeyを利用します。
各項目の項目設定で識別子として表示されている文字列がitemKeyに相当します。
ただし、スケジュール、タスク、マイルストーンについては項目設定が存在しないので、以下で各項目のitemKeyを列挙します。

スケジュール

項目名	itemKey
日時	calendar.schedule.datetime
顧客	calendar.schedule.relational_customer
案件	calendar.schedule.relational_businessplan
種別	calendar.schedule.schedule_type
件名	calendar.schedule.subject
スケジュールコード	calendar.schedule.id
住所	calendar.schedule.address
設備・備品	calendar.schedule.relational_assets
参加者	calendar.schedule.participants
当日面談者	calendar.schedule.interviewees
メモ	calendar.schedule.memo
添付ファイル	calendar.schedule.attachment
公開設定	calendar.schedule.is_published
他ユーザが変更／削除	calendar.schedule.editable
登録日	calendar.schedule.system_reg_date
登録者	calendar.schedule.system_reg_user
最終更新日	calendar.schedule.system_upd_date
最終更新者	calendar.schedule.system_upd_user

タスク

項目名	itemKey
完了(予定)日	tasks.task.expected_completion_date
マイルストーン	tasks.task.relational_milestone
ステータス	tasks.task.status_id
顧客	tasks.task.relational_customer
案件	tasks.task.relational_businessplan
タスク名	tasks.task.task_name
優先度	tasks.task.priority_id
タスクID	tasks.task.id
住所	tasks.task.address
担当者	tasks.task.relational_employee
社外担当者	tasks.task.outside_manager
メモ	tasks.task.memo
ファイル	tasks.task.attached_file
公開設定	tasks.task.publishing_setting
他ユーザが変更/削除	tasks.task.is_editable
登録日	tasks.task.system_reg_date
登録者	tasks.task.system_reg_user
最終更新日	tasks.task.system_upd_date
最終更新者	tasks.task.system_upd_user

マイルストーン

項目名	itemKey
完了(予定)日	tasks.milestone.expected_completion_date
完了ステータス	tasks.milestone.milestone_status_id
顧客	tasks.milestone.relational_customer
案件	tasks.milestone.relational_businessplan
マイルストーン名	tasks.milestone.milestone_name
マイルストーンID	tasks.milestone.id
担当社員	tasks.milestone.relational_employee
メモ	tasks.milestone.memo
登録日	tasks.milestone.system_reg_date
登録者	tasks.milestone.system_reg_user
最終更新日	tasks.milestone.system_upd_date
最終更新者	tasks.milestone.system_upd_user

推奨

try...catch によるエラーハンドリング

eventHook のコールバックメソッド外の処理でエラーが発生した場合はハンドリングされません。
コールバックメソッド外に処理を記述する場合はtry...catchを使用したエラーハンドリングを推奨します。

try {
  nonExistentFunction();
} catch (error) {
  console.error(error);
}

非推奨

トップレベルでの await の使用

スクリプトのトップレベルでのawaitはeventHookの登録を遅延させ、期待する動作にならない可能性があります。

await somethingSlowProcess();

// 顧客登録画面遷移時に、まだeventHookが登録されていない可能性がある
esmJSPlugin.screen.sheetSave("customer").onEntered(function () {
  // do something
});