Adding a Button to a CRM 2011 Form Ribbon

Here’s a shortcut guide to customising the Form ribbon in CRM 2011.  Rather than explaining all of the intricacies of the ribbon here’s a set of instructions that will get a button added to a form with the least amount of steps/complexity.  In this scenario we will add a button to the Account form that will launch an external web page (if you prefer the button executes a jscript function keep reading as I cover that as well)… 

Here’s the steps:

1. Create a new Solution called Ribbon.

2. Add to your Solution the Account entity and then export the Solution.

3. Determine the location ID for where you want your button to sit (note: this take a bit of research, keep reading…)

3a. Download and install the CRM SDK.  Then go to the following SDK folder:

sdk\samplecode\cs\client\ribbon\exportribbonxml\exportedribbonxml\

Here you will see Ribbon definitions for each entity (e.g. accountribbon.xml)

[UPDATE: 14 Dec 2011 – The latest SDK did not include the ribbon definition XML files forcing you to build and run an app from source code provided in order to generate them for your self. I provide instructions on this process here]

3b. Open accountribbon.xml in Visual Studio.

Now we need to find the relevant bit of XML that defines the ribbon component we want to customise.  Each entity has ribbon definitions for it’s form ribbon (“Form”), for the ribbon that appears when the entity’s grid view is selected from the main CRM menu (“HomePageGrid”) and for the ribbon that appears when the entity is displayed as an in-line grid on either a dashboard on another entity’s form (“SubGrid”).  You will see Tab definitions for each of this:

image

We are interested in the Form ribbon so minimise the other XML elements and have a look at the Tab definitions for the Account Form.  You will see 3 tabs are defined:

image

These are the definitions behind the “Account”, “Add” and “Customize” tabs you see when looking at the Account form in CRM:

(Note: As the “File” tab is generic it is defined in the application.ribbon.xml rather than inside each entity’s ribbon xml file)

image

The Tab that we want is the one that appears as “Account”.  The Tab definition for this is:

Tab Id="Mscrm.Form.account.MainTab"

(Note: look at the Buttons defined under each Tab  to help figure out the correct Tab)

To add a button to the CRM ribbon we need to specify a location.  The value we need is the “Controls Id”.   Find the button you want your button added next to and grab the “Controls ID” that button sits under.  We will add our button to the “Process” Group next to the “Run Workflow” button so the Controls ID value we want is:

Controls Id="Mscrm.Form.account.MainTab.Workflow.Controls"

image

3c. Copy the Controls Id value to NotePad

3d.  Close accountribbon.xml

 

That’s our research done, let’s get back to defining our button…


 

4. Open the customisation.xml file that was included in your exported Solution zip file (open in Visual Studio).

5. From the XML menu, click Schemas and then add from .. sdk\schemas\ the 3 xsd files that have “ribbon” in their name and also customizationssolution.xsd (this gives us intellisense)

7. Back in the main window of VS do a Find on “RibbonDiff” and then swap out: “<CustomActions />”  with:

<CustomActions> 
  <CustomAction Id="GT.account.Form.Star.CustomAction" 
                Location="Mscrm.Form.account.MainTab.Workflow.Controls._children" 
                Sequence="1"> 
    <CommandUIDefinition> 
      <Button Id="GT.account.Form.Star.Button" 
              Command="GT.account.Form.Star.Command" 
              LabelText="Star" 
              ToolTipTitle="Tip" 
              ToolTipDescription="This is a Star" 
              TemplateAlias="o1" 
              Image16by16="$webresource:new_star16x16" 
              Image32by32="$webresource:new_star32x32" 
      /> 
    </CommandUIDefinition> 
  </CustomAction> 
</CustomActions>

If you want to deviate from my scenario of customising the Account form the relevant bit in the above is the Location reference.  This is where the Controls ID value that we we obtained from our research goes.  Note: The Controls ID value needs to be appended with “._children” e.g.:

Location="Mscrm.Form.account.MainTab.Workflow.Controls._children"

 

8.  If you have 16x16 and 32x32 icons for your button go and add those into CRM as web resources and then change the references in the above code snippet.  Otherwise, remove the Image16by16 and Image32by32 lines (they’re optional, the button will still show).

9. Scroll down a bit and replace: “<CommandDefinitions />”  with:

<CommandDefinitions> 
  <CommandDefinition Id="GT.account.Form.Star.Command"> 
    <EnableRules> 
    </EnableRules> 
    <DisplayRules> 
    </DisplayRules> 
    <Actions> 
      <Url Address="http://www.google.com" /> 
    </Actions> 
  </CommandDefinition> 
</CommandDefinitions>

10.Adjust the Url reference to whatever you want.  You can use use a relative reference if you want to launch a CRM URL or an HTML page you have loaded into CRM.

or:

If you want to execute a jscript function instead swap out the <Actions> node with a jscript web resource and function name reference like the below:

<Actions> 
  <JavaScriptFunction Library="$webresource:new_getcontact" 
                      FunctionName="NewCaseOnClick" 
                      /> 
</Actions>

11. Save your customisation.xml changes.

12. Re-zip your unzipped solution back into a solution zip file, import, publish all and then refresh your browser.

Done.  Smile

 

End result:

image

 

This solution is available for download in both managed and unmanaged formats.

About these ads

54 thoughts on “Adding a Button to a CRM 2011 Form Ribbon

  1. Mike Kolling

    Hi

    Great article, can you tell me how I would do this for a new bespoke entity that is not in the SDK?

    Cheers

    Mike

    Reply
    1. Gareth Tucker Post author

      Hi Mike,

      Same approach for making the change. For determining the Location ID I think you would need to look in “ApplicationRibbon.XML”. Have a look at “Tab Id=”Mscrm.Form.{!EntityLogicalName}.MainTab”. I think you would reference a Control ID in that Tab definition but then would also need to add a display rule to ensure your new button change is only applied to the one entity and not all.

      Good luck!
      Gareth.

      Reply
  2. Mike Kolling

    Hi

    I ran the SDK SampleProject to kick out a new ApplicationRibbon.xml, got the location and as you say, the rest is the same.

    It worked a treat, many thanks for your help!

    Mike

    Reply
  3. Casper Schau

    Hi
    I need to have som Url attributes on the url string. The values is from the form, from where you hit the button. How can I make this URL? Should I make the URL in a javascript function and make the button action start the javascript function?

    By the way you dont show how to use a javascript function, but instead just shows a picture of the URL action in your fine blog. :) Can you please help me as fast as possible…

    Reply
    1. Gareth Tucker Post author

      Hi, yes I would call a Jscript function and have that collect the form values and then open the URL. To execute a jscript function from a button swap out the action I have at Step 11 with what you will see at step 5 of the following walkthrough in the SDK: “Walkthrough: Add a Custom Button to an Existing Group for all Entities” (search on that title and you will find it). Sorry, I tried to paste the code here but this blog site is removing it from my comment.

      Note: You will need to place your Jscript function into a Web Resource. Refer to my latest blog post if you need help with the syntax for collecting values from the form. And my post titled “Launching a Dialog from a Ribbon Button in CRM 2011″ has downloadble source code that includes a URL launch from Jscript.

      Good luck!

      Reply
  4. swesa

    Hi,

    Is there anyway I can change the existing functionality of a ribbon?
    Where can I find the existing code for a particular button?

    For example,
    I want to change the functionality of “Resolve a Case”, as in I want it to perform some function of my own. Is there anyway I can do this?

    Please reply to the earliest! Thank you!

    Reply
  5. Pingback: Add Button to Ribbon on MSCRM 2011 « .Work and Study book – A.K.Margono.

  6. Mike

    Hi Gareth,

    Great work on this blog! I used it to create a custom button on the Contact entity to call a Web Resource that updates the Contact’s address to that of its Parent Account if they are different!

    I have a question though! I am not well versed with XML and wanted to know how I would go about adding another button to the same entity (Contact) that I have my initial button on? Would I add the code from step 9 right after the last line of the first instance where is?

    Thank you for your help!

    Reply
    1. Gareth Tucker Post author

      Step 7 has you add an XML snippet like this:

      CustomActions
      CustomAction id = “uniqueid1″
      details
      CustomAction
      CustomActions

      This adds a button to the ribbon. To add 2 buttons to the ribbon you’ll need to add a 2nd CustomAction inside the CustomActions node, e.g.:

      CustomActions
      CustomAction id = “uniqueid1″
      details
      CustomAction
      CustomAction id = “uniqueid2″
      details
      CustomAction
      CustomActions

      Presumably you’ll want the second button to perform a different action from the 1st button so you will also need to add a 2nd CommandDefinition inside the CommandDefinitions node (at step 9).

      Make sure you give each CommandDefinition and CustomAction unique Ids.

      regards,
      Gareth

      Reply
    2. Gareth Tucker Post author

      Hi Mike, WordPress warped my reply. I’ve since tidied it up. It you received a warped reply via email go to my blog and you will hopefully see something a little more readable :)

      Reply
      1. Mike

        Hi Gareth,

        Two things:
        1. Thank you for the amazingly quick reply!!
        2. It worked like a charm! Thank you very much for your contributions, you have helped me learn a very great piece of customization in CRM!

  7. Yusuf Ansari

    Dear Gareth,

    Thanks for explaining ribbon customization in an excellent way.I have came across multiple
    blogs but their explanation is very poor.
    A good blogger explains things in such a way that even novice can understand it.
    I hope you will keep posting such stuffs.

    Regards,

    Yusuf

    Reply
  8. Pingback: Editing Ribbon Buttons in CRM 2011 « Gareth Tucker's Microsoft CRM Blog

  9. Andrew Nevitt

    Hi Gareth

    How could we limit the Ribbon customisation to a specific form (e.g. a new custom form added to the Account entity) so that it executes on that form only (but the main “Information” form retains the standard Ribbon)?

    BTW: Great blog

    Andrew

    Reply
  10. Andrew Nevitt

    Hi Gareth,

    Forgot to add that this is a contextual ribbon not a form ribbon – it’s actually hiding a button on the Sub Accounts grid.

    Will let you know if we figure it out

    Thanks

    andrew

    Reply
  11. Abhishek Yadav

    Hi Gareth
    This is really very great and helpful article. really thanks a lot for sharing such useful information with us.

    Thanks
    Abhishek

    Reply
  12. Kyle

    Thanks a lot for the article, it helped a lot.

    I also wanted to add a button to the ribbon that appears when the dashboards are selected. I tried exporting a solution that contained some dashboards but there was nothing in the XML to do with the Ribbon. Any ideas on how to do it?

    Reply
  13. Kyle

    Thanks for the great post, it has been a big help.

    I also want to add a button to the ribbon that appears when dashboards are selected. I tried exporting a solution that contained some dashboards but there is nothing in the XML to do with the ribbon.

    Any ideas on how to do it?

    Reply
    1. Gareth Tucker Post author

      There is an item called “Application Ribbons”, create a Solution and add that item. Make your change to that customizations.XML file. In the Sdk there is a corresponding applicationribbon.XML file for you to refer to, in there you will see the dashboard ribbons are defined.

      Reply
  14. Psychology

    My brother recommended I would possibly like this website. He used to be entirely right. This post actually made my day. You cann’t consider simply how a lot time I had spent for this information! Thanks!

    Reply
  15. kurt

    Great article, I have struggled thru using the SDK to add buttons before, reading this was a breeze. Do you have any thoughts on disabling a button after the user clicks it? I got a button that creates a document and loads it up to SP, but I need to stop the user from clicking twice! thanks

    Reply
    1. Gareth Tucker Post author

      Perhaps have your button also update a field on the CRM form and then add a custom display rule to your button based on that field. That sort of approach is worth exploring. Else, build this logic into your code that creates the document, have it check that field before it does anything else. HTH

      Reply
  16. Steve

    I love your articles, but I am a bit confused. I have read as much I could, but most of the information seems to talk about adding Custom Buttons to either Custom Tabs or Existing Tab. What about if you want to add a button that already exists somewhere else in dynamics and add it to a completely different ribbon. For example, I was asked to add the “Open New Case” button that appears on the Cases Ribbon and transplant it to the Queue Ribbon. The queue already exists, as does the aforementioned button, but in separate places…

    Reply
    1. Gareth Tucker Post author

      Hi Steve, I suspect that’s not going to be possible I’m afraid. You can try adding a new button to the Queue ribbon by defining a button there that has the same Action, Images, etc as the New button on the Case form but I suspect the Action won’t work for you in this new context. If you have a look at the New Case button its Action is a jscript function call “openObj”. If the function was called “newCase” I’d have some hope but it sounds like this is something a bit more dynamic that won’t work out of context. If you are more optimistic then me you could give it a try! Alternatively, add a new button to the Queue ribbon, steal the image that is used by the normal New Case button but make your Action a jscript function call to a new function that you create that will perform a pop of the new Case form. If you look at the jscript I used in this post you will see the approach used to pop a CRM form via jscript: http://gtcrm.wordpress.com/2011/02/22/launching-a-dialog-from-a-ribbon-button-in-crm-2011/

      Reply
    2. Gareth Tucker Post author

      I take it back. I was using the cool new Ribbon Editor available on Code Plex and it only tells half the story. Looking at the raw incidentribbon.xml I see that yes the new Case button calls a generic “openObj” function but I wouldn’t couldn’t see in the Ribbon Editor tool was that within that function call the entitytypecode is passed as a parameter. So it may well be possible for you to create a button on the Queue ribbon that mimics this button where you hard code the entitytypecode you pass to this function. Good luck! [update: Another mistake - the Ribbon Editor can show the parameter detail, there's a small arrow button you can click to expand the Actions detail to see more info]

      Reply
  17. pnkcrm

    Hi Gareth, I found the sequence number mentioned on the accountribbonxml for Run workflow-20, Run Dialog-25 mentioned on that SDK xml file. so in above example we didn’t mention any sequence number for the button. So sequence number is not needed? if i want to place the button between or before these two buttons. i should follow the sequence number?

    Reply
    1. Gareth Tucker Post author

      yeah, there is a lot of detail I have left out to keep things simple (things like language codes, sequence numbers and scaling). Add a sequence number to control the positioning.

      Reply
  18. yan

    Hello, is it possible to hide a sub menu item in the File (Jewel) button? For instance you hide the sub menu item Save & New in the section “Save”?
    I tried it with this:
    in customizations.xml for the entity SalesOrder but it doesn´t work.

    Reply
  19. Nicolas Brandl

    Hi, excelent post! I’m a contributor to the elblogdedynamicsCRM.com It’s the #1 blog for the spanish community and would be great if we can include a translation of this post. Thanks in advance.

    Reply
    1. Gareth Tucker Post author

      Sorry, this is not something I’ve seen, I don’t think there is a supported way to do this. However, find yourself a jscript expert, there is probably a generic jscript solution for capturing a keyboard action and then executing a function. And you should be able to sniff out how to click the ribbon button programatically. See if this helps:

      http://stackoverflow.com/questions/2511388/how-can-i-add-a-javascript-keyboard-shortcut-to-an-existing-javascript-function

      Reply
  20. Steven Turner

    Hi Gareth
    Awesome post. Is it possible to change the location where the new custombutton is placed in the ribbon? I want to add a new button that should sit beside the SaveAndClose button on the Incident form but the system keeps defaulting it to the far end of the ribbon.

    Reply
  21. Sylvia

    hey! Awesome post. I want to know if it is possible to create a button and this button can execute a program or a bat file.
    Thanks in advance.

    Reply
  22. Tomas

    Thanks!
    Any idea on how to specify an accesskey ALT+ for a ribbon button?
    You could do that in 4.0 in ISV.Config but I can’t find it in 2011.

    Reply
  23. Pingback: Ribbon tutorials | hachecrm2011

  24. Peter

    Hi,
    i have a problem with this. The Icon shows correctly in IE but in Outlook Plugin, the Icon is streched. Does anyone knows why?
    THX, Greets Peter

    Reply
  25. ambien

    Very nice post. I just stumbled upon your blog and wished to
    say that I’ve really enjoyed surfing around your weblog posts. In any case I’ll be subscribing in your rss
    feed and I am hoping you write once more soon!

    Reply
  26. Pepsi Man

    Very nice post, gave me some success. Here’s where I’m failing:

    I added a tab to the ApplicationRibbon, so it’s on all forms. I want to add a button to that tab for a particular entity. I’ve tried dozens of approaches, including your instructions here verbatim. Nothing has worked.

    If this approach is possible, please tell me how to do it. In the meantime, I’m going to try removing the custom tab and adding a new tab for that entity. Thanks.

    Reply
      1. Pepsi Man

        So I tried the ribbon workbench and it led me to a different approach. I added the button for the custom entity to the main application ribbon and added an enable-rule to restrict the button to being enabled for just that entity. This is certainly a much cleaner approach; it avoids having objects in one ribbon referencing objects in another.

      2. Nicolas

        Yeah, that’s the best approach. Editing the application ribbon is usefull only if you intend to modify or add some functionality to all the entities, not just one.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s