データをページからパラメーターとしてリボン操作に渡す

操作をリボン上に定義する場合、ページからデータを JavaScript 関数または URL に渡す処理が頻繁に必要とされます。 ここでは、<CrmParameter> 要素を使用してこれらの値を取得するためのオプションについて説明します。

リボン アクションのフォームとグリッドのコンテキスト

実行コンテキスト (フォーム コンテキスト または グリッド コンテキスト) 情報をリボン操作の Javascript 関数に渡すには、リボン定義で <CrmParameter> 値として、フォーム コンテキストには PrimaryControl、グリッド コンテキストには SelectedControl を指定します。 SelectedControl は、サブグリッドおよびホームページ グリッドの両方に、グリッド コンテキストを渡します。 PrimaryControl または SelectedControl で渡された値は、それぞれ フォーム コンテキスト または グリッド コンテキスト の JavaScript 関数で引数として使用されます。

たとえば、ここに PrimaryControl パラメーターを JavaScript 関数に渡す場所であるサンプル リボン定義があります:

<CommandDefinition Id="SampleCommand">
  <EnableRules/>
  <DisplayRules/>
  <Actions>
    <JavaScriptFunction Library="$webresource:new_mySampleScript.js" FunctionName="mySampleFunction">
      <CrmParameter Value="PrimaryControl" />
    </JavaScriptFunction>
  </Actions>
</CommandDefinition>

次に、上記のサンプルで参照される new_mySampleScript.js Web リソース ファイルで、primaryControl 変数を引数として指定して Javascript 関数を定義します。 この引数は、リボン コマンドが実行されるところで フォーム コンテキストを提供します:

function mySampleFunction(primaryControl) {
    var formContext = primaryControl;
    // Perform operations using the formContext object
}

また、リボン定義で <CrmParameter> 値として CommandProperties を指定すると、リボン コントロールからイベントの詳細を渡すこともできます。 この機能を使用するとコンテキスト情報を中央機能に送信できるので、JavaScript 関数はイベントのコンテキストに基づいて、実行する操作を決めることができます。

注意

リボン アクションでの JavaScript 関数用フォーム コンテキストおよびグリッド コンテキストの取得は、フォーム スクリプト内での取得方法とは異なります。 フォーム スクリプトおよび、これらのコンテキストを取得する方法については、「クライアント API フォーム コンテキスト」および「クライアント API グリッド コンテキスト」を参照してください。

フォーム値

フォーム リボンに対しては、data.entity.attributes コレクションと ui.controls コレクションを使用して、既知のフィールドから値を取得して設定できます。

たとえば、次のサンプル コードは、取引先企業フォーム上の取引先企業名フィールドを取得し、取引先企業名の値に基づいて websiteurl フィールドに値を設定する方法を示しています。

function mySampleFunction(primaryControl) {
    var formContext = primaryControl;    
    var accountName = formContext.getControl("name").getAttribute().getValue();    

    // Set the WebSiteURL field if account name contains "Contoso"
    if (accountName.toLowerCase().search("contoso") != -1) {
        formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
    }
    else {
        Xrm.Navigation.openAlertDialog({ text: "Account name does not contain 'Contoso'." });
    }
}

グリッド値

<CrmParameter> 要素で使用可能な値の大半は、グリッドまたは階層グラフで表示されるデータを操作するためのものです。 Value 属性列挙オプションを使用すると、次のアイテムからアイテムを簡単に切り分けることができます。

  • 選択されているアイテム

    • SelectedControlSelectedItemCount

    • SelectedControlSelectedItemIds

    • SelectedControlSelectedItemReferences

  • すべての項目

    • SelectedControlAllItemCount

    • SelectedControlAllItemIds

    • SelectedControlAllItemReferences

  • 選択されていないアイテム

    • SelectedControlUnselectedItemCount

    • SelectedControlUnselectedItemIds

    • SelectedControlUnselectedItemReferences

    これらのグループ分けごとに、アイテムの数や GUID 識別子を収集できます。 値を URL に渡している場合は、グリッド内のオブジェクトを一意に識別するために必要なすべての情報を格納した EntityReference オブジェクトも取得できます。 これらのパラメーターは、表示中のページがメイン グリッド (HomepageGrid) である場合とフォーム内のサブグリッドである場合のどちらにも適用されます。 SelectedEntityTypeName パラメーターと組み合わせて使用すると、別のアプリケーションに渡す必要がある情報がすべて入手できます。

その他のコンテキスト情報

データ値のほかに、 <CrmParameter> を使用してクライアント コンテキスト情報を取得できます。 CrmParameter 要素の値として次のオプションを使用できます。OrgNameOrgLcid、および UserLcid

<Url> 操作を行う場合は、PassParams 属性を使用してコンテキスト情報を含めることもできます。

Value オプションの PrimaryEntityTypeNameFirstPrimaryItemId は、エンティティ レコードの情報を提供します。 PrimaryItemIds リボンの HomepageGrid を使用して、すべての表示中アイテムのリストを取得できます。

関連項目

リボンのカスタマイズ
リボンの使用による URL へのパラメーターの受け渡し
リボン アクションの定義
ユーザー定義のアクションによるリボンの変更
クライアントAPIフォームコンテキスト
クライアントAPIグリッドコンテキスト