Кастомизация
24
Ноя
2

Настройка Ленты

Сначала немножко общей теории…

Общая теория

Лента бывает двух видов:

  • Главная Лента – Лента, которая видна в основном окне CRM.
    Чтобы увидеть ее определение XML нужно выгрузить из CRM «Ленту приложения».
  • Лента объекта – Лента, отображаемая на карточке какого-либо объекта.
    Чтобы отредактировать ленту объекта, необходимо выгрузить соответствующий объект из CRM.

Лучше всего каждый тип Ленты выделить в отдельное Решение, т.е. для «Ленты приложения» и каждого используемого объекта создать свое Решение, чтобы не запутаться в XML-разметке. И уже каждое такое Решение выгружать из CRM.

При этом нужно понимать, что выгруженное определение Ленты (любого типа) не будет содержать ее полного определения. В XML файле будет представлены только те изменения, которые были добавлены к Ленте относительно ее изначального состояния (которое было создано при установке).

Но при настройке Ленты Вам обязательно понадобится смотреть на ее полное XML-определение. Есть два способа это сделать:

  1. Воспользоваться программой ExportRibbonXml.exe, которая поставляется вместе с последним SDK (пример ее использования смотрите в следующем посте);
  2. Вы можете программно экспортировать Ленту определенного объекта с помощью сообщения RetrieveEntityRibbonRequest.

Верхнеуровнево полное определение Лениты выглядит так:

<RibbonDefinitions>
  <RibbonDefinition>
    <UI>...</UI>
    <Templates>...</Templates>
    <CommandDefinitons>...</CommandDefinitons>
    <RuleDefinitions>...</RuleDefinitions>
  </RibbonDefinition>
</RibbonDefinitions>

Состоит полное определение Ленты из четырех разделов:

  1. UI: раздел UI содержит определение всех вкладок, групп и кнопок.
    Иерархия раздела UI: Вкладки -> Группы -> Элементы управления (различные кнопки).


    В целом раздел UI является довольно простым, но есть несколько вещей, на которые стоит обратить внимание:

    • Есть несколько различных типов вкладок: HomepageGrid, Form и SubGrid. Из названий понятно для чего они предназначены;
    • У каждой кнопки есть порядковый номер (Sequence) и TemplateAlias. Они определяют порядок следования и размер кнопок на Ленте, соответственно;
    • В каждой Вкладке в дополнение к набору Групп есть раздел «Scaling». Этот раздел определяет, как Группа ведет себя, если на экране не достаточно места для полного отображения всех ее элементов.
  2. Templates: шаблоны, которые определяют визуальное отображение (или макет) Групп, а именно:
    • Размеры кнопок и элементов управления на Ленте;
    • Взаимное расположение элементов управления;
    • Как элементы управления сворачиваются при уменьшении размеров окна.
  3. CommandDefinitons: определяет то, что делают кнопки (какие действия выполняются при нажатии).
    <Button Id="Mscrm.HomepageGrid.account.NewRecord" 
            ToolTipTitle="$Resources:Ribbon.HomepageGrid.MainTab.New" 
            ToolTipDescription="$Resources(EntityDisplayName):Ribbon.Tooltip.New" 
            Command="Mscrm.NewRecordFromGrid" 
            Sequence="10" 
            LabelText="$Resources:Ribbon.HomepageGrid.MainTab.New" 
            Alt="$Resources:Ribbon.HomepageGrid.MainTab.New" 
            Image16by16="/_imgs/ribbon/NewRecord_16.png" 
            Image32by32="/_imgs/ribbon/newrecord32.png" 
            TemplateAlias="o1" />
    
    ...
    
    <CommandDefinition Id="Mscrm.NewRecordFromGrid">
      <EnableRules />
      <DisplayRules>
        <DisplayRule Id="Mscrm.CreateSelectedEntityPermission" />
        <DisplayRule Id="Mscrm.ShowForNonRelationshipBoundGrids" />
        <DisplayRule Id="Mscrm.PrimaryIsNotActivity" />
        <DisplayRule Id="Mscrm.HideNewForChildEntities" />
        <DisplayRule Id="Mscrm.HideAddressEntities" />
      </DisplayRules>
      <Actions>
        <JavaScriptFunction FunctionName="openObj" Library="/_common/global.ashx">
          <CrmParameter Value="SelectedEntityTypeCode" />
        </JavaScriptFunction>
      </Actions>
    </CommandDefinition>
    

    Если Вы посмотрите на поредение кнопки в разделе UI, то заметите, что у них есть атрибут «Command». Этот атрибут с помощью ID ссылается на определение команды в разделе CommandDefinition. По сути CommandDefinition это способ группировки отдельных правил определенных в RuleDefinitions. Соответственно все правила, на которые ссылается CommandDefinition выполняются одновременно (например, при нажатии кнопки).
    CommandDefinition содержит следующие узлы:

    • Actions – определяет, что происходит при нажатии кнопки. Actions может содержать либо вызов функции Javascript, либо открывать URL;
    • DisplayRules – ссылки на правила DisplayRule из RuleDefinitions;
    • EnableRules – ссылки на правила EnableRuleиз RuleDefinitions.
  4. RuleDefinitions: содержит определения правил отображения/скрытия и активации/деактивации элементов на Ленте.
    EnableRules и DisplayRules в RuleDefinitions определяют отдельные (сами по себе) правила, на которые будут ссылкаться различные CommandDefinition. Правила, которые Вы видите в CommandDefinition, являются только указателями на фактическое определения этих правил в разделе RuleDefinitions:

    <CommandDefinition Id="Mscrm.NewRecordFromGrid">
      <EnableRules />
      <DisplayRules>
        <DisplayRule Id="Mscrm.CreateSelectedEntityPermission" />
        <DisplayRule Id="Mscrm.ShowForNonRelationshipBoundGrids" />
        <DisplayRule Id="Mscrm.PrimaryIsNotActivity" />
        <DisplayRule Id="Mscrm.HideNewForChildEntities" />
        <DisplayRule Id="Mscrm.HideAddressEntities" />
      </DisplayRules>
      <Actions>
        <JavaScriptFunction FunctionName="openObj" Library="/_common/global.ashx">
          <CrmParameter Value="SelectedEntityTypeCode" />
        </JavaScriptFunction>
      </Actions>
    </CommandDefinition>
    
    ...
    
    <RuleDefinitions>
      <DisplayRules>
        ...
        <DisplayRule Id="Mscrm.CreateSelectedEntityPermission">
          <EntityPrivilegeRule AppliesTo="SelectedEntity" PrivilegeType="Create" PrivilegeDepth="Basic" />
        </DisplayRule>
        ...
      </DisplayRule>
    </DisplayRules>
    

    Есть много различных видов правил, которые могут использоваться в EnableRule или DisplayRule, позволяя Вам создавать сложные условия отображения и деактивации элементов упаравления.

Но так как редактирование полного определения Ленты нам не доступно перейдём к более практической части – редактированию «добавочного» определения Ленты…

Добавочный Ribbon XML

XML определение выгружаемое для Ленты или какого-либо объекта состоит из следующих элементов:

<RibbonDiffXml>
  <CustomActions>
    ...
  </CustomActions>
  <Templates>
    ...
  </Templates>
  <CommandDefinitions>
    ...
  </CommandDefinitions>
  <RuleDefinitions>
    ...
  </RuleDefinitions>
  <LocLabels>
    ...
  </LocLabels>
</RibbonDiffXml>

Рассмотрим предназначение каждого из разделов…

1. CustomActions

CustomActions содержит коллекцию «действий», которые добавляют, изменяют или удаляют элементы с Ленты. Может содержать один из двух элементов:

1.1 CustomAction

<CustomActions>
  <CustomAction
    Id="String"
    Location="String"
    Sequence="Integer"
    Title="String"
  >
    <CommandUIDefinition>
      <Button/>
      <CheckBox/>
      <ComboBox/>
      <ColorPicker/>
      <ContextualGroup/>
      <Controls/>
      <DropDown/>
      <FlyoutAnchor/>
      <Gallery/>
      <GalleryButton/>
      <GroupTemplate/>
      <Group/>
      <Groups/>
      <InsertTable/>
      <Label/>
      <MRUSplitButton/>
      <MaxSize/>
      <Menu/>
      <MenuSection/>
      <Scale/>
      <Scaling/>
      <Spinner/>
      <SplitButton/>
      <Tab/>
      <TextBox/>
      <ToggleButton/>
    </CommandUIDefinition>
  </CustomAction>
  <HideCustomAction/>
</CustomActions>

CustomAction добавляет или заменяет элемент на Ленте. Имеет следующие параметры:

  • Id: Уникальный идентификатор.

Рекомендуемое соглашение о присвоении имен: [solution identifier].[entity].[ribbon].[function].[element name]. Например: MyISV.account.form.SendToOtherSystem.Button;

  • Location: ссылка на ID элемента Ленты, в котором могут распологаться другие элементы (например Группа) + суффикс «._children»;
  • Sequence: порядок расположения элементов.

Внутри CustomAction содержится контейнер CommandUIDefinition , который в свою очередь и включает элементы управления, отображаемые на Ленте. CommandUIDefinition может содержать один из следующих элементов:

GroupTemplate Набор макетов, которые может использовать Группа при изменении ширины Ленты.
ContextualGroup Набор Вкладок, которыми необходимо синхронно управлять (отображать, дизейблить и т.д.)
Tab Вкладка на Ленте.
Groups Коллекция Групп
Group Группа на Вкладке
Menu Определяет контейнер, используемый для показа раскрывающиеся меню.
MenuSection Определяет секцию, используемую для разделения меню на секции. Меню может иметь заголовок и содержать элементы управления.
Controls Коллекция каких-либо элементов управления. Используется во многих других элементах управления.
Scale Определяет одну из возможных разметок, которая может использоваться Группой для визуализации своих элементов, когда они не помещаются на экране.
MaxSize Специальный элемент Scaling (Масштабирование), который определяет самый большой Layout возможный Группы.
SplitButton Элемент управление, используемое и в качестве кнопки и в качестве меню. Визульно это кнопка со стрелкой вниз по нажатию, на которую открывается ниспадающий список. В отличие от FlyoutAnchor, щелкнуть можно как на пункте ниспадающего мнею, так и на кнопке.
MRUSplitButton SplitButton (см. ниже), который отображает элементы Most Recently Used.
TextBox Текстовое поле для ввода текста.
InsertTable Сетка 10 на 10, используемая для определения размеров таблицы. Например, используется в Word для вставки таблицы.
Label Строка текста
Spinner Элемент управления для ввода значений либо с помощью клавиатуры, либо с помощью кнопок-стрелок (вверх/вниз), которые добавляют/убавляют текущее значение на определенную велечину.
Button Простая кнопка
CheckBox Галка
ComboBox Список значений, из которого Вы можете выбрать одно. При этом значения можно также выбирать путем вводо одного из них в текстовое поле.
ColorPicker Типичный контрол для выбора цветового значения или стиля. Нафига нужен в CRM – не понятно… 🙂
DropDown Типичный ниспадающий список. От ComboBox’а отличается тем, что в нем нельзя вводить значения – только выбирать из списка!
FlyoutAnchor Кнопку со стрелкой вниз. По нажатию на кнопку или стрелку, раскрыввается ниспадающий список, по одному из значений которого Вы можете щелкнуть.
Gallery Контрол, представляющий собой кнопку, по нажатию на которую раскрывается большое меню, содержащее множество других кнопок (могут быть очень больших размеров).
GalleryButton Кнопка для Галереи.
ToggleButton Кнопка-переключатель между двумя состояниями.

1.2 HideCustomAction

Каждый HideCustomAction удаляет один существующие элемент с Ленты:

<CustomActions>
  <HideCustomAction
    HideActionId="String"
    Location="String"
    Sequence="Integer"
  />
</CustomActions>

HideCustomAction имеет следующие параметры:

  • HideActionId: уникальный идентификатор;
  • Location: ID элемента подлежащего скрытию;
  • Sequence: определяет порядок расположения элемента на Ленте.

2. Шаблоны

Прежде чем переходить переходить к созданию новых Шаблонов, рассмотрим сухую теорию…

2.1 Теория

2.1.1 Определение Макетов

Шаблоны используются для определения того, как группы элементов управления распологаются на Ленте. Используемый шаблон определит порядок и размер кнопок. Шаблон также определяет, как группа уменьшается, когда нет достаточного пространства на странице для отображения полной Ленты.

В большинстве случаев Вам не потребуется беспокоиться о шаблонах (достаточно у кнопок установить атрибут TemplateAlias = «isv» и все). Однако, если Вы создаете новую Группу или новую Вкладку, то тогда Вам стоит знать как работают Шаблоны.

Во-первых, у кнопок есть атрибут TemplateAlias:

<Button Id="Mscrm.HomepageGrid.account.NewRecord"
        ToolTipTitle="$Resources:Ribbon.HomepageGrid.MainTab.New"
        ToolTipDescription="$Resources(EntityDisplayName):Ribbon.Tooltip.New"
        Command="Mscrm.NewRecordFromGrid"
        Sequence="10"
        LabelText="$Resources:Ribbon.HomepageGrid.MainTab.New"
        Alt="$Resources:Ribbon.HomepageGrid.MainTab.New"
        Image16by16="/_imgs/ribbon/NewRecord_16.png"
        Image32by32="/_imgs/ribbon/newrecord32.png"
        TemplateAlias="o1" />

Во-вторых у каждой Группы есть атрибут Template:

<Group Id="Mscrm.HomepageGrid.account.MainTab.Management" 
       Command="Mscrm.Enabled" 
       Sequence="10" 
       Title="$Resources:Ribbon.HomepageGrid.MainTab.Management" 
       Description="$Resources:Ribbon.HomepageGrid.MainTab.Management" 
       Image32by32Popup="/_imgs/ribbon/newrecord32.png" 
       Template="Mscrm.Templates.FourOverflow">

Если Вы посмотрите узел Templates, то найдете отдельные Шаблоны (Template), который используются Группами. Каждый Шаблон имеет много Макетов (Layout) с такими именами как «LargeMedium» или «LargeSmall». Один из этих Макетов будет использоваться, чтобы определить расположение элементов управления в Группе.

<GroupTemplate Id="Mscrm.Templates.FourOverflow">
  <Layout Title="LargeMediumLargeLarge">
    <OverflowSection Type="OneRow" TemplateAlias="o5" DisplayMode="Large" />
    <OverflowSection Type="ThreeRow" TemplateAlias="o6" DisplayMode="Medium" />
    <OverflowSection Type="OneRow" TemplateAlias="o7" DisplayMode="Large" />
    <OverflowSection Type="ThreeRow" TemplateAlias="o8" DisplayMode="Medium" />
    <OverflowSection Type="OneRow" TemplateAlias="o1" DisplayMode="Large" />
    <OverflowSection Type="ThreeRow" TemplateAlias="o2" DisplayMode="Medium" />
    <OverflowSection Type="OneRow" TemplateAlias="o3" DisplayMode="Large" />
    <OverflowSection Type="OneRow" TemplateAlias="o4" DisplayMode="Large" />
    <OverflowSection Type="OneRow" TemplateAlias="isv" DisplayMode="Large" />
  </Layout>
  <Layout Title="LargeMediumLargeMedium">
    <OverflowSection Type="OneRow" TemplateAlias="o5" DisplayMode="Large" />
    <OverflowSection Type="ThreeRow" TemplateAlias="o6" DisplayMode="Medium" />
    <OverflowSection Type="OneRow" TemplateAlias="o7" DisplayMode="Large" />
    <OverflowSection Type="ThreeRow" TemplateAlias="o8" DisplayMode="Medium" />
    <OverflowSection Type="OneRow" TemplateAlias="o1" DisplayMode="Large" />
    <OverflowSection Type="ThreeRow" TemplateAlias="o2" DisplayMode="Medium" />
    <OverflowSection Type="OneRow" TemplateAlias="o3" DisplayMode="Large" />
    <OverflowSection Type="ThreeRow" TemplateAlias="o4" DisplayMode="Medium" />
    <OverflowSection Type="ThreeRow" TemplateAlias="isv" DisplayMode="Medium" />
  </Layout>
  <Layout Title="Popup" LayoutTitle="LargeMediumLargeMedium" />
</GroupTemplate>

В каждом Макете есть два способа, которыми может быть определено расположение кнопок и элементов управления…

OverflowSections

Наиболее распространенный способ заключается в использовании OverflowSections. Каждый OverflowSection будет расположен в Группе горизонтально слева направо, и будет содержать все кнопки, у которых есть соответствующий TemplateAlias. На скрине ниже показана Группа «Совместная работа», которая использует расположение «LargeMedium» шаблона «Flexible2»:


На изображении выше, все кнопки, которые использут TemplateAlias = o1 размещаются перед кнопками с TemplateAlias = o2, независимо от их порядкового (sequence) номера. Но элементы управления с одним и тем же TemplateAlias, будут упорядочены в OverflowSection в соответствии с их порядковым номером в пределах своего TemplateAlias.
У OverflowSection с типом «OneRow» будет одна единственная строка кнопок, в то время как у типа «ThreeRow» будет три ряда кнопок расположенными друг над другом. DisplayMode определяет размер кнопки в OverflowSection. Есть три размера: Large, Medium и Small.

Заметьте, что у всех стандартных Шаблонов есть «isv» TemplateAlias. Это таким образом разработчики CRM позаботились, чтобы можно было легко добавить кнопки к любой Группе, не беспокоясь о Шаблонах и Макетах. Если Вы всегда будете использовать TemplateAlias = isv, то Ваши кнопки всегда будут распологаться в конце Группы, не затрагивая при этом стандартные элементы управления.

Sections

Другой способ определить Макет состоит в использовании Секций (Section) и Строк (Row). Секции и Строки позволяют задавать расположение элементов управления в Шаблоне с большей точностью, чем с помощью OverflowSections. Каждый элемент управление в Группе помещен в определенную Секцию и определенную Строку. Например, Группа Действие на Вкладке Добавление использует Секции и Строки, чтобы получить точное определение расположения элементов управления:

<GroupTemplate Id="Mscrm.Templates.Activities">
  <Layout Title="MaxSize">
    <Section Type="OneRow">
      <Row>
        <ControlRef TemplateAlias="c1" DisplayMode="Large" />
      </Row>
    </Section>
    <Section Type="OneRow">
      <Row>
        <ControlRef TemplateAlias="c2" DisplayMode="Large" />
      </Row>
    </Section>
    <Section Type="ThreeRow">
      <Row>
        <ControlRef TemplateAlias="c3" DisplayMode="Medium" />
      </Row>
      <Row>
        <ControlRef TemplateAlias="c4" DisplayMode="Medium" />
      </Row>
      <Row>
        <ControlRef TemplateAlias="c5" DisplayMode="Medium" />
      </Row>
    </Section>
    <Section Type="OneRow">
      <Row>
        <ControlRef TemplateAlias="c6" DisplayMode="Large" />
      </Row>
    </Section>
    <Section Type="ThreeRow">
      <Row>
        <ControlRef TemplateAlias="c7" DisplayMode="Medium" />
      </Row>
      <Row>
        <ControlRef TemplateAlias="c8" DisplayMode="Medium" />
      </Row>
      <Row>
        <ControlRef TemplateAlias="c9" DisplayMode="Medium" />
      </Row>
    </Section>
    <Section Type="OneRow">
      <Row>
        <ControlRef TemplateAlias="c10" DisplayMode="Large" />
      </Row>
    </Section>
    <OverflowSection Type="OneRow" TemplateAlias="o1" DisplayMode="Large" />
    <OverflowSection Type="OneRow" TemplateAlias="isv" DisplayMode="Large" />
  </Layout>
  <Layout Title="Scale.1">...</Layout>
  <Layout Title="Scale.2">...</Layout>
  <Layout Title="Scale.3">...</Layout>
  <Layout Title="Scale.4">...</Layout>
  <Layout Title="Popup" LayoutTitle="MaxSize" />
</GroupTemplate>

Заметьте, что даже с Секциями и Cтроками в этом Макете все еще присутствуют два OverflowSections с TemplateAliases «o1» и «isv». Разделы и Строки предлагают более точное управление расположением элементов управления, но OverflowSections предлагает больше гибкости при добавлении кастомных элементов управления к Группе.
Примечание: элементы управления с TemplateAlias, которые начинаются с «c» использует Секции и Строки. TemplateAlias начинающиеся с «o» использует OverflowSections (c = ConfrolRef, o = overflowSection).

2.1.2 Изменение размеров Ленты

Каждый Шаблон имеет несколько Макетов и каждый из этих Макетов определяет, как Группа будет отображаться на Ленте. При этом макеты могут быть разной визуальной ширины и поэтому разные Макеты можно использовать при различной ширине экрана. Здесь решающую роль играет узел Масштабирование (Scaling) определенный для Группы. Если Вы посмотрите на узел Scaling (в узле Tab), Вы увидите, что он сопоставляет Макеты Группам.

<Tabs Id="Mscrm.Tabs">
  <Tab Id="Mscrm.HomepageGrid.account.MainTab" Command="Mscrm.HomepageGrid.account.MainTab" Title="Accounts" Description="Accounts" Sequence="100">
    <Scaling Id="Mscrm.HomepageGrid.account.MainTab.Scaling">
      <MaxSize Id="Mscrm.HomepageGrid.account.MainTab.Management.MaxSize" GroupId="Mscrm.HomepageGrid.account.MainTab.Management" Sequence="10" Size="LargeMediumLargeMedium" />
      <MaxSize Id="Mscrm.HomepageGrid.account.MainTab.Collaborate.MaxSize" GroupId="Mscrm.HomepageGrid.account.MainTab.Collaborate" Sequence="20" Size="LargeMedium" />
      <MaxSize Id="Mscrm.HomepageGrid.account.MainTab.Actions.MaxSize" GroupId="Mscrm.HomepageGrid.account.MainTab.Actions" Sequence="30" Size="LargeLargeMediumLarge" />
      <MaxSize Id="Mscrm.HomepageGrid.account.MainTab.ExportData.MaxSize" GroupId="Mscrm.HomepageGrid.account.MainTab.ExportData" Sequence="40" Size="LargeMediumLarge" />
      <MaxSize Id="Mscrm.HomepageGrid.account.MainTab.Workflow.MaxSize" GroupId="Mscrm.HomepageGrid.account.MainTab.Workflow" Sequence="50" Size="Large" />
      <MaxSize Id="Mscrm.HomepageGrid.account.MainTab.Find.MaxSize" GroupId="Mscrm.HomepageGrid.account.MainTab.Find" Sequence="60" Size="Large" />
      <MaxSize Id="Mscrm.HomepageGrid.account.MainTab.OutlookHelp.MaxSize" GroupId="Mscrm.HomepageGrid.account.MainTab.OutlookHelp" Sequence="61" Size="Large" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.ExportData.Scale.1" GroupId="Mscrm.HomepageGrid.account.MainTab.ExportData" Sequence="80" Size="LargeSmallLarge" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.Workflow.Scale.2" GroupId="Mscrm.HomepageGrid.account.MainTab.Workflow" Sequence="100" Size="Popup" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.Actions.Scale.1" GroupId="Mscrm.HomepageGrid.account.MainTab.Actions" Sequence="110" Size="LargeMediumMediumLarge" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.Collaborate.Scale.1" GroupId="Mscrm.HomepageGrid.account.MainTab.Collaborate" Sequence="120" Size="LargeSmall" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.Management.Scale.1" GroupId="Mscrm.HomepageGrid.account.MainTab.Management" Sequence="130" Size="LargeMediumLargeMedium" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.ExportData.Scale.3" GroupId="Mscrm.HomepageGrid.account.MainTab.ExportData" Sequence="140" Size="Popup" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.Collaborate.Scale.2" GroupId="Mscrm.HomepageGrid.account.MainTab.Collaborate" Sequence="150" Size="Popup" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.Actions.Scale.2" GroupId="Mscrm.HomepageGrid.account.MainTab.Actions" Sequence="160" Size="Popup" />
      <Scale Id="Mscrm.HomepageGrid.account.MainTab.Management.Scale.2" GroupId="Mscrm.HomepageGrid.account.MainTab.Management" Sequence="170" Size="Popup" />
    </Scaling>
    <Groups Id="Mscrm.HomepageGrid.account.MainTab.Groups">
      <Group Id="Mscrm.HomepageGrid.account.MainTab.Management" Command="Mscrm.Enabled" Sequence="10" Title="$Resources:Ribbon.HomepageGrid.MainTab.Management" Description="$Resources:Ribbon.HomepageGrid.MainTab.Management" Image32by32Popup="/_imgs/ribbon/newrecord32.png" Template="Mscrm.Templates.FourOverflow">
        <Controls Id="Mscrm.HomepageGrid.account.MainTab.Management.Controls">
          ...
        </Controls>
      </Group>
    </Groups>
  </Tab>
</Tabs>

Элемент MaxSize определяет, какой Макет будет использовать Группа при достаточной ширине экрана для ее полного отображения. Если пользователь уменьшит ширину окна, система переключится на следующий по порядку элемент Scale.

Для каждой Вкладки все элементы MaxSize и Scale собраны одном месте – в узле Scaling. Но если посмотреть, например, только на элементы Scales для группы «Collaborate», то можно проследить, как изменяется Макет Группы при уменьшннии горизонтального размера Ленты.


Когда Лента развернута на полную ширину, она использует первый Scale – MaxSize, который ссылается на Макет «LargeMedium». Когда доступная ширина Ленты уменьшается, Группа «перемещается» к следующиму Scale в списке, который ссылается на макет «LargeSmall». Ну и при последующем уменьшении ширины Лента достигает третьего и заключительного Scale, который ссылается на макет «Popup».

Обычно последний Макет в Шаблоне это специальный «Popup». Макет Popup это самый «маленьки» макет, представляющий собой одну кнопку (для которой, кстати, можно определить своию икноку), по нажатию на которую во всплывающем меню появляются кнопки Группы. Атрибут LayoutTitle в этом Макете ссылается на другой Макет, который используется, чтобы расположить элементы управления в раскрывающемся меню.

Примечание:

  • Для новой Группы на Ленте, тогда Вы должны выбрать Шаблон и определить для нее как минимум элемент MaxSize;
  • Если ни один из стандартных Шаблонов не будет Вас удовлетворять, тогда Вы должны будете определить свой собственный Шаблон в RibbonDiffXml (об этом далее).

Далее перейдем к способам создания новых Шаблонов…

2.2 Templates

Содержит коллекцию шаблонов Ленты.

<Templates>
  <RibbonTemplates Id="String">
    <GroupTemplate Id="String" ClassName="String">
      <Layout LayoutTitle="String" Title="String">
        <Section
          Alignment=["Top" | "Middle"]
          Type=["Divider" | "OneRow" | "TwoRow" | "ThreeRow"]>
          <Row>
            <ControlRef
              DisplayMode=["Default" | "Small" | "Medium" | "Large" | "Text" | "Menu" | "Menu16" | "Menu32" | "Thin" ]
              TemplateAlias="String"/>
            <OverflowArea
              DisplayMode=["Default" | "Small" | "Medium" | "Large" | "Text" | "Menu" | "Menu16" | "Menu32" | "Thin"]
              TemplateAlias="String" />
            <Strip>
              <ControlRef
                DisplayMode=["Default" | "Small" | "Medium" | "Large" | "Text" | "Menu" | "Menu16" | "Menu32" | "Thin" ]
                TemplateAlias="String"
              />
            </Strip>
          </Row>
        </Section>
        <OverflowSection
          DisplayMode=["Default" | "Small" | "Medium" | "Large" | "Text" | "Menu" | "Menu16" | "Menu32" | "Thin"]
          DividerAfter=["0" | "1" | "true" | "false"]
          DividerBefore=["0" | "1" | "true" | "false"]
          TemplateAlias="String"
          Type=["Divider" | "OneRow" | "TwoRow" | "ThreeRow"]
        />
      </Layout>
    </GroupTemplate>
  </RibbonTemplates>
</Templates>

Ну, тут в начале мы имеем кучу вложенных элементов:

  • RibbonTemplates: содержит коллекцию групп шаблонов. Единственный параметр – ID;
  • GroupTemplate: определение коллекция макетов, которые Группа может использовать при изменении ширины Ленты. Имеет два параметра:
    • ClassName: Имя CSS класса для применения к группе;
    • Id: Идентификатор элемента.
  • Layout: определяет макет для группы в GroupTemplate. Имеет два атрибута:
    • LayoutTitle: альтернативный идентификатор элемента;
    • Title: не используется в CRM.

А дальше начинается самое интересное:

2.2.1 Section

Содержит коллекцию строк, которые отображаются в Группе:

<Section
  Alignment=["Top" | "Middle"]
  Type=["Divider" | "OneRow" | "TwoRow" | "ThreeRow"]>
  <Row />
</Section>

Имеет два атрибута:

  • Alignment: Выравнивание элементов по вертикали в секции. Допустимые значения:
    • Top: строки выравниваются по верху;
      Middle: строки выравниваются посередине.
  • Type: определяет тип секции. Допустимые значения:
    • Divider: секция действует как разделитель между секциями;
    • OneRow: секция отображает одну строку;
    • TwoRow: секция отображает две строки;
    • ThreeRow: секция отображает три строки.
Row

Определяет строку в пределах секции:

<Row>
  <ControlRef />
  <OverflowArea />
  <Strip />
</Row>

Конкретные позиции и их размеры в перделах одной строки задаются с помощью трех элементов…

ControlRef

Определяет заполнитель для элемента управления в макете.

<ControlRef
 DisplayMode=["Default" | "Small" | "Medium" | "Large" | "Text" | "Menu" | "Menu16" | "Menu32" | "Thin" ]
 TemplateAlias="String"
/>

Имеет два атрибута:

  • DisplayMode: управляет режимом, используемым для отображения элементов:
    • Default: отображает элемент используя режим по умолчанию;
    • Small: отображает элемент в маленьком виде.
    • Medium: отображает элемент в среднем виде.
    • Large: отображает элемент в большом виде.
    • Text: отображает элемент в текстовом виде.
    • Menu: отображает элемент как меню.
    • Menu16: отображает элемент в меню с высотой 16 пикселов.
    • Menu32: отображает элемент в меню с высотой 32 пиксела.
    • Thin: отображает элемент в тонком виде.
  • TemplateAlias: связывает дочерний элемент Ленты из CommandUIDefinition с определенным заполнителем расположения в качестве дочернего в узле Layout. Это значение определяет, где элемент управления отображается в пределах Группы, когда макет меняется.
OverflowArea

Определяет область, где множество элементов управления представлены в виде списка.

<OverflowArea
  DisplayMode=["Default" | "Small" | "Medium" | "Large" | "Text" | "Menu" | "Menu16" | "Menu32" | "Thin"]
  TemplateAlias="String"
/>

Набор атрибутов такой же, как и в ControlRef.

Strip

Представляет собой набор элементов обрамленных тонкой линеей. При этом обрамление заканчивается на последнем элементе не доходя до конца секции. Внутри Strip’а содержатся ControlRef’ы описанные ранее.

<Strip>
  <ControlRef/>
</Strip>

2.2.2 OverflowSection

Определяет набор макетов (Layout), которые позволяют элементам управления изменять относительную позицию в зависимости от свободного места.

<OverflowSection
  DisplayMode=["Default" | "Small" | "Medium" | "Large" | "Text" | "Menu" | "Menu16" | "Menu32" | "Thin"]
  DividerAfter=["0" | "1" | "true" | "false"]
  DividerBefore=["0" | "1" | "true" | "false"]
  TemplateAlias="String"
  Type=["Divider" | "OneRow" | "TwoRow" | "ThreeRow"]
/>

Имеет следующие атрибуты:

  • DisplayMode: управляет режимом, используемым для отображения элементов:
    • Default: отображает элемент используя режим по умолчанию;
    • Small: отображает элемент в маленьком виде.
    • Medium: отображает элемент в среднем виде.
    • Large: отображает элемент в большом виде.
    • Text: отображает элемент в текстовом виде.
    • Menu: отображает элемент как меню.
    • Menu16: отображает элемент в меню с высотой 16 пикселов.
    • Menu32: отображает элемент в меню с высотой 32 пиксела.
    • Thin: отображает элемент в тонком виде.
  • DividerAfter: TRUE рендерит «разделитель» как конец секции;
  • DividerBefore: TRUE рендерит «разделитель» как начало конец секции;
  • TemplateAlias: связывает дочерний элемент Ленты из CommandUIDefinition с определенным заполнителем расположения в качестве дочернего в узле Layout. Это значение определяет, где элемент управления отображается в пределах Группы, когда макет меняется.
  • Type: определяет тип секции. Допустимые значения:
    • Divider: секция действует как разделитель между секциями;
    • OneRow: секция отображает одну строку;
    • TwoRow: секция отображает две строки;
    • ThreeRow: секция отображает три строки.

3. CommandDefinition

Определяет ряд правил, которые управляют тем, как элементы Ленты отображаются и какие действия выполняют. По сути CommandDefinition это группировака отдельных независимых действий, которые описываются в разделе RuleDefenition и на которые происзводится ссылка из CommandDefinition. На CommandDefinition же в свою очередь могут ссылаться элементы управления Ленты. Единственный параметр – ID.

<CommandDefinition Id="String">
  <EnableRules />
  <DisplayRules />
  <Actions />
</CommandDefinition>

CommandDefinition соддержит две коллекции правил:

  • EnableRules;
  • DisplayRules.

В которых сожержаться отдельные EnableRule и DisplayRule, соответственно.

3.1 EnableRule

Определяет одно из двух:

  • Правило которое активируют и деактивируют элементы управления Ленты.
  • Ссылку (с помощью единственного атрибута — ID) на какой-либо EnableRule из RuleDefinitions (в котором уже в свою очередь определено правило активации/деактивации элемента управления Ленты)
<EnableRule Id="String">
  <CrmClientTypeRule />
  <CrmOfflineAccessStateRule />
  <CrmOutlookClientTypeRule />
  <CustomRule />
  <EntityRule />
  <FormStateRule />
  <OrRule />
  <OutlookItemTrackingRule />
  <OutlookVersionRule />
  <PageRule />
  <RecordPrivilegeRule />
  <SelectionCountRule />
  <SkuRule />
  <ValueRule />
</EnableRule>

Правило активации/деактивации может проверять одно из следующи условий (которое задется с помощью вложеных элементов):

Элемент Описание
CrmClientTypeRule Определяет тип клиента CRM.
CrmOfflineAccessStateRule Определяет работает ли CRM клиент Outlook в офлайне.
CrmOutlookClientTypeRule Определяет тип клиента Microsoft Dynamics CRM for Microsoft Office Outlook.
CustomRule Правило используется с правилом EnableRule, которое состоит из ссылки на функцию в библиотеки JS.
EntityRule Определяет объект, в контексте которого происходит действие.
FormStateRule Определяет состояние (state) формы.
OrRule Правило, которое в свою очередь содержит набор других правил. И если среди них хотя бы одно выполняется, то и весь набор выполняется положительно.
OutlookItemTrackingRule Определяет, включено ли для записи отслеживание в Microsoft Dynamics CRM.
OutlookVersionRule Определяет версию клиента Microsoft Office Outlook.
PageRule Определяет адрес текущей страницы.
RecordPrivilegeRule Определяет полномочия пользователя в отношении определенной записи.
SelectionCountRule Определяет сколько элементов в выбрано Представлении.
SkuRule Определяет редакцию CRM.
ValueRule Определяет значение какого-либо поля.

3.2 DisplayRule

Определяет одно из двух:

  • Правила отображения или скрытия элементов на Ленте.
  • Ссылку на какой-либо DisplayRule из RuleDefinitions.
<DisplayRule Id="String">
  <CrmClientTypeRule />
  <CrmOfflineAccessStateRule />
  <CrmOutlookClientTypeRule />
  <CrmOutlookClientVersionRule />
  <EntityPrivilegeRule />
  <EntityPropertyRule />
  <EntityRule />
  <FormEntityContextRule />
  <FormStateRule />
  <MiscellaneousPrivilegeRule />
  <OrganizationSettingRule />
  <OrRule />
  <OutlookRenderTypeRule />
  <OutlookVersionRule />
  <PageRule />
  <ReferencingAttributeRequiredRule />
  <RelationshipTypeRule />
  <SkuRule />
  <ValueRule />
</DisplayRule>

Правило отображения/скрытия может проверять одно из следующи условий (которое задется с помощью вложеных элементов):

Элемент Описание
CrmClientTypeRule Определяет тип клиента CRM.
CrmOfflineAccessStateRule Определяет работает ли CRM клиент Outlook в офлайне.
EntityPrivilegeRule Определяет полномочия текущего пользователя для определенного объекта.
EntityPropertyRule Определяет битовые свойства какого-либо объекта.
EntityRule Определяет объект, в контексте которого происходит действие.
FormEntityContextRule Определяет объект, для которого построена форма.
FormStateRule Определяет состояние (state) формы.
MiscellaneousPrivilegeRule Определяет, обладает ли пользователь определенным полномочием.
OrganizationSettingRule Правило, которое может определить, две заданные настройки организации в DisplayRule.
OrRule Правило, которое в свою очередь содержит набор других правил. И если среди них хотя бы одно выполняется, то и весь набор выполняется положительно.
OutlookRenderTypeRule Определяет, отбражается ли форма или Представление в Outlook нативно или как веб-страница.
OutlookVersionRule Определяет версию клиента Microsoft Office Outlook.
PageRule Определяет адрес текущей страницы.
ReferencingAttributeRequiredRule Определяет, требуется ли ссылка на атрибут для объекта.
RelationshipTypeRule Определяет, существует ли определенный тип связи двумя объектами.
SkuRule Определяет редакцию CRM.
ValueRule Определяет значение какого-либо поля.

3.3 Actions

А Actions содержатся два возможных действия, которые выполняет команда.

3.3.1 JavaScriptFunction

Действие вызывает функцию из JS библиотеки.

<Actions>
  [<JavaScriptFunction /> | <Url />]
</Actions>

Имеет два параметра:

  • FunctionName: Имя JS функции, кооторая будет вызвана. Эта строка должна начаться с буквы, с символа подчеркивание («_») или символ доллара («$»). Остальные символы могут быть любой комбинацией букв, чисел, символа подчеркивания или символа доллара;
  • Library: Имя Веб-ресурса представляющего собой библиотеку JS, который содержит функцию. Используйте директиву «$webresource:» перед именем JS-библиотеки.

В вызываемую функцию могут быть переданы следующие параметры:

Element Description
CrmParameter Данные, полуенные от CRM, которые можно передать в качестве параметра.
BoolParameter Определяет значение булевого типа, который может быть передан в качестве параметра.
DecimalParameter Определяет значение типа decimal, который может быть передан в качестве параметра.
IntParameter Определяет значение целочисленного типа, который может быть передан в качестве параметра.
StringParameter Определяет значение строкового типа, который может быть передан в качестве параметра.

В свою очередь в атрибуте Value элемента CrmParameter можно передать следующие значения:

Значение Описание
CommandProperties Объект с тремя параметрами:

  • SourceControlId: ID элемента Ленты вызвавшего событие (например, ID нажатой кнопки;
  • CommandValueId: Строка, которая будет отправлена с событием команды, когда кнопка будет нажата;
  • MenuItemId: ID элемента меню.
PrimaryEntityTypeCode Код объекта
PrimaryEntityTypeName Имя объекта
PrimaryItemIds Массив строк, состоящий их GUID’ов основного объекта.
FirstPrimaryItemId GUID первой записи основного объекта.
PrimaryControl Объект, который имеет ссылку на элемент управления, который имел фокус при выполнении действия Ленты.
PrimaryControlId ID элемента управления, который имеет сфокус.
SelectedEntityTypeCode Код объекта, отображаемого в Представлении.
SelectedEntityTypeName Название объекта, отображаемого в Представлении.
FirstSelectedItemId GUID первой записи среди выделенных в Представлении.
SelectedControl Объект, который имеет ссылку на элемент управления, который имел фокус при выполнении действия Ленты.
SelectedControlSelectedItemCount Количество записей выбранных в Представлении.
SelectedControlSelectedItemIds Массив GUID’ов записей, выбранных в Представлении.
SelectedControlSelectedItemReferences Массив объектов EntityReference, представляющих все выделенные в Gредставлении записи.

Доступно только при использовании в теге <URL>.

SelectedControlAllItemCount Количество всех записей в представлении.
SelectedControlAllItemIds Массив GUID’ов всех записей, выбранных в Представлении.
SelectedControlAllItemReferences Массив объектов EntityReference, представляющих все записи в Представлении.

Доступно только при использовании в теге <URL>.

SelectedControlUnselectedItemCount Количество записей, с которых снято выделение.
SelectedControlUnselectedItemIds Массив GUID’ов всех записей, с которых снято выделение.
SelectedControlUnselectedItemReferences Массив объектов EntityReference представляющих собой все записи, не выделенные в Представлении.

Эта опция доступна только при использовании в элементе <URL>.

OrgName Название Организации.
OrgLcid Код базового языка организации.
UserLcid Код предпочитаемого пользователем языка.

3.3.2 Url

Действие открывает веб-страницу.

<Url
  Address="String"
  PassParams=["0" | "1" | "true" | "false"]
  WinMode="Integer"
  WinParams="String">
  <BoolParameter/>
  <CrmParameter/>
  <DecimalParameter/>
  <IntParameter/>
  <StringParameter/>
</Url>

Имеет следующие параметры:

  • Address: адрес страницы, которую необходимо открыть. Может быть как абсолютным, так и относительным.
  • PassParams: определяет, передается ли информация о записи и языковом контексте в URL.
  • WinMode: режим открываемого окна. Может принимать одно из следующих значений:
    Значение Описание
    0 Открывает окно по умолчанию. Используется метод window.open
    1 Модальное диалоговое окно. Используется метод window.showModalDialog
    2 Немодальное диалоговое окно. Используется метод window.showModelessDialog
  • WinParams: Определяет параметры, которые будут переданы в открываемое окно. Формат этого параметра отличается в зависимости от значения параметра WinMode.

Набор же вложенных элементов такой же как и у элемента .

4. RuleDefinitions

Содержит отдельные действия, на которые ссылаются из CommandDefenition и CustomActions.

4.1 TabDisplayRules

Определяет условия, при которых отображается какая-либо Вкладка.

<TabDisplayRules>
  <TabDisplayRule TabCommand="String">
    <EntityRule />
    <PageRule />
  </TabDisplayRule>
</TabDisplayRules>

Единственный параметр TabCommand связывает TabDisplayRule с соответствующей Вкладкой.

Отображение Вкладки упарвляется двумя элементами:

Элемнт Описание
EntityRule Определяет объект, в контексте которого происходит действие.
PageRule Определяет адрес текущей страницы.

4.2 EnableRules

Содержит коллекцию отдельных EnableRule, которые определяют правила включения или отключения элемента Ленты;

<EnableRule Id="String">
  <CrmClientTypeRule />
  <CrmOfflineAccessStateRule />
  <CrmOutlookClientTypeRule />
  <CustomRule />
  <EntityRule />
  <FormStateRule />
  <OrRule />
  <OutlookItemTrackingRule />
  <OutlookVersionRule />
  <PageRule />
  <RecordPrivilegeRule />
  <SelectionCountRule />
  <SkuRule />
  <ValueRule />
</EnableRule>

Набор дочерних элементов такой же, как и у EnableRule из CommandDefinition.

4.3 DisplayRules

Набор отдельных правил DisplayRule, которые определяют правила отображения элементов.

<DisplayRule Id="String">
  <CrmClientTypeRule />
  <CrmOfflineAccessStateRule />
  <CrmOutlookClientTypeRule />
  <CrmOutlookClientVersionRule />
  <EntityPrivilegeRule />
  <EntityPropertyRule />
  <EntityRule />
  <FormEntityContextRule />
  <FormStateRule />
  <MiscellaneousPrivilegeRule />
  <OrganizationSettingRule />
  <OrRule />
  <OutlookRenderTypeRule />
  <OutlookVersionRule />
  <PageRule />
  <ReferencingAttributeRequiredRule />
  <RelationshipTypeRule />
  <SkuRule />
  <ValueRule />
</DisplayRule>

Набор дочерних элементов такой же как и у DisplayRule из CommandDefinition.

5. LocLabels

Содержит набор элементов LocLabel, которые задают отдельные строки текста , на которые в свою очередь можно ссылаться из других элементов. Например определить здесь строку текста и ссылаться на нее из элемента Title разных кнопок.

<LocLabel Id="String">
  <Titles>
    <Title
      description="String"
      languagecode="String"
    />
  </Titles>
</LocLabel>

В LocLabel Вам нужно задать только ID (на который будут ссылаться различные элементы управления из свои атрибутов). А в Title задается текстовая строка, связанная с кодом языка:

  • description: локализованный текст;
  • languagecode : Код языка.
Комментарии (2)
  • pavlyxar 24.11.2011

    Добрый день, прошу подсказать ответы на два вопроса, огромна просьба ответить, заранее спасибо:
    1)При добавлении на рибон кнопки ей ставится Sequence = 100, у вас написано, что это ее порядок следования на летне, но вот после Publish, она далеко несотая на форме и это бы даже было бы странно, причем бывают, как адекватные числа, так и типо 100, можете расписать поподробнее, что это за параметр;
    2)Еще хотелось бы знать, что значит параметр CommandCore на рибоне в разделе Misc, еще раз заранее большое спасибо)))

  • slivka_83 24.11.2011

    Добрый день.
    1. На ленте, но всегда в рамках того контейнера (группы) в котором находится кнопка. Из это именно порядок следования а не номер позиции. Т.е. если у вас на ленте две кнопки с номерами 1 и 100, то под номером 100 будет стоять второй.
    2. C CommandCore никогда раньше вроде дела не имел. Поэтому затрудняюсь ответить 🙂

*

code