Dynamics CRM 2013/Fall '13 コマンドバーのカスタマイズ その 3

みなさん、こんにちは。

前回に引き続き、コマンドバーのカスタマイズを紹介します。今回は
カスタムボタンの追加を紹介しますが、手順は前回までの記事からの
続きとなります。

Dynamics CRM 2013/Fall '13 コマンドバーのカスタマイズ その 1
Dynamics CRM 2013/Fall '13 コマンドバーのカスタマイズ その 2

シナリオ

取引先企業のグリッドコマンドバーにカスタムのボタンを追加します。
場所は新規ボタンの右側とし、独自のアイコン、名前、説明を使用、
クリック実行時にカスタムの JavaScript 関数を実行します。

事前準備

カスタムボタンで利用するアイコンと JavaScript は Web リソース
として登録しておきます。

1. 設定よりカスタマイズ | ソリューションを開きます。

2. 以前作成した Command Bar Test ソリューションを開きます。

3. Web リソースをクリックし、新規ボタンをクリックします。

4. 種類より任意の画像形式を選択し、ファイルのアップロードより
16x16 ピクセルの画像を選択します。

5. 任意の名前と表示名で保存します。今回は new_CRM16by16.png
という画像 Web リソースを作成しました。

6. 上書き保存をクリック後、一旦画面を閉じます。

7. 再度新規をクリックします。名前と表示名に任意のスクリプト
名を入力します。ここでは new_CommandBarTest.js としました。

8. 種類よりスクリプト  (JScript) を選択し、テキストエディター
ボタンをクリックします。

9. 以下の関数を入力して、OK ボタンをクリックします。

function showAlert()
{
  alert('test');
}

10. 上書き保存ボタンをクリックしてから画面を閉じます。

11. すべてのカスタマイズを公開後、ソリューションをエクスポート
して Customizations.xml を任意の場所に保存します。

12. Visual Studio で Customizations.xml を開き、前回と同じ手順で
XML スキーマを適用します。

カスタムボタンを追加する

早速今回のシナリオを満たすようにカスタマイズします。カスタム
ボタンの追加を行うためには多くの内容を追加する必要があります。

CustomAction の追加

1. CustomActions ノード配下に CustomAction を追加します。

2. ID に一意となる値を指定します。他のソリューションと重なら
ないように、例えば以下のようなルールで ID を追加します。

<独自サフィックス>.CustomAction.<追加先>.<ボタン名>

今回ボタン名は ShowAlert としてみました。

3. Location にカスタムコマンドを追加したいコントロールグループ
の ID に ._children を追加したものを指定します。今回は新規ボタン
横にカスタムボタンを追加したいので、以下の様に指定します。
ID の確認方法は後ほど紹介します。

4. CustomAction 配下に CommandUIDefinition ノードを追加、さらに
その配下に Button ノードを追加します。

5. Button ノードの要素をそれぞれ以下の様に指定します。

Id : 一意となる id を作成します。
Command : ボタンをクリックした際の挙動を定義します。実際の中身
はこの後作成します。
LabelText, Description, ToolTipDescription : それぞれ画面に表示される
文字列です。
Image16by16 : ボタンのアイコンです。作成済の画像 Web リソースを
$webresource: に続いて指定します。
Sequence : ボタンを表示する位置です。詳細は後ほどで紹介します。

CommandDefinition の追加

次にカスタムボタンをクリックした際の動作を定義します。

1. RibbonDiffXml 配下の CommandDefinition を書き換えて、以下の様に
カスタムの CommandDefinition を追加します。

ここで指定する Id は一意となる必要があり、上記 Button ノードの
Commnad 要素で指定する Id となります。

2. CommandDefinition ノードの配下に以下の 3 つのノードを追加
します。スキーマが有効なら容易に追加できます。

EnableRules : ボタンの有効/無効の判定方法を指定
DisplayRules : ボタンの表示/非表示の判定方法を指定
Actions : ボタンをクリックした際の挙動を指定

※ コマンドバーは有効/無効の概念がないため、EnableRules で無効と
判定された場合、非表示として扱います。

3. Actions ノード配下に以下内容を追加します。

Actions には数種類のアクションが指定できますが、今回は任意の
関数を実行することが目的であるため、JavaScriptFunction を使用
しています。

Library : JavaScript ライブラリのパス。作成済の JavaScript Web
リソースを $webresource: に続いて指定します。
FunctionName : 上記ライブラリに含まれる、実行したい関数名

4. EnableRules と DisplayRules を指定しない場合、表示されない為
以下のように指定します。ここで指定したルールは後で作成します。

DisplayRuels、EnableRules の追加

今回、有効/無効の判定および表示/非表示の判定は極力シンプル
にするため、ブラウザでアクセスした場合に有効とするルールを
作成します。

1. RibbonDiffXml | RuleDefinitions 配下にある DisplayRules と
EnableRules を以下の様に書き換えます。

それぞれの ID は一意である必要があり、CommnadDefinition で
指定しているものと一致します。

EnableRule、DisplayRule ノード配下には実際の判定を行うルール
をしています。それぞれ既定で多くのルールが利用できるように
テンプレートが提供されています。幾つかは次回以降紹介しますが、
今回はクライアントの種別を判定できる、CrmClientTypeRule を
利用しています。上記の場合、ブラウザでアクセスすると true が
返され、有効と判定されます。

ソリューションのインポートと公開

1. Customizations.xml の変更を保存します。

2. ダウンロードした zip ファイル内の Customizations.xml を、保存
したファイルで上書きします。

3. ブラウザに戻り、設定のカスタマイズ | ソリューションより、
変更したソリューションのインポートを実行します。

4. ソリューションのインポート完了後、すべてのカスタマイズを
公開し、ブラウザをリフレッシュします。

5. 取引先企業を表示し、グリッドのコマンドバーにカスタムボタン
が表示されていることを確認します。

6. ボタンクリックで関数が実行されることを確認します。

追加先コントロール ID と Sequence の確認方法

既存コマンドバーの情報は、SDK の以下のフォルダに存在します。

SDK\Resources\ExportedRibbonXml

今回追加したコントロール ID や Secuence は以下手順で確認します。

1. 上記パスにある accountRibbon.xml を Visual Studio で開きます。

2. グリッドにある新規ボタンを文字列 「new」で検索します。

3. 名前より、取引先企業エンティティのグリッドコマンドバーに
表示されている新規ボタンであると目星を付けます。

4. 直前の Controls ノードにある Id 要素がカスタムボタンを追加
したいコントロール ID です。最後に ._children を追加した名前を
使用します。

5. カスタムボタンは新規ボタンと編集ボタンの間に配置したいので
それぞれのボタンの Sequence を確認します。

今回は 10 より大きく 20 より小さい数字として 11 を利用しました。

次回はより複雑な EnableRule、DisplayRule の使用と、複数言語に
対応させる方法を紹介します。

- 中村 憲一郎