This post is intended for BETA1. It will work on BETA2 as well, just remove the … for
First of all, create a new Empty SharePoint project in Visual Studio. (no screenshots after this as my laptop here can’t run SP2010)
- Rename your project to MyCoolButton
- Add an empty Element.
- In that element, paste the following xml:
<?xml version="1.0" encoding="utf-8" ?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/"> <CustomAction Id="MeSoCool" Location="CommandUI.Ribbon.Documents.New.Controls._children"> <CommandUIExtension> <CommandUIDefinitions> <CommandUIDefinition Location="CommandUI.Ribbon.Documents.New.Controls._children"> <Button Id="Ribbon.Documents.New.Controls.MyCoolButton" Image16by16="/_layouts/images/edit.gif" Image32by32="/_layouts/images/placeholder32x32.png" Description="MyDescription" Command="MyCoolButton" LabelText="Banzai" Sequence="60" TemplateAlias="o1" /> </CommandUIDefinition> </CommandUIDefinitions> </CommandUIExtension> </CustomAction> </Elements>
What does all this XML mean?
First of all we will be adding a CustomAction, and the most important attribute there is the Location. This location attribute will define where the button is going to appear. Notice that the same attribute is also defined in the CustomUIDefinition which is the location where it will need to be defined in Beta2. So in Beta1 apply the Location to the CustomAction, in Beta2 only apply the location to the CommandUIDefinition. Notice the _children in the end, you need to add it to be able to add buttons to that Control collection.
Where does this location come from? In the CMDGui.XML file that location is defined in a group. This group is part of a group collection called Ribbon.Documents.Groups which is part of the Tab called Ribbon.Documents. This tab is the ribbon we will see when we are working with documents. Important to notice is the Template the group is using. If the Template used is Ribbon.Templates.Flexible2 you can add buttons to that group. If it isn’t a flexible template (like Ribbon.Templates.ThreeRowsSixAlignedControls2) then you can’t add buttons as those are fixed templates. As an example I added the xml for the Ribbon.Documents.New group.
<Group Id="Ribbon.Documents.New" Sequence="10" Command="DocumentNewGroup" Description="" Title="$Resources:core,cui_GrpNew;" Image32by32Popup="/_layouts/images/placeholder32x32.png" Template="Ribbon.Templates.Flexible2" >
Ok, on to the next item in our XML, the CommandUIExtensions. They contain the CommandUIDefinitions who are defining the element that you are showing (a Button in our case). The name of the second element escapes me and I can’t check SP2010 at the moment, but the other element within the CommandUIExtensions defines the action of the button (what happens if you click on it) Our little post is only focused on making it appear. Now back to our Button Control.
The Id needs to start with Ribbon.Documents.New.Controls. After that you can put whatever you want. The image attributes are used and the images are shown depending on what is defined in the GroupTemplates. What does that mean? In the GroupTemplates (also defined in the CMDGui.xml) it is defined how a button in the ribbon should behave when the page gets resized. Should it hide itself, should it change it’s template (for instance instead of 3 large buttons next to eachother 3 small buttons above eachother)That way we can control how our Ribbon is behaving when the page gets resized. Description is quite easy to understand what it does, Command links to the command that you can define afterwards (you can deploy without having implemented the command), the LabelText is used in the template and shown on the ribbon, the Sequence defines where the button needs to be places and the TemplateAlias links to the template that you are using for that button.
Ok, now that we have that XML we just need to do one more thing:
<script OnDemandKey="ribbon"> <File></File> <File>SP.Ribbon.js</File> </script>
Now we are set to go. Rightclick your project, select deploy. Go to a document library, on the ribbon select Documents and you should see a new button next to the New Folder button. (More images will follow as soon as I get home, but we were so excited when it finally worked that I at least had to put it online, but I’m sure Joris will do the same very soon 🙂 )
Should I have missed something, let me know, but this should do the trick for you 🙂