As stated, there is an “approved” (or maybe “supported” is a better term for it) method for creating custom ribbon components. The ribbon is mostly “drawn” from declarative XML referred to as Ribbon XML and there is a lot of documentation that covers it on MSDN. This declarative approach makes it easy to create fairly complex tabs and controls. Much of the OOB ribbon is defined in the Program Files\Common Files\microsoft shared\Web Server Extensions\14\TEMPLATE\GLOBAL\XML\CMDUI.XML file. I have referenced this file to create several different ribbon components. (Note that for SharePoint 2013 this would be in the 15 folder)
If you take a look at the ribbon, you can see that there are several types of controls that you can create. There are 2 main tab types. A regular tab and what is called a contextual tab. A contextual tab is a tab that is only available when an object on a page is selected. This tab contains sub tabs with groups of buttons representing commands for customizing/formatting the selected object. An example from PowerPoint is below:
As you can see, this allows us to create some very nice controls based on what we want to do. So lets create something so that we can see this stuff in action.
We are going to create a new solution in Visual Studio. I am using Visual Studio 2012. For my example I also used some OOB images from the layouts/images folder. I copied the MENUOUTL.GIF file and used Adobe After Effects to change the color just to make a different icon for contrast. You can use any icon you like of course!
So start Visual Studio and create a new Project as shown below:
Click OK and then select the type of solution. This brings up the next screen where I chose a farm solution.
Click Finish to get into the solution.
Once in the solution, you will need to create an Empty Element. Right click on the C# project as highlighted below:
This will bring up a selection menu where you will select “Add” and then “New Item” as shown below:
Which will then bring up the next screen:
Give it a good name and as you can see, I named it "E3D_Email_Tab2". This will create an elements.xml file. This is where the Ribbon XML code is declared.
Of course this is an empty file and we need something to add here! Copy in the below code and I will go over it.
As you can see, that is a lot of XML, but not too much!
The first thing that is defined is that this is a CustomAction. We give this some attributes as follows:
- RegistrationType: This defines what type of item we are registering the custom action to. (Ex. Content Type)
- RegistrationId: This defines the id of the item. (Ex. 0x01 = default item content type id)
- Id: This is a unique identifier for the custom action
- Sequence: Defines the order
- Location: Defines where the custom action is placed. These can be found here for 2010 and here for 2013.
Then we move to the real meat of the XML by defining a CommandUIExtension with some CommandUIDefinitions. A CommandUIDefinition has the Location parameter as well denoting where it will be placed.
Tab: For this I defined a Tab item with the attributes as shown in the above XML. Again a unique id is given and also a Title that defines what is displayed in the tab as seen in the image shown below.
Scaling: The next thing I defined was the scaling. This is used to define what happens to your controls as the size of the ribbon changes. In my example, I chose to do nothing as there are only 2 controls. Again, there are several options here as defined in the RibbonXML documentation.
Groups: A place to add the groups for this single tab.
Group: This defines a single group with the attributes as shown.
Controls: This is where the real fun begins and you define the controls you want to use. In this example I used 2 SplitButton controls. This is simply a button with a dropdown menu.
Some nice attributes are defined in the controls and one of the nice ones is the Image32by32 and Image16by16. These define the location of the images that will be used by the controls. These attributes are available in many of the supported ribbon controls.
Another important attribute to include is the Command attribute of your control. This is the name or id of the command. This will then be used to define what to when that item is used.
There is also the TemplateAlias attribute. This is a somewhat unique identifier that is used later when defining the layout of the group.
And for that segue lets get to the next CommandUIDefiniton which is the Templates which is used to setup the group layouts, sections and rows as seen in the above XML. And notice the TemplateAlias names match.
So, lets look at what deploying this yields.
Remember I changed one of my icons for contrast as shown below.
I already had another solution which is why there are 2 custom tabs, but as you can see, they are pretty cool. You can take this pretty far if you want to really create some nice stuff. My next post on this topic will include adding controls to existing ribbons and groups and maybe a few more types of controls. Stay tuned, and as always, let me know what you think and if there is something you would like me to post about.