serving the solutions day and night

Pages

Friday, May 3, 2013

Customize the CRM Ribbon

Ribbon used to perform actions and add custom controls.
Displays actions that are relevant to each area of the application as users access them.
Dynamics CRM provides RibbonDiffXml definitions for all ribbons in the application for you to customize.
You can access the default ribbon definitions in the SDK\SampleCode\CS\Client\Ribbon\ExportRibbonXml\ExportedRibbonXml folder - this will generate all the entities ribbons

<RibbonDiffXml>
    <CustomActions>
        <CustomAction Id="Mscrm.DashboardTab.Favorite.CustomAction" Location="Mscrm.DashboardTab.Groups._children" Sequence="101">
            <CommandUIDefinition>
                <MaxSize Id="Mscrm.DashboardTab.Favorite.MaxSize" GroupId="Mscrm.DashboardTab.Favorite" Sequence="101" Size="LargeMedium" />
                <Scale Id="Mscrm.DashboardTab.Favorite.Scale.Popup" GroupId="Mscrm.DashboardTab.Favorite" Sequence="3001" Size="Popup" />
                <Group Id="Dns.DashboardTab.Favorite" Command="Mscrm.Enabled" Template="Mscrm.Templates.Flexible2" Sequence="100" Title="$LocLabels:Mscrm.DashboardTab.Favorite.TitleText" Description="$LocLabels:Mscrm.DashboardTab.Favorite.DescriptionText">
                    <Controls Id="Mscrm.DashboardTab.Favorite.Controls">
                        <Button Id="Mscrm.DashboardTab.Favorite.EmpApp" Command="Mscrm.DashboardTab.Favorite.EmpApp.Command" Sequence="201" ToolTipTitle="$LocLabels:Mscrm.DashboardTab.Favorite.EmpApp.LabelText" LabelText="$LocLabels:Mscrm.DashboardTab.Favorite.EmpApp.LabelText" ToolTipDescription="$LocLabels:Mscrm.DashboardTab.Favorite.EmpApp.Description" TemplateAlias="isv" />
                    </Controls>
                </Group>
                 <Tab Id="Mscrm.Isv.Global" Command="Mscrm.Isv.Global" Description="Place" Title="Place" Sequence="2000">
                    <Scaling Id="Mscrm.Isv.Global.Scaling">
                      <MaxSize/ />
                      <Scale/ />
                    </Scaling>
                    <Groups Id="Mscrm.Isv.Global.Groups">
                      <Group/>
                    </Groups>
                      </Tab>
            </CommandUIDefinition>
        </CustomAction>
        <HideCustomAction />
    </CustomActions>
    <Templates>
              <RibbonTemplates Id="Mscrm.Templates"></RibbonTemplates>
    </Templates>
     <CommandDefinitions />
     <RuleDefinitions />
</RibbonDiffXml>


Each entities contains there own ribbon xml ( called the Entity Ribbon Template), Ribbon modifications for a specific entity must be defined in the //ImportExportXml/Entities/Entity/RibbonDiffXml node. You can global ribbon in the customization.xml of global

Entity controls Ribbons: Form, Grid & Sub-Grid

Grid Ribbons
Beginning with Mscrm.HomepageGrid.<entity logical name>. For example, an account entity grid is Mscrm.HomepageGrid.account.MainTab

Sub Grid Ribbons
Beginning with Mscrm.SubGrid.<entity logical name>. For example, on account entity sub grid is Mscrm.SubGrid.account.MainTab.

Form Ribbons
Each entity can have multiple forms. You can define changes to the form ribbon - (//ImportExportXml/Entities/Entity/RibbonDiffXml).
Each entity form can have a specific ribbon definition - //ImportExportXml/Entities/Entity/FormXml/forms/systemform/form/RibbonDiffXml.
Beginning with Mscrm.Form.<entity logical name>. For example, an account entity form is Mscrm.Form.account.MainTab.

Decompressing the Ribbon Data
Use System.IO.Packaging.ZipPackage
System.IO.Packaging.ZipPackage package = (ZipPackage)ZipPackage.Open(memStream, FileMode.Open);
ZipPackagePart part = (ZipPackagePart)package.GetPart(new Uri("/RibbonXml.xml", UriKind.Relative));

Retrieving the Application Ribbon Data
RetrieveApplicationRibbonRequest appribReq = new RetrieveApplicationRibbonRequest();
RetrieveApplicationRibbonResponse appribResp = (RetrieveApplicationRibbonResponse)_serviceProxy.Execute(appribReq);

//Retrieve system Entity Ribbons
RetrieveEntityRibbonRequest entRibReq = new RetrieveEntityRibbonRequest() { RibbonLocationFilter = RibbonLocationFilters.All };

//Check for custom entities
 RetrieveAllEntitiesRequest raer = new RetrieveAllEntitiesRequest() { EntityFilters = EntityFilters.Entity };


LocLabels element - defines the title and description of your ribbon item.
The LocLabels element XML structure follows:
<LocLabels>
    <LocLabel Id="">
        <Titles>
            <Title description="" languagecode=""/>
        </Titles>
    </LocLabel>
</LocLabels>

<LocLabels>
  <LocLabel Id="Dns.Form.contact.MainTab.Save.Close.Description">
    <Titles>
      <Title languagecode="1033" description="Close this window." />
    </Titles>
  </LocLabel>
  <LocLabel Id="Dns.Form.contact.MainTab.Save.Close.LabelText">
    <Titles>
      <Title languagecode="1033" description="Close" />
    </Titles>
  </LocLabel>
</LocLabels>

CustomActions element - 2 types CustomAction and HideCustomAction
You need to know the unique identifier of the Ribbon Button element to hide or update or remove it.
All of your changes will be in the <CustomAction> (RibbonDiffXml) or <HideCustomAction> (RibbonDiffXml) elements.

<CustomActions>
    <HideCustomAction Location="Mscrm.BasicHomeTab.New.NewActivity" HideActionId="Mscrm.BasicHomeTab.New.NewActivity.HideAction" />
    <HideCustomAction Location="Mscrm.HomepageGrid.{!EntityLogicalName}.Copy" HideActionId="Mscrm.HomepageGrid.{!EntityLogicalName}.Copy.HideAction" />
</CustomActions>

Some buttons actions are also controlled by Dynamics CRM security settings. For example, hide the New contact button for some users, remove the create privilege on the contact entity from those users as opposed to hiding the New button.

Templates - define how the items in a ribbon group should display and scale as the application user interface changes.
<Templates>
    <RibbonTemplates Id="Mscrm.Templates"></RibbonTemplates>
</Templates>

CommandDefinitions element - defines a set of rules that control when a ribbon item is displayed and the actions to perform when the item is clicked.
<CommandDefinitions>
    <CommandDefinition Id="String">
        <EnableRules>
            <EnableRule/>
        </EnableRules>
        <DisplayRules>
            <DisplayRule/>
        </DisplayRules>
        <Actions>
            <JavaScriptFunction FunctionName="String" Library="String">
                <BoolParameter Name="string" Value=["0" | "1" | "true" | "false"]/>
                 <CrmParameter />
                 <DecimalParameter/>
                 <IntParameter/>
                 <StringParameter/>
             </JavaScriptFunction>
            <Url Address="String" PassParams=["0" | "1" | "true" | "false"] WinMode="Integer" WinParams="String">
                <BoolParameter Name="string" Value=["0" | "1" | "true" | "false"]/>
                 <CrmParameter />
                 <DecimalParameter/>
                 <IntParameter/>
                 <StringParameter/>
            </Url>
        </Actions>
    </CommandDefinition>
</CommandDefinitions>

<CrmParameter Name = “String”
  Value= ["CommandProperties" | "PrimaryEntityTypeCode" |  "PrimaryEntityTypeName" | "PrimaryItemIds" | "FirstPrimaryItemId" |
     "PrimaryControl" | "PrimaryControlId" | "SelectedEntityTypeCode" | "SelectedEntityTypeName" | "FirstSelectedItemId" |
     "SelectedControl" | "SelectedControlSelectedItemCount" | "SelectedControlSelectedItemIds" |
     "SelectedControlSelectedItemReferences" | "SelectedControlAllItemCount" | "SelectedControlAllItemIds" |
     "SelectedControlAllItemReferences" | "SelectedControlUnselectedItemCount" | "SelectedControlUnselectedItemIds" | 
     "SelectedControlUnselectedItemReferences" | "OrgName" | "OrgLcid" | "UserLcid"] />

Enable Rules: Specifies when a specific ribbon control will be enabled.
Display Rules: Specifies when a specific ribbon element will be visible.
Actions: Specifies what code will execute when a ribbon control is uses.

<CommandDefinition Id="Sample.all.Developer.Tools.Controls.CustomButton.Command">
    <EnableRules />
    <DisplayRules>
        <DisplayRule Id="Mscrm.Isv.Global" />
    </DisplayRules>
    <Actions>
        <JavaScriptFunction Library="$webresource:sample_/Scripts/DeveloperTools.js" FunctionName="ChangeBusinessUnit" />
        <StringParameter Value="1" />
        <CrmParameter Value="FirstSelectedItemId" />
    </Actions>
</CommandDefinition>

For example, when the ribbon command is clicked, CRM executes the ChangeBusinessUnit method from a script in a custom web resource. The
DisplayRule element references Sample.all.Developer.Tools.Controls.CustomButton.DisplayRule.

<OrRule> - lets you override the default AND comparison for multiple enable rule types.
<CrmOfflineAccessStateRule> -  Dynamics CRM for Microsoft Office Outlook with Offline Access.
    <CrmOfflineAccessStateRule Default=["0 | 1 | true | false"] InvertResult=["0 | 1 | true | false"] State=["Online | Offline"] />
<CrmClientTypeRule> - depending on the type of client used. Web or Outlook
<DisplayRules>
<DisplayRule Id="Mscrm.Isv.Global">
  <OrRule>
    <Or>
      <CrmClientTypeRule Type="Web" />
    </Or>
    <Or>
      <CrmClientTypeRule Type="Outlook" />
      <CrmOfflineAccessStateRule State="Online" />
    </Or>
    <Or>
      <CrmClientTypeRule Type="Outlook" />
      <CrmOfflineAccessStateRule State="Offline" />
    </Or>
  </OrRule>
</DisplayRule>

RuleDefinitions element - defines the actual rules that are referenced from a CommandDefinition.
<RuleDefinitions>
  <TabDisplayRules>
      <TabDisplayRule TabCommand="String">
         <EntityRule AppliesTo=["PrimaryEntity | SelectedEntity"]  Context=["Form | HomePageGrid | SubGridStandard | SubGridAssociated"]  Default=["0 | 1 | true | false"]  EntityName="String" InvertResult=["0 | 1 | true | false"]/>
         <PageRule Address="String" Default=["0" | "1" | "true" | "false"] InvertResult=["0" | "1" | "true" | "false"] />
    </TabDisplayRule>
  </TabDisplayRule>
  <DisplayRules />
  <EnableRules />
</RuleDefinitions>

<RibbonDiffXml>
<CustomActions>
  <CustomAction Id="Dns.Form.contact.MainTab.Save.Close.CustomAction" Location="Mscrm.Form.contact.MainTab.Save.Controls._children" Sequence="41">
    <CommandUIDefinition>
      <Button Id="Dns.Form.contact.MainTab.Save.Close" Command="Dns.Form.contact.MainTab.Save.Close.Command" Sequence="50" ToolTipTitle="$LocLabels:Dns.Form.contact.MainTab.Save.Close.LabelText" LabelText="$LocLabels:Dns.Form.contact.MainTab.Save.Close.LabelText" ToolTipDescription="$LocLabels:Dns.Form.contact.MainTab.Save.Close.Description" TemplateAlias="o1" Image16by16="/_imgs/ribbon/ActivityClose_16.png" Image32by32="/_imgs/ribbon/ActivtiyClose_32.png" />
    </CommandUIDefinition>
  </CustomAction>
  <HideCustomAction Location="Mscrm.Form.contact.Activate" HideActionId="DnsMscrm.Form.contact.Activate.HideAction" />
  <HideCustomAction Location="Mscrm.Form.contact.Deactivate" HideActionId="DnsMscrm.Form.contact.Deactivate.HideAction" />
  <HideCustomAction Location="Mscrm.Form.contact.Delete" HideActionId="DnsMscrm.Form.contact.Delete.HideAction" />
  <HideCustomAction Location="Mscrm.Form.contact.MainTab.Collaborate" HideActionId="DnsMscrm.Form.contact.MainTab.Collaborate.HideAction" />
  <HideCustomAction Location="Mscrm.Form.contact.MainTab.Workflow" HideActionId="DnsMscrm.Form.contact.MainTab.Workflow.HideAction" />
  <HideCustomAction Location="Mscrm.Form.contact.SaveAndNew" HideActionId="DnsMscrm.Form.contact.SaveAndNew.HideAction" />
</CustomActions>
<Templates>
  <RibbonTemplates Id="Mscrm.Templates"></RibbonTemplates>
</Templates>
<CommandDefinitions>
  <CommandDefinition Id="Dns.Form.contact.MainTab.Save.Close.Command">
    <EnableRules>
      <EnableRule Id="Dns.Form.contact.FormStateNotNew.EnableRule" />
      <EnableRule Id="Dns.Form.contact.Field.EnableRule" />
    </EnableRules>
    <DisplayRules>
      <DisplayRule Id="Dns.Form.contact.WebClient.DisplayRule" />
    </DisplayRules>
    <Actions>
      <JavaScriptFunction Library="$webresource:Dns_JavaScript/Maint.js" FunctionName="CloseForm" />
    </Actions>
  </CommandDefinition>
</CommandDefinitions>
<RuleDefinitions>
  <TabDisplayRules />
  <DisplayRules>
    <DisplayRule Id="Dns.Form.contact.WebClient.DisplayRule">
      <OrRule>
    <Or>
      <CrmClientTypeRule Type="Web" />
    </Or>
    <Or>
      <CrmClientTypeRule Type="Outlook" />
    </Or>
      </OrRule>
    </DisplayRule>
  </DisplayRules>
  <EnableRules>
    <EnableRule Id="Dns.Form.contact.Field.EnableRule">
      <ValueRule Field="new_formcloseflag" Value="true" />
    </EnableRule>
    <EnableRule Id="Dns.Form.contact.FormStateNotNew.EnableRule">
      <FormStateRule State="Create" InvertResult="true" />
    </EnableRule>
  </EnableRules>
</RuleDefinitions>
<LocLabels>
  <LocLabel Id="Dns.Form.contact.MainTab.Save.Close.Description">
    <Titles>
      <Title languagecode="1033" description="Close this window." />
    </Titles>
  </LocLabel>
  <LocLabel Id="Dns.Form.contact.MainTab.Save.Close.LabelText">
    <Titles>
      <Title languagecode="1033" description="Close" />
    </Titles>
  </LocLabel>
</LocLabels>
</RibbonDiffXml>

http://msdn.microsoft.com/en-us/library/gg309639.aspx

2 comments:

kar poh chong said...

ut where is the mini sub-grid? I notice that we cant modify the mini sub-grid but can edit the command. Do you experience before how to edit the command for example the "+" add button?

Daynight said...

you will get answer from the blogs
http://makdns.blogspot.com/search/label/command?