Developers

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

JSプラグインの基本構成

esmJSPlugin

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

const esmJSPlugin = esmJSPlugin;

JSプラグインの独自仕様

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);
  });
});

関連情報

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
タスクIDtasks.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
マイルストーンIDtasks.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

注意事項

DOM構造、id、class属性の変更

eセールスマネージャーの各要素に付与されているidやclass属性の値は、予告なく変更されます。
DOM構造についても変更されることがあります。

プラグインを作成する際は、次を参照または変更するような処理を記述しないでください。

  • DOM構造
  • 各要素のidやclass属性の値

DOM要素を操作する場合、esm Developers記載のAPIを使用してください。

複数のプラグイン適用による機能の競合

複数のプラグインをeセールスマネージャーに適用する場合、プラグイン同士が競合する可能性があります。
運用に支障がないことを検証したうえでアプリにプラグインを適用してください。

Webブラウザーによる挙動の違い

Webブラウザーの種類やバージョンの違いによって、期待した動作にならない場合があります。
動作確認の際には、複数のWebブラウザーを使用することを推奨します。
eセールスマネージャーの推奨ブラウザーについては以下のリンクをご確認ください。

活用支援サイト｜推奨ブラウザー・端末について

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
});

eセールスマネージャーが正常に動作しなくなった場合

プラグインの影響でeセールスマネージャーが正常に動作しなくなった場合、クエリパラメータにjsplugin-disabled=trueを付与することによってブラウザ上でプラグインが実行されない状態にすることが出来ます。プラグインが実行されない状態にした後、JSプラグイン設定画面で原因となるプラグインを非公開にしてください。

例：
https://esm.softbrain.com/sample/calendar?jsplugin-disabled=true