チュートリアル: 最初のクライアント スクリプトを記述する

最初のクライアント スクリプトを記述して物事を把握することができます。 では始めましょう。

目標

このチュートリアルを完了すると、モデル駆動型アプリで JavaScript コードを使用することができます。これには、次のハイレベルなステップが関係します。

• ビジネス上の課題の解決するために JavaScript コードを記述する
• モデル駆動型アプリで Web リソースとして JavaScript コードをアップロードする
• モデル駆動型アプリの異なるクライアント側のイベントに Webリソース で Javascript 関数を関連付ける。

チュートリアルでは、重要な事実に注意を向け、必要に応じて実際のメソッドを参照します。

ステップ 1: カスタム JavaScript コードを記述する

最初のステップは、クライアント スクリプトを使用して解決するビジネス上の課題を特定します。 特定した後、ビジネス上の課題に対処できるカスタム ビジネス ロジックを含む JavaScript コードを記述する必要があります。

モデル駆動型アプリには、JavaScript エディタがありません。 そのため、Notepad++、Visual Studio Code、Microsoft Visual Studio など、JavaScript ファイルの編集機能をサポートする外部作成ツールを活用する必要があります。

この記事の後半のチュートリアルで使用されている完全なサンプル コードを確認できます。

コードの詳細を確認しましょう。

コードの詳細な説明

• 名前空間の定義: コードはカスタム スクリプトの名前空間を定義することから開始します。 ベスト プラクティスとして、関数が他のライブラリの関数に上書きされないように、常に名前空間のある JavaScript ライブラリを作成する必要があります。

  var Sdk = window.Sdk || {};
  

  ここでは、このライブラリで定義されるすべての関数は Sdk.[functionName] として使用できます。

• グローバル変数の定義: 次のセクションは、スクリプトで使用するグローバル変数を定義します。 ユーザー名を取得するために、フォーム コンテキストに目を通す必要はありません。 コンテキスト情報は Xrm.Utility.getGlobalContext メソッドを使用してグローバルで利用できるようになりました。

  // Define some global variables
  var myUniqueId = "_myUniqueId"; // Define an ID for the notification
  var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
  var message = currentUserName + ": Your JavaScript code in action!";
  

• OnLoad イベントで実行するコード: このセクションには、アカウント フォームがロードすると実行されるコードが含まれます。 たとえば、新しい取引先企業レコードを作成する、または既存の取引先企業レコードを開くときです。

  コードは、executionContext オブジェクトを使用して formContext オブジェクトを取得します。 後にフォーム イベントにコードをアタッチするとき、実行コンテキスト をこの関数に渡すオプションを選択するようにします。 次に、setFormNotification メソッドを使用してフォーム レベル通知を表示します。 次に、5 秒後に通知をクリアする clearFormNotification メソッドの実行を遅らせるために setTimeOut メソッドを使用します。

  // Code to run in the form OnLoad event
  this.formOnLoad = function (executionContext) {
      var formContext = executionContext.getFormContext();
  
      // display the form level notification as an INFO
      formContext.ui.setFormNotification(message, "INFO", myUniqueId);
  
      // Wait for 5 seconds before clearing the notification
      window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);        
  }
  

• OnChange イベントで実行するコード: このセクションのコードは、アカウント フォームの アカウント名 列に関連付けられ、アカウント名の値を変更したとき のみ 実行されされます。

  コードは、アカウント名内の "Contoso" に対して大文字と小文字を区別しない検索を実行し、存在する場合は、アカウント フォームの一部の列に値が自動的に設定されます。

  // Code to run in the column OnChange event 
  this.attributeOnChange = function (executionContext) {
      var formContext = executionContext.getFormContext();
  
      // Automatically set some column values if the account name contains "Contoso"
      var accountName = formContext.getAttribute("name").getValue();
      if (accountName.toLowerCase().search("contoso") != -1) {
          formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
          formContext.getAttribute("telephone1").setValue("425-555-0100");
          formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
      }
  }
  

• OnSaveイベントで実行するコード: このセクションのコードは、openAlertDialog メソッドを使用して通知ダイアログ ボックスを表示します。 このダイアログ ボックスには、OK ボタンのあるメッセージが表示され、ユーザーは OK を選択してアラートを閉じることができます。

  Xrm.Utility を実行する必要はないため、この関数で実行コンテキストは渡されません。 メソッドで作成または更新されたレコードが、この属性の影響を受けることはありません。

  // Code to run in the form OnSave event 
  this.formOnSave = function () {
      // Display an alert dialog
      Xrm.Navigation.openAlertDialog({ text: "Record saved." });
  }
  

ステップ 2: スクリプト Web リソースで JavaScript コードを追加する

統一インターフェイス

コードの準備ができたので、モデル駆動型アプリのイベントに関連付けます。 モデル駆動型アプリの スクリプト Web リソース を使用して、モデル駆動型アプリのインスタンスにインスタンスをアップロードし、イベントと関連付けます。

1. Power Apps に移動します。

2. 左のナビゲーション ペインで、データ を選択し、テーブル を選択します。

3. テーブルのリストから、JavaScript Web リソースを追加するテーブルを選択します。

4. フォーム タブを選択し、フォームのリストから目的のフォームを選択します。

   

5. 左側のナビゲーション ペインから フォーム ライブラリ を選択し、ライブラリの追加 を選択します。

   

6. JavaScript Web リソースを作成するには、新規 を選択します。

7. 新しい Web リソース ダイアログで、Web リソースの 名前 と 表示名 を指定します。 例: "mySampleScript.js" および "サンプル: チュートリアル" スクリプト。

8. 種類 ドロップダウン リストで、スクリプト (JScript) を選択します。 ファイルの選択 を選択して JavaScript コードを含むファイルをアップロードするか、テキスト エディター を選択してエディターに JavaScript コードを貼り付けます。

   

9. 保存 を選択し、JavaScript コードを含む Web リソースを作成します。

10. 公開 を選択して Web リソースを公開します。

レガシ

コードの準備ができたので、モデル駆動型アプリのイベントに関連付けます。 モデル駆動型アプリの スクリプト Web リソース を使用して、モデル駆動型アプリのインスタンスにインスタンスをアップロードし、イベントと関連付けます。

1. ブラウザーでモデル駆動型アプリ インスタンスに移動し、右上隅にある歯車のアイコンを選択してから、詳細設定 を選択します。
2. 設定 > カスタマイズ に移動します。
3. カスタマイズ領域で、システムのカスタマイズ をクリックします。
4. ソリューション エクスプローラーの コンポーネント で、Web リソース を選択します。
5. 新規 を選択して、Web リソースを作成します。
6. 新しい Web リソース ダイアログで、Web リソースの 名前 と 表示名 を指定します。 例: "mySampleScript.js" および "サンプル: チュートリアル" スクリプト。
7. 種類 ドロップダウン リストで、スクリプト (JScript) を選択します。 ファイルの選択 を選択して JavaScript コードを含むファイルをアップロードするか、テキスト エディター を選択してエディターに JavaScript コードを貼り付けます。
8. JavaScript コードを含む Web リソースを作成するには 保存 を選択します。
9. Web リソースを公開するには、公開 を選択します。

ステップ 3: スクリプト Web リソースをフォームに関連付ける

統一インターフェイス

1. Power Apps に移動します。

2. 左のナビゲーション ペインで、データ を選択し、テーブル を選択します。

3. テーブルのリストから、イベント ハンドラーを追加するテーブルを選択します。

4. コマンドバーから フォーム タブを選択して、追加するフォームを選択します。

   

5. イベント タブを選択します。保存時 と ロード時 のイベント ハンドラーがあります。

   

6. OnLoad イベント ハンドラーを選択し、実行する機能を関連付けます。

   

7. OnSave イベント ハンドラーを選択し、実行する機能を関連付けます。

   

8. On Change イベントのイベント ハンドラーを追加する場合は、列を選択してから、イベント タブを選択します。

   

OK! JavaScript コードで指定したカスタム ビジネス ロジックを使用するように取引先企業フォームを構成する手順が完了しました。

レガシ

コードの関数をイベントに関連付けるために、JavaScript コードを含む Web リソースをモデル駆動型アプリのフォームに関連付けます。 このチュートリアルの JavaScript コードは、取引先企業レコードをターゲットとしているため、Web リソースと取引先企業フォームを関連付けます。

1. ブラウザーでモデル駆動型アプリのインスタンスにアクセスし、Sales > 取引先企業 または サービス > 取引先企業 に移動します。

2. 取引先企業レコードを開き、フォーム を選択してフォーム エディターを開きます。

   

3. フォーム エディターで、フォーム プロパティ を開きます。

4. フォーム プロパティ ダイアログ ボックスの イベント タブで、追加 を選択し、Web リソースを検索および追加します。

   

5. 次のダイアログ ボックスで、Web リソース名を検索して選択し、追加 を選択して、取引先企業フォームの JavaScript ライブラリとして追加します。

   

これにより、フォーム プロパティ ダイアログの イベント ハンドラー セクションで、Web リソースが選択できるようになります。 JavaScript コードには、フォームの適切なイベントに関連付けられる 3 つの関数があります。

1. イベント ハンドラー セクションで、コントロールとして Form、イベント として OnLoad を選択します。追加 を選択し、OnLoad イベントのイベント ハンドラーを追加します。

   

2. ハンドラー プロパティ ダイアログ ボックスで次を行います。

   • ライブラリ ドロップダウン リストから Web リソースの名前を選択し、および Sdk.formOnLoad を 関数 列で指定します。 関数名は JavaScript コードの [名前空間].[関数] です。

   • この関数にパラメーターとして実行コンテキストを渡すには、実行コンテキストを最初のパラメーターとして渡す を選択します。 コードの関数の定義を確認すると、関数の定義に executionContext オブジェクトを渡しており、このオプションを選択するとそれらが関連付けられます。

     

3. OK を選択して、フォーム プロパティ ダイアログ ボックスに戻ります。

4. イベント ハンドラー セクションで、今回は イベント として OnSave を選択します。追加 を選択し、Form OnSave イベントのイベント ハンドラーを追加します。

   

5. ハンドラーのプロパティ ダイアログ ボックスで、ライブラリ ドロップダウン リストから Web リソースの名前を選択し、Sdk.formOnSave を 関数 列で指定します。 実行コンテキストは Sdk.formOnSave 関数コードでは必要とされないため、今回は関数に渡しません。

   

6. OK を選択して、フォーム プロパティ ダイアログ ボックスに戻ります。

7. イベント ハンドラー セクションで、コントロールとして アカウント名、イベントとして OnChange を選択します。追加 を選択し、OnChange イベントのイベント ハンドラーを追加します。

   

8. ハンドラー プロパティ ダイアログ ボックスで次を行います。

   • ライブラリ ドロップダウン リストから Web リソースの名前を選択し、Sdk.attributeOnChange を 関数 列で指定します。

   • この関数にパラメーターとして実行コンテキストを渡すには、実行コンテキストを最初のパラメーターとして渡す を選択します。 コードの関数の定義を確認すると、関数の定義に executionContext オブジェクトを渡しており、このオプションを選択するとそれらが関連付けられます。

     

9. OK を選択して、フォーム プロパティ ダイアログ ボックスに戻ります。

10. フォーム プロパティ ダイアログ ボックスで OK を選択し、フォーム エディターに戻ります。

11. フォームへの変更を保存するには、保存 を選択します。

12. 公開 を選択し、フォームの変更を公開します。

OK! JavaScript コードで指定したカスタム ビジネス ロジックを使用するように取引先企業フォームを構成する手順が完了しました。

JavaScript コードのテスト

モデル駆動型アプリ インスタンスで変更を有効にするため、ブラウザーを更新することをお勧めします。 このチュートリアルで構成したカスタム ビジネス ロジックをテストするには

1. モデル駆動型アプリのインスタンスにサインインします。

2. 取引先企業 に移動して、新しい取引先企業を開くか作成します。 この場合、取引先企業フォームを読み込むために既存の取引先企業を開きます。 自分のユーザー名が含まれる通知が表示され、5 秒後に自動で非表示になります。

   

3. アカウント名を編集して名前に "Contoso" を追加し、Tab キーを押して次の列に移動します。 これにより、OnChange イベントが発生し、コードで指定された値で 電話、Web サイト、説明 の列が自動的に更新されます。

   

4. 最後に 保存 を選択すると、OnSave イベントがトリガーされ、コードで構成したメッセージと共にアラート ダイアログが表示されます。 OK を選択してアラートを閉じます。

   

チュートリアルで使用される完全なサンプル コード

// A namespace defined for the sample code
// As a best practice, you should always define 
// a unique namespace for your libraries
var Sdk = window.Sdk || {};
(function () {
    // Define some global variables
    var myUniqueId = "_myUniqueId"; // Define an ID for the notification
    var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
    var message = currentUserName + ": Your JavaScript code in action!";

    // Code to run in the form OnLoad event
    this.formOnLoad = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // display the form level notification as an INFO
        formContext.ui.setFormNotification(message, "INFO", myUniqueId);

        // Wait for 5 seconds before clearing the notification
        window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);
    }

    // Code to run in the column OnChange event 
    this.attributeOnChange = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // Automatically set some column values if the account name contains "Contoso"
        var accountName = formContext.getAttribute("name").getValue();
        if (accountName.toLowerCase().search("contoso") != -1) {
            formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
            formContext.getAttribute("telephone1").setValue("425-555-0100");
            formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
        }
    }

    // Code to run in the form OnSave event 
    this.formOnSave = function () {
        // Display an alert dialog
        Xrm.Navigation.openAlertDialog({ text: "Record saved." });
    }
}).call(Sdk);

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。