モデル駆動型アプリで最初のクライアントスクリプトを記述する

モデル駆動型アプリで最初の JavaScript クライアントスクリプトを記述する方法について説明します。このチュートリアルでは、スクリプトを作成し、Web リソースとしてアップロードし、フォームイベントと列イベントにアタッチして、カスタムビジネスロジックをフォームに追加できるようにテストする方法を示します。

目標

このチュートリアルを完了すると、モデル駆動型アプリで JavaScript コードを使用する方法がわかります。このプロセスには、次の大まかな手順が含まれます。

作業を追加するソリューションを見つけるか作成する
ビジネス上の課題の解決するために JavaScript コードを記述する
Web リソースとしてコードをアップロードする
Web リソースをフォームに関連付ける
フォームとフィールドのイベントを構成する
コードをテストする

Note

完了したウォークスルーを確認および検証するには、JavaScriptWebResourceExampleSolution_1_0_managed.zip をダウンロードします。このマネージドソリューションをインストールし、含まれているアカウント管理アプリを確認してください。

ステップ 1: ソリューションを見つけるか作成する

ソリューションを使用して、カスタマイズをある環境から別の環境に転送します。アンマネージドソリューションの一部として、開発環境で JavaScript コードを記述してテストします。テストが完了したら、ソリューションをマネージドソリューションとしてエクスポートし、運用環境にインポートまたはインストールします。

既存のソリューションを既に使用できる場合があります。スクリプトでカスタマイズするモデル駆動型アプリは、既にソリューションの一部である必要があります。そのソリューションを編集することも、別の既存のソリューションに依存する新しいソリューションを作成することもできます。

新しいソリューションを作成するには

Power Apps に移動します。
左のナビゲーションペインで ソリューション を選択してから 新しいソリューション を選択します。
ポップアップダイアログで、[ 表示名]、[名前]、[発行元 ] を入力 します。

ほとんどの企業は、常に使用する既存の発行元を持っています。その発行元を使用します。最初のユーザーの場合は、独自の発行元を作成します。

[ 新しい発行元] を選択して、[ 新しい発行元 ] ダイアログを開きます。このチュートリアルでは、次の定義でパブリッシャーを使用します。

接頭辞 の値に注目します。この値は、会社を識別する必要があります。この場合は、 exampleを使用します。

このソリューションは、このチュートリアルで使用するソリューションです。
モデル駆動型アプリを見つけるか、ソリューションに追加します。

新しいソリューションには、モデル駆動型アプリは含まれません。既存のモデル駆動型アプリを追加するか、新しいアプリを作成する必要があります。

Note

このチュートリアルでは、アプリにアカウントテーブルが含まれていることを必ず確認してください。以下のスクリプトと手順では、Account テーブルのフォームにあるフィールドが必要です。

オプションA: 既存のモデル駆動型アプリをソリューションに追加する
1. ソリューションで 既存を追加>アプリ>モデル駆動型アプリ を選択します。
1. 既存のアプリを選択し、[ 追加] を選択します。
オプション B: ソリューションで新しいモデル駆動型アプリを作成する

ソリューションで、New>App>モデル駆動型アプリを選択します。

モデル駆動型アプリを初めて作成するチュートリアルを参照してください。アカウントテーブルを含むアプリを作成します。

ステップ 2: JavaScript コードを記述する

最初の手順では、クライアントスクリプトを使用して対処するビジネス上の問題を特定します。問題を特定したら、ビジネス上の問題に対処するカスタムビジネスロジックを含む JavaScript コードを記述します。

モデル駆動型アプリでは、JavaScript エディターは提供されません。 Notepad++、Visual Studio Code、Microsoft Visual Studio など、JavaScript ファイルの編集機能をサポートする外部作成ツールを使用します。

このチュートリアルでは、次の JavaScript コードを使用します。

// Define a unique namespace for the sample library.
window.Example ??= {};

(() => {
    const notificationId = "_myUniqueId";
    const currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName;
    const message = `${currentUserName}: Your JavaScript code in action!`;

    // Code to run in the form OnLoad event
    window.Example.formOnLoad = (executionContext) => {
        const formContext = executionContext.getFormContext();

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

        // Wait for 5 seconds before clearing the notification
        window.setTimeout(
            () => formContext.ui.clearFormNotification(notificationId),
            5000
        );
    };

    // Code to run in the column OnChange event
    window.Example.attributeOnChange = (executionContext) => {
        const formContext = executionContext.getFormContext();

        // Automatically set some column values if the account name contains "Contoso"
        const accountName = formContext.getAttribute("name").getValue();
        if (accountName?.toLowerCase().includes("contoso")) {
            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
    window.Example.formOnSave = () => {
        // Display an alert dialog
        Xrm.Navigation.openAlertDialog({ text: "Record saved." });
    };
})();

このコードをテキストファイルにコピーし、 form-script.jsとして保存します。

コードの詳細な説明

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

名前空間の定義: コードはカスタムスクリプトの名前空間を定義することから開始します。ベストプラクティスとして、名前空間付きの JavaScript ライブラリを常に作成して、別のライブラリ内の関数によって関数がオーバーライドされないようにします。
```
window.Example ??= {};
```
この場合、このライブラリで定義されているすべての関数を Example.[functionName]として使用できます。ソリューションの発行元名と一致する名前空間を選択します。
定数の定義: 次のセクションでは、スクリプトで使用する定数をいくつか定義します。 Xrm.Utility.getGlobalContext メソッドを使用すると、コンテキスト情報にグローバルにアクセスできます。
```
const notificationId = "_myUniqueId";
const currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName;
const message = `${currentUserName}: Your JavaScript code in action!`;
```
OnLoad イベントで実行する関数: このセクションには、アカウントフォームの読み込み時に実行される関数が含まれています。たとえば、新しい取引先企業レコードを作成する、または既存の取引先企業レコードを開くときです。

Example.formOnLoad 関数は、executionContext パラメーターを使用して formContext オブジェクトを取得します。後でフォームイベントを使用してコードをアタッチする場合は、実行コンテキストをこの関数に渡すオプションを選択します。

この関数は、 formContext.ui.setFormNotification メソッドを使用してフォームレベルの通知を表示します。

最後に、この関数は、5 秒後に通知をクリアする formContext.ui.clearFormNotification メソッドの実行を遅らせるために、JavaScript setTimeOut method メソッドを使用します。
```
// Code to run in the form OnLoad event
window.Example.formOnLoad = (executionContext) => {
    const formContext = executionContext.getFormContext();

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

    // Wait for 5 seconds before clearing the notification
    window.setTimeout(
        () => formContext.ui.clearFormNotification(notificationId),
        5000
    );
};
```

OnChange イベントで実行する関数: アカウントExample.attributeOnChangeの値を変更した場合にのみ実行されるように、関数をアカウントフォームの [アカウント名] 列に関連付けます。

この関数は、取引先企業 Contoso において name を大文字と小文字を区別せずに検索し、存在する場合は、取引先企業フォームの websiteurl、telephone1、description 列に値を設定します。

// Code to run in the column OnChange event
window.Example.attributeOnChange = (executionContext) => {
    const formContext = executionContext.getFormContext();

    // Automatically set some column values if the account name contains "Contoso"
    const accountName = formContext.getAttribute("name").getValue();
    if (accountName?.toLowerCase().includes("contoso")) {
        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 イベントで実行する関数: Example.formOnSave 関数は、Xrm.Navigation.openAlertDialog メソッドを使用してアラートダイアログボックスを表示します。このダイアログボックスには、メッセージと OK ボタンが表示されます。ユーザーは[ OK]を選択してアラートを閉じます。

Note

Xrm.Navigation メソッドでは必要ないため、この関数では実行コンテキストは使用されません。
```
// Code to run in the form OnSave event
window.Example.formOnSave = () => {
    // Display an alert dialog
    Xrm.Navigation.openAlertDialog({ text: "Record saved." });
};
```

ステップ 3: コードを Web リソースとしてアップロードする

コードの準備ができたら、ソリューションにアップロードします。

ソリューションで、[ 新規>詳細>Web リソース] を選択します。
[ 新しい Web リソース ] ダイアログで、[ ファイルの選択 ] を選択し、前に保存した form-script.js ファイルを選択します。
表示名、名前、および必要に応じて説明を入力します。型が JavaScript (JS) であることを確認します。
Note
- 名前には、ソリューションパブリッシャーのカスタマイズプレフィックスと一致するプレフィックスがあります。 Web リソースを作成する方法は他にもありますが、この方法で Web リソースを作成すると、Web リソースがソリューションの一部になります。
- Web リソースの名前は example_form-script.js です。

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

ソリューションで、[ オブジェクト>Apps>Your App ] を選択し、[ 編集 ] を選択します。
[ アカウント] を展開し、[ アカウント] フォームを選択します。情報フォームの右側にある省略記号 (...) を選択し、[編集] を選択します。
左側のナビゲーションで、[ フォームライブラリ ] を選択し、[ ライブラリの追加 ] を選択します。
JavaScript ライブラリの追加 ダイアログで、Example Script という名前で作成した JavaScript Webリソースを検索します。
サンプルスクリプト Web リソースを選択し、[追加] を選択します。

ステップ 5: フォームとフィールドのイベントを構成する

イベント タブを選択します。

フォーム読み込み時イベントを構成する

On Load イベントハンドラーを選択し、+ Event Handler を選択します。

次の設定が正しいことを確認してください。
- イベントの種類 は 読み込み時 です。
- example_example-form-script ライブラリが選択されます。
1. [ 関数 ] フィールドに関数の名前を入力します。この場合は、「 Example.formOnLoad」と入力します。
2. 実行コンテキストを最初のパラメーターとして渡す を選択します。
3. 完了を選択します。

フォーム保存時イベントを構成する

[保存時] イベントハンドラーを選択し、[+ イベントハンドラー] を選択します。

次の設定が正しいことを確認してください。
- イベントの種類 は 保存時 です。
- example_example-form-script ライブラリが選択されます。
1. 関数フィールドに関数の名前を入力します。この場合は、「 Example.formOnSave」と入力します。
  
  Note
  
  この関数では使用されないため、この関数の 最初のパラメーターとして [実行コンテキストを渡す ] を選択する必要はありません。
2. 完了を選択します。

[変更時] フィールドの設定を行うイベント

取引先企業名 フィールドを選択し、イベント タブを選択します。
[変更時] イベントハンドラーを選択し、[+ イベントハンドラー] を選択します。

次の設定が正しいことを確認します。
- イベントの種類 は 変更時 です。
- example_example-form-script ライブラリが選択されます。
1. [ 関数 ] フィールドに関数の名前を入力します。この例では Example.attributeOnChange です。
2. 実行コンテキストを最初のパラメーターとして渡す を選択します。
3. 完了を選択します。