Dynamics CRM 2011 リボンのカスタマイズパート 4

Article
05/25/2011

みなさん、こんにちは。

引き続きリボンのカスタマイズ紹介です。今回は、カスタムタブの追加と
今までの知識を利用した機能を紹介します。パート 1 からの知識を前提
にしていますので、まだご覧でない方は、事前に読んでください。

まずはサンプルからです。

サンプルソリューション

まずは以下のフォルダにあるソリューションを、Dynamics CRM 2011 に
インポートしてください。

sdk\walkthroughs\ribbon\addacustomtabtoaspecificentity.zip

営業案件にカスタムタブ、グループ、コントロールが追加されます。

[営業案件のグリッド]

[営業案件のフォーム]

[営業案件サブグリッド]

RibbonDiffXml の構成

今回もまず customizations.xml ファイルを見ていきます。

LocLabels 要素

今まで同様英語のラベルしか定義されていませんので、対応する
日本語を追加します。

RuleDefinitions 要素

DisplayRule, EnableRule は今回設定されておらず、TabDisplay
ルールが設定されています。タブの表示や有効化のルールは、
CommandDefinition で指定が可能です。

TabDisplayRule 要素

タブの表示/非表示の条件を設定します。属性は以下の通りです。
TabCommand : タブ用の CommandDefinition ID を指定

EntityRule 要素

現在の画面が、指定したエンティティの画面であるか確認します。
属性は以下の通りです。

EntityName : 対象となるエンティティの名称
Context : リボンの表示場所の指定
- Form : フォーム用
           - HomePageGrid : グリッド用
           - SubGridStandard : フォーム上のサブグリッド用
           - SubGridAssociated : ナビゲーションの関連サブグリッド用
AppliesTo : 条件の適用先
           - PrimaryEntity : フォーム用
           - SelectedEntity : グリッド用

CommandDefinitions 要素

今回 RuleDefinitions にカスタムの DisplayRule と EnableRule を
定義していないため、Dynamics CRM 2011 が初めから用意している
Rule を利用しています。

DisplayRule : Mscrm.CanWriteOpportunity
この DisplayRule は opportunityribbon.xml に定義されています。
営業案件エンティティにユーザーレベル以上の書き込み権限があれば
True を返します。

EnableRule : Mscrm.Enabled
この EnableRule は常に True を返します。

ボタンコントロール用の CommandDefinition は Action も設定
していますが、グループ用、タブ用は Action は不要のため、表示
と有効のルールのみ設定しています。

CustomActions 要素

前回のカスタムグループ追加では、コントロールを子要素に持つ
Group 要素がありましたが、カスタムタブを追加する場合には、
Group 要素を子要素にする Tab 要素を利用します。また Maxsize
および Scale 要素は、 Tab の子要素である Scaling 要素内に
配置されます。

CustomAction 要素

重要な属性は Location です。カスタムタブを配置する場所として Mscrm.Tabs を
指定し、追加の意味である _children を指定しています。

Tab 要素

Tab 要素は以下の属性を持ちます。
Id : 一意の ID を作成します。
Command : CommandDefinition の Id です。 TabDisplayRule で指定した
CommandDefinition と同じものを指定します。
Sequence : カスタムタブの表示優先度です。
Title と Description : タイトルと説明です。LocLabels を指定できます。

Scaling 要素

グループスケール用の MaxSize と Scale 要素を含めるための要素です。

サンプルの更新と動作の確認

日本語のラベルを追加したので、編集した customizations.xml を保存してから、
addacustomtabtoaspecificentity.zip 内に上書きしソリューションを再度
インポートしてください。

表示が以下のように変わっていれば編集成功です。

チャレンジ

これまでの記事で、すでにカスタムコントロールの追加、カスタムグループの
追加とスケーリング、カスタムタブの追加をマスターしていると思います。
またカスタムの RuleDefinitions や CommandDefinitions も習得されて
いると思います。

そこで以下のチャレンジを行いたいと思います。

内容

今回編集したサンプルソリューションをさらに編集します。以下の内容を
実装してください。

- グリッド用カスタムタブに、第 2 、第 3 グループを追加する。

第 2 グループに関して
- 第 1 グループで利用しているボタン 1 ~ 3 を追加する。クリック時の動作
とアイコンはそのまま利用し、ToolTip のみ変更する。
- 営業案件エンティティに対して、ユーザーレベル以上の削除権限がある
場合のみ、グループを表示する。表示されている場合には常に有効。
- 1 番目のボタンは、常に表示、有効にする。
- 2 番目のボタンは、常に表示、グリッドでレコードが 1 件だけ選択されてる
場合にのみ有効にする。
- 3 番目のボタンは、常に表示、グリッドでレコードが複数選択されている
場合にのみ有効にする。

第 3 グループに関して
- 第 1 グループで利用しているボタン 4 を追加する。クリック時の動作
とアイコンはそのまま利用し、ToolTip のみ変更する。
- グループは常に表示、有効にする。
- ボタンは、常に表示、グリッド内の全てのレコードが選択された場合に
のみ有効にする。

表示領域が狭くなった場合には、第 1、第 2、第 3 グループの純で
Popup 化する。

チャレンジの回答サンプル

私は以下のように実現しました。

LocLabels要素

グループ用のラベルは既に定義されていたため再利用。他のものは
以下の要素を Loclabes 子要素として追加。

RuleDefinitions 要素

2 つの DisplayRule と 3 つの EnableRule を追加。常に表示に該当するルールのサンプルと
して、OrRule を使って ClientType を網羅してみました。ただし CommandDefinition の
DisplayRule 要素で何も指定しない場合にも、常に表示の要件は満たせます。

またグリッドの全てのレコードを選択した場合のみ有効のルールには、CustomRule を使用
してみました。パラメータとして、現在選択されていないレコード数を関数に渡し、関数内で
選択されていないレコードの数が 0 の場合 True を返すようにして実現しています。

以下 new_SelectAllEnableRule の内容です。パラメータの数値を確認
しているだけのシンプルなものです。

function countUnselected(count){
if(count == 0)
return true;
else
return false;
}

CommandDefinitions 要素

追加のグループ用に 2 つと、ボタン用に 4 つ追加しています。それぞれ
要件にあった DisplayRule、EnableRule、Action を指定しました。
また第 3 グループのボタンに関しては、DisplayRule を指定せず、常に
表示するサンプルとしています。

CustomActions 要素

2 つのグループ用定義と Maxsize 要素、また 3 つの Scale 要素を追加しました。
追加したグループのコントロールの属性は、作成した LocLabel と Command を
間違えないように慎重に追加しました。

既存の要素内に追加していますので、コメント  を入れました。

<Group Id ="Sample.Grid.opportunity.CustomTab.SecondGroup" Command="Sample.Grid.opportunity.SecondGroup" Sequence="20" Title="$LocLabels:Sample.opportunity.CustomTab.SecondGroup.Title" Template="Mscrm.Templates.3.3">
                    <Controls Id="Sample.Grid.opportunity.CustomTab.SecondGroup.Controls">
                      <Button Id="Sample.Grid.opportunity.CustomTab.SecondGroup.FirstButton" ToolTipTitle="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.FirstButton.LabelText" ToolTipDescription="$LocLabels:Sample.opportunity.CustomTab.SecondGroup.FirstButton.ToolTipDescription" Command="Sample.Grid.opportunity.SecondGroup.FirstButton" Sequence="10" LabelText="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.FirstButton.LabelText" Alt="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.FirstButton.LabelText" Image16by16="$webresource:sample_/icons/1Icon16x16.png" Image32by32="$webresource:sample_/icons/1Icon32x32.png" TemplateAlias="o1" />
                      <Button Id="Sample.Grid.opportunity.CustomTab.SecondGroup.SecondButton" ToolTipTitle="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.SecondButton.LabelText" ToolTipDescription="$LocLabels:Sample.opportunity.CustomTab.SecondGroup.SecondButton.ToolTipDescription" Command="Sample.Grid.opportunity.SecondGroup.SecondButton" Sequence="20" LabelText="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.SecondButton.LabelText" Alt="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.SecondButton.LabelText" Image16by16="$webresource:sample_/icons/2Icon16x16.png" Image32by32="$webresource:sample_/icons/2Icon32x32.png" TemplateAlias="o1" />
                      <Button Id="Sample.Grid.opportunity.CustomTab.SecondGroup.ThirdButton" ToolTipTitle="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.ThirdButton.LabelText" ToolTipDescription="$LocLabels:Sample.opportunity.CustomTab.SecondGroup.ThirdButton.ToolTipDescription" Command="Sample.Grid.opportunity.SecondGroup.ThirdButton" Sequence="30" LabelText="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.ThirdButton.LabelText" Alt="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.ThirdButton.LabelText" Image16by16="$webresource:sample_/icons/3Icon16x16.png" Image32by32="$webresource:sample_/icons/3Icon32x32.png" TemplateAlias="o1" />
                    </Controls>
                  </Group>
                  <Group Id ="Sample.Grid.opportunity.CustomTab.ThirdGroup" Command="Sample.Grid.opportunity.SecondGroup" Sequence="20" Title="$LocLabels:Sample.opportunity.CustomTab.ThirdGroup.Title" Template="Mscrm.Templates.3.3">
                    <Controls Id="Sample.Grid.opportunity.CustomTab.ThirdGroup.Controls">
                      <Button Id="Sample.Grid.opportunity.CustomTab.ThirdGroup.FirstButton" ToolTipTitle="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.FirstButton.LabelText" ToolTipDescription="$LocLabels:Sample.opportunity.CustomTab.ThirdGroup.FirstButton.ToolTipDescription" Command="Sample.Grid.opportunity.ThirdGroup.FirstButton" Sequence="10" LabelText="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.FirstButton.LabelText" Alt="$LocLabels:Sample.opportunity.CustomTab.FirstGroup.FirstButton.LabelText" Image16by16="$webresource:sample_/icons/4Icon16x16.png" Image32by32="$webresource:sample_/icons/4Icon32x32.png" TemplateAlias="o1" />
                    </Controls>
                  </Group>
                  
                </Groups>
              </Tab>
            </CommandUIDefinition>
          </CustomAction>

動作の確認

それぞれのグループの表示、ボタンの有効化/無効化、スケーリングが
要件に合致しているか確認してください。

まとめ

今回はカスタムタブの追加サンプル、および今までの復習をかねたチャレンジを
行いました。リボンのカスタマイズは次回のパート 5 が最終回となります。
最終回は、Template 要素を解説します。リボンの見た目を決める上で、最も
重要な要素となりますので、お楽しみに!

- Dynamics CRM サポート中村憲一郎

Dynamics CRM 2011 リボンのカスタマイズ パート 4

Additional resources

Dynamics CRM 2011 リボンのカスタマイズパート 4