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

みなさん、こんにちは。

今回はカスタムグループの追加と、前回紹介しきれなかった要素の
紹介をします。前回の記事をまだご覧になっていない方は、この記事の
前提になっていますので、ご覧ください。

サンプルソリューション

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

sdk\walkthroughs\ribbon\addacustomgrouptoanexistingtabforaspecificentity.zip

取引先担当者のグリッドとフォームにカスタムグループが追加されます。

[取引先担当者のグリッド]
image

[取引先担当者のフォーム]
image

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 化

[通常時はコントロールアイコンのみ]
image

[スペースがない場合に Popup 化してグループアイコンが表示]
image

Sequence : 値として 29 と指定。

ここで既定のリボンを確認してみます。sdk\samplecode\cs\client\ribbon\
exportribbonxml\exportedribbonxml\contactribbon.xml を開きます。
<RibbonDefinitions><RibbonDefinition><UI><Ribbon><Tabs> の子要素と
して、グリッド用とフォーム用のタブの定義があります。

グリッド用タブの定義は以下のようになっていますので、画面と比較してみてください。

image

次にメインタブの定義を展開します。<Tab><Groups> の子要素にグループの定義が
あり、以下のようになっています。こちらも画面と比較してください。

image

このサンプルでは、カスタムグループを共同作業の直前に追加するため
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 を付け足します。

image

また 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 内に上書きし
ソリューションを再度インポートしてください。

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

image

では動作の確認です。

1. 取引先担当者はもともとリボンの要素が多いので、念のため Internet 
Explorer のズームを75% にセットします。サイズは画面右下で変更できます。

image

2. 取引先担当者のグリッドを表示します。以下のように表示されます。
※長いので 2行に分けています。

image
image

3. Internet Explorer の大きさを少しずつ狭くしていきます。するとまず
Sequence が一番大きい以下の定義が反映されます。

<Scale Id="Mscrm.HomepageGrid.contact.MainTab.ExportData.Scale.1" GroupId="Mscrm.HomepageGrid.contact.MainTab.ExportData" Sequence="80" Size="LargeSmallLarge" />

ここでの LargeSmallLarge では、大きいアイコンは大きいままで、小さい
アイコンの文字を省略という意味になっていますので、データ領域が以下の
用に変更されます。

image

4. さらに小さくしていくと、 Sequence が 85 のサンプルの定義が反映され、
カスタムグループが以下のように Popup 表示に変わります。

image

5. さらに横幅を狭くして、contactribbon.xml の定義どおり表示が変更されるか
確認します。最後は以下のように、全て Popup になります。

image

ルールの編集と動作の確認

では、サンプルを少しカスタマイズしてみましょう。

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 化された段階で、以下の
ようにアイコンの大きさが変わります。

image

5. さらに幅を小さくしていくと、既存のグループは Popup 化していきますが、以下の
ようにカスタムグループは最後まで Popup 化しません。

image

6. さらに狭めると、全てのグループが Popup 化します。

image

まとめ

グループの追加には、前回のコントロールの追加の要素以外にも、MaxSize と Scale
要素が CustomAction として必要であることを説明しました。また MaxSize と Scale の
Sequence の意味についても説明を行いました。

グループの表示場所を変更したり、Scale の順番を変更する等、いろいろ試してください。

次回はカスタムタブのサンプルを紹介します。
お楽しみに!

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