Dynamics CRM 2011 リボンのカスタマイズ パート 3
みなさん、こんにちは。
今回はカスタムグループの追加と、前回紹介しきれなかった要素の
紹介をします。前回の記事をまだご覧になっていない方は、この記事の
前提になっていますので、ご覧ください。
サンプルソリューション
まずは以下のフォルダにあるソリューションを、Dynamics CRM 2011 に
インポートしてください。
sdk\walkthroughs\ribbon\addacustomgrouptoanexistingtabforaspecificentity.zip
取引先担当者のグリッドとフォームにカスタムグループが追加されます。
RibbonDiffXml の構成
今回もまず customizations.xml ファイルを見ていきます。
LocLabels 要素
前回同様英語のラベルしか定義されていませんので、対応する
日本語を追加します。
<LocLabels>
<LocLabel Id="Sample.contact.CustomGroup.Button.C.Description">
<Titles>
<Title languagecode="1033" description="Button C Description" />
<Title languagecode="1041" description="ボタン C の説明"/>
</Titles>
</LocLabel>
<LocLabel Id="Sample.contact.CustomGroup.Button.C.LabelText">
<Titles>
<Title languagecode="1033" description="Button C Label" />
<Title languagecode="1041" description="ボタン C"/>
</Titles>
</LocLabel>
<LocLabel Id="Sample.contact.CustomGroup.Button.A.Description">
<Titles>
<Title languagecode="1033" description="Button A Description" />
<Title languagecode="1041" description="ボタン A の説明"/>
</Titles>
</LocLabel>
<LocLabel Id="Sample.contact.CustomGroup.Button.B.Description">
<Titles>
<Title languagecode="1033" description="Button B Description" />
<Title languagecode="1041" description="ボタン B の説明"/>
</Titles>
</LocLabel>
<LocLabel Id="Sample.contact.CustomGroup.Button.B.LabelText">
<Titles>
<Title languagecode="1033" description="Button B Label" />
<Title languagecode="1041" description="ボタン B"/>
</Titles>
</LocLabel>
<LocLabel Id="Sample.contact.CustomGroup.Button.A.LabelText">
<Titles>
<Title languagecode="1033" description="Button A Label" />
<Title languagecode="1041" description="ボタン A"/>
</Titles>
</LocLabel>
<LocLabel Id="Sample.contact.CustomGroup.Title">
<Titles>
<Title languagecode="1033" description="Custom Group" />
<Title languagecode="1041" description="カスタムグループ"/>
</Titles>
</LocLabel>
</LocLabels>
RuleDefinitions 要素
DisplayRule, EnableRule ともに前回と同じため、説明は省略します。
CommandDefinitions 要素
5 つの CommandDefinition が定義されています。ボタン用のものは
Action だけが指定されており、EnableRule、DisplayRule は設定していません。
これは、グループの表示と有効化にあわせて動作させるため不要だからです。
Action には WebResource 上の JScript が指定されていますが、前回
から一歩進んで、関数に引数として文字をを渡すよう設定されています。
<CommandDefinition Id="Sample.contact.CustomGroup.Button.A.Command">
<EnableRules />
<DisplayRules />
<Actions>
<JavaScriptFunction Library="$webresource:sample_ShowMessage.js" FunctionName="show">
<StringParameter Value="A" />
</JavaScriptFunction>
</Actions>
</CommandDefinition>
実際の関数では、引数として受け取った文字を使って処理を実施します。
function show(letter)
{
alert("Button "+letter+" action performed.");
}
一方でグループ用の CommandDefinition には Action が設定されて
いません。これはグループ自体は実行するアクションがないためです。また
グリッド用とフォーム用に分けて設定を行っています。
CustomActions 要素
CustomActions 要素は前回とは内容がかなり異なります。グループを追加する
場合には、以下の 3 種類の CustomAction 要素グループを定義します。
- Group 定義 : カスタムグループの場所やコントロールの詳細
- Maxsize 定義 : リボン領域に十分な空きがある場合の表示の定義
- Scale 定義 : リボン領域に十分な空きがない場合に採用される、表示の定義
今回のサンプルでは、グリッド用、フォーム用にそれぞれ定義がありますが、
ここではグリッドのサンプルをピックアップして見て行きます。
Group 用定義
まずはグループの定義およびグループが持つコントロールの定義から行います。
今回の場合は、ボタンA、B、C の 3 つのコントロールがグループに入りますので
グリッド用には以下のように定義されています。
<CustomAction Id="Sample.contact.grid.CustomGroup.CustomAction" Location="Mscrm.HomepageGrid.contact.MainTab.Groups._children" Sequence="140">
<CommandUIDefinition>
<Group Id="Sample.contact.grid.CustomGroup.Group" Command="Sample.contact.grid.CustomGroup.Command" Title="$LocLabels:Sample.contact.CustomGroup.Title" Sequence="29" Template="Mscrm.Templates.Flexible2" Image32by32Popup="$webresource:sample_/icons/TIcon32x32.png">
<Controls Id="Sample.contact.grid.CustomGroup.Controls">
<Button Id="Sample.contact.grid.CustomGroup.Button.A" …省略… />
<Button Id="Sample.contact.grid.CustomGroup.Button.B" …省略… />
<Button Id="Sample.contact.grid.CustomGroup.Button.C" …省略… />
</Controls>
</Group>
</CommandUIDefinition>
</CustomAction>
[CustomAction 要素]
グループをエンティティのメインタブに新規追加するため Location 属性には
Mscrm.HomepageGrid.contact.MainTab.Groups._children が指定されています。
[Group 要素]
CommandUIDefinition の子要素として、Group 要素が追加されています。Group の
属性は以下の通りです。
ID : 一意の ID を作成。
Title : LocLabels のものを指定。
Command : Action を指定しなかったグループ用のものを指定。
Image32by32Popup : Web リソースを指定。グループ用のアイコンは、リボンの
表示領域が狭くなり、コントロールが表示できなくなった際に利用されます。
※ Popup 化
[スペースがない場合に Popup 化してグループアイコンが表示]
Sequence : 値として 29 と指定。
ここで既定のリボンを確認してみます。sdk\samplecode\cs\client\ribbon\
exportribbonxml\exportedribbonxml\contactribbon.xml を開きます。
<RibbonDefinitions><RibbonDefinition><UI><Ribbon><Tabs> の子要素と
して、グリッド用とフォーム用のタブの定義があります。
グリッド用タブの定義は以下のようになっていますので、画面と比較してみてください。
次にメインタブの定義を展開します。<Tab><Groups> の子要素にグループの定義が
あり、以下のようになっています。こちらも画面と比較してください。
このサンプルでは、カスタムグループを共同作業の直前に追加するため
Mscrm.HomepageGrid.contact.MainTab.Collaborate グループにある
Sequence="30" と基準に、Sequence="29" としてしています。もし共同作業
とプロセスに間に移したい場合には、31 から 39 の間の数字を指定します。
Template : Mscrm.Templates.Flexible2 を指定。テンプレートに関しては
今後の回で詳細を紹介します。
[Controls 要素と子要素]
グループは複数のコントロールを持つため、まず Controls 要素を追加します。
属性は一意となる ID のみです。その子要素として、実際のコントロールを追加
します。今回は Button 要素が 3 つです。
ボタンの表示順序は、ここの定義順ではなく、 Sequence 属性値で決定します。
Template 属性は、リボンの表示領域が少なくなった場合の動作を指定しますが
詳細は次回以降で紹介します。
MaxSize 用定義
次に MaxSize 用の CustomAction です。
<CustomAction Id="Sample.contact.grid.CustomGroup.MaxSize.CustomAction" Location="Mscrm.HomepageGrid.contact.MainTab.Scaling._children" Sequence="150">
<CommandUIDefinition>
<MaxSize Id="Sample.contact.grid.CustomGroup.MaxSize" GroupId="Sample.contact.grid.CustomGroup.Group" Sequence="21" Size="LargeLarge" />
</CommandUIDefinition>
</CustomAction>
[CustomAction 要素]
Location 属性には Mscrm.HomepageGrid.contact.MainTab.Scaling._children
が指定されています。Group と同じように、既定のリボン定義から Scaling 要素の
場所を特定し、新規で追加するという意味の _children を付け足します。
また Sequence には150 が指定されていますが、先ほど指定した Group 用の
ものより大きい数字となっているだけです。
[MaxSize 要素]
MaxSize の属性は以下の通りです。
ID : 一意となる ID を作成。
GroupId : 紐付く Group ID を指定。
Sequence : 既存の MaxSize 要素と重複しない値かつ、Scale 要素より大きい数字。
contactribbon.xml の Scaling 要素を確認すると、MaxSize のSequence は
10、20、30、40、50、60、61、また Scale の Sequence は 80 以降。ここでは
21 を指定。
Size : Template に存在する Layout.Title より指定。Template の詳細は次回以降で
解説します。ここでは LargeLarge を指定。
Scale 用定義
次に Scale 用の CustomAction です。Scale 定義ではリボンに十分な空きがない
場合のグループの表示方法を複数指定することができます。複数指定する場合には、
表示領域がより多く必要なものから、より少ない領域で表示できるものの順に
Scale 要素のSequence を割り当てます。
<CustomAction Id="Sample.contact.grid.CustomGroup.Popup.CustomAction" Location="Mscrm.HomepageGrid.contact.MainTab.Scaling._children" Sequence="160">
<CommandUIDefinition>
<Scale Id="Sample.contact.grid.CustomGroup.Popup.1" GroupId="Sample.contact.grid.CustomGroup.Group" Sequence="85" Size="Popup" />
</CommandUIDefinition>
</CustomAction>
[CustomAction 要素]
Location 属性には Mscrm.HomepageGrid.contact.MainTab.Scaling._children
が指定されています。場所は MaxSize と同じです。
また Sequence には160 が指定されていますが、先ほど指定した MaxSize 用の
ものより大きい数字となっているだけです。
[Scale 要素]
以下の属性を指定します。
ID : 一意となる ID を作成。
GroupID : 紐付く Group ID を指定。
Sequence : MaxSize の最大値より大きい数字。リボンに空きがなくなった場合、
この数字の小さい定義から利用されていく。contact.xml を見ると、
80、100、110、120、130、140、150、160、170 が既に定義されており
ここでは 85 を定義しているため、2 番目に適用される。
Size : Template に存在する Layout.Title より指定。Template の詳細は次回以降で
解説します。ここでは最小の単位である Popup を指定。
サンプルの更新と動作の確認
日本語のラベルを追加したので、編集した customizations.xml を保存してから、
addacustomgrouptoanexistingtabforaspecificentity.zip 内に上書きし
ソリューションを再度インポートしてください。
表示が以下のように変わっていれば編集成功です。
では動作の確認です。
1. 取引先担当者はもともとリボンの要素が多いので、念のため Internet
Explorer のズームを75% にセットします。サイズは画面右下で変更できます。
2. 取引先担当者のグリッドを表示します。以下のように表示されます。
※長いので 2行に分けています。
3. Internet Explorer の大きさを少しずつ狭くしていきます。するとまず
Sequence が一番大きい以下の定義が反映されます。
<Scale Id="Mscrm.HomepageGrid.contact.MainTab.ExportData.Scale.1" GroupId="Mscrm.HomepageGrid.contact.MainTab.ExportData" Sequence="80" Size="LargeSmallLarge" />
ここでの LargeSmallLarge では、大きいアイコンは大きいままで、小さい
アイコンの文字を省略という意味になっていますので、データ領域が以下の
用に変更されます。
4. さらに小さくしていくと、 Sequence が 85 のサンプルの定義が反映され、
カスタムグループが以下のように Popup 表示に変わります。
5. さらに横幅を狭くして、contactribbon.xml の定義どおり表示が変更されるか
確認します。最後は以下のように、全て Popup になります。
ルールの編集と動作の確認
では、サンプルを少しカスタマイズしてみましょう。
1. 以下のように既存の Scale の Size を MediumMedium に変更して、はじめて
スケーリングされる際の表示方法を変更します。また Scale 要素の Id 名を変更して
Sample.contact.grid.CustomGroup.MediumMedium.1 にしてみました。
<CustomAction Id="Sample.contact.grid.CustomGroup.Popup.CustomAction" Location="Mscrm.HomepageGrid.contact.MainTab.Scaling._children" Sequence="160">
<CommandUIDefinition>
<Scale Id="Sample.contact.grid.CustomGroup.MediumMedium.1" GroupId="Sample.contact.grid.CustomGroup.Group" Sequence="85" Size="MediumMedium" />
</CommandUIDefinition>
</CustomAction>
2. 以下のように、新規の Scale 定義を追加します。CustomAction Id は 最後に 2 を
つけて一意性を保ち、Sequence は先ほどより大きい 170 にします。 Scale 要素では
Sequence を 180 にして最後に呼び込まれるようにし、Size は Popup を指定します。
Id はもともとあったものを再利用しました。
<CustomAction Id="Sample.contact.grid.CustomGroup.Popup.CustomAction2" Location="Mscrm.HomepageGrid.contact.MainTab.Scaling._children" Sequence="170">
<CommandUIDefinition>
<Scale Id="Sample.contact.grid.CustomGroup.Popup.1" GroupId="Sample.contact.grid.CustomGroup.Group" Sequence="180" Size="Popup" />
</CommandUIDefinition>
</CustomAction>
上記の変更により、MaxSize は LargeLarge、その後第一段階として MediumMedium
最終段階として Popup に動作が変わります。またカスタムグループの Popup 化は
他のすべてのグループが Popup 化した後となります。
1. 編集した customizations.xml を保存してから、ソリューションファイル内に
上書きし ソリューションを再度インポートしてください。
2. ワークプレース | 取引先担当者グリッドを開きます。
3. 最初の状態と、徐々に幅を狭めた結果の第一段階までは、先ほどと同じ結果です。
4. さらに幅を狭くすると、先ほどカスタムグループが Popup 化された段階で、以下の
ようにアイコンの大きさが変わります。
5. さらに幅を小さくしていくと、既存のグループは Popup 化していきますが、以下の
ようにカスタムグループは最後まで Popup 化しません。
6. さらに狭めると、全てのグループが Popup 化します。
まとめ
グループの追加には、前回のコントロールの追加の要素以外にも、MaxSize と Scale
要素が CustomAction として必要であることを説明しました。また MaxSize と Scale の
Sequence の意味についても説明を行いました。
グループの表示場所を変更したり、Scale の順番を変更する等、いろいろ試してください。
次回はカスタムタブのサンプルを紹介します。
お楽しみに!
- Dynamics CRM サポート 中村 憲一郎