Ribbon customization Part 5

In this post, I am going to talk about how to add tab and then how to add groups and controls in it.

If you have not gone through Part 1 to Part 4, I recommend you reading them first and then continue reading this post.

First we will start with very basic example of how to add a simple tab and one group with one control. This will reduce the level of complexity and then we can dive into more examples.

So here is the example that I have used and following is the output of it. I am going to explain each important tag in detail. We have added one tab called Utilities and I have added one group for search with one button control for Bing search engine.

<blockquote><?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction Id="SPKings.Ribbon.CustomTab"
Location="CommandUI.Ribbon" RegistrationType="List" RegistrationId="101">
<CommandUIExtension>
<CommandUIDefinitions>
<CommandUIDefinition
Location="Ribbon.Tabs._children">

<Tab Id="SPKings.Ribbon.CustomTab"
Title="Utilities"
Description="Different Utilities comes here"
Sequence="501">


<Scaling Id="SPKings.Ribbon.CustomTab.Scaling">

<MaxSize Id="SPKings.Ribbon.CustomTab.SearchGroup.MaxSize"
GroupId="SPKings.Ribbon.CustomTab.SearchGroup"
Size="OneLarge"/>

<Scale Id="SPKings.Ribbon.CustomTab.SearchGroup.Scaling.CustomTabScaling"
GroupId="SPKings.Ribbon.CustomTab.SearchGroup"
Size="OneLarge" />

</Scaling>

<Groups Id="SPKings.Ribbon.CustomTab.Groups">

<Group
Id="SPKings.Ribbon.CustomTab.SearchGroup"
Description="Different Search Engines"
Title="Search Engines"
Sequence="52"
Template="SearchEnginesGroup">


<Controls Id="SPKings.Ribbon.CustomTab.SearchGroup.Controls">

<Button
Id="SPKings.Ribbon.CustomTab.SearchGroup.SearchBingButton"
Sequence="15" Image16by16="/_layouts/images/CustomImages/Bing-logo.jpg"
Image32by32="/_layouts/images/CustomImages/bing.png"
Description="Click to see Bing message"
Command="btnGoToBingCommand"
LabelText="Bing"
TemplateAlias="BingSearch" />

</Controls>

</Group>


</Groups>
</Tab>
</CommandUIDefinition>

<CommandUIDefinition
Location="Ribbon.Templates._children">

<GroupTemplate Id="SearchEnginesGroup">
<Layout Title="OneLarge" LayoutTitle="OneLarge">
<Section Alignment="Top" Type="OneRow">
<Row>
<ControlRef DisplayMode="Large" TemplateAlias="BingSearch" />
</Row>
</Section>
</Layout>
</GroupTemplate>


</CommandUIDefinition>

</CommandUIDefinitions>

<CommandUIHandlers>
<CommandUIHandler
Command="btnGoToBingCommand"
CommandAction="javascript: var statusId = SP.UI.Status.addStatus('This will take you to Bing search');
SP.UI.Status.setStatusPriColor(statusId, 'green');"></CommandUIHandler>

</CommandUIHandlers >

</CommandUIExtension>
</CustomAction>
</Elements></blockquote>

And here is what you get

Now, let’s understand important tags in above XML.

<CustomAction Id="SPKings.Ribbon.CustomTab"
Location="CommandUI.Ribbon" RegistrationType="List" RegistrationId="101">


We have defined that we want to add something in the ribbon which we have indicated with the help of CommandUI.Ribbon and we have mentioned that we want a new tab to be on the document library by using List registration type and ID.

<CommandUIDefinition
Location="Ribbon.Tabs._children">


Then we have shown that we want to add children in the tabs. That means we want to add one more tab in the existing list of tabs.

<Scaling Id="SPKings.Ribbon.CustomTab.Scaling">

<MaxSize Id="SPKings.Ribbon.CustomTab.SearchGroup.MaxSize"
GroupId="SPKings.Ribbon.CustomTab.SearchGroup"
Size="OneLarge"/>

<Scale Id="SPKings.Ribbon.CustomTab.SearchGroup.Scaling.CustomTabScaling"
GroupId="SPKings.Ribbon.CustomTab.SearchGroup"
Size="OneLarge" />

</Scaling>


Then we have defined scaling element. Scaling actually defines that how does a groups which are inside the tab scale based on the size of the window.

We have to make sure that we have to have N number of Maxsize and Scale element when we have N number of groups. As I have only one right now, I have one MaxSize and one Scale element. If you have three groups, then total will be six entries. Each MaxSize and Scale for each group.

Here we have mentioned in MaxSize and Scale that this refers to SearchGroup which we will have created in later part of XML. So this element is bound to that group. GroupID must be the same Id defined for the group.

<Group
Id="SPKings.Ribbon.CustomTab.SearchGroup"
Description="Different Search Engines"
Title="Search Engines"
Sequence="52"
Template="SearchEnginesGroup">


Now are adding groups to it. Here I have only one group, so it’s only one tag right now here we have given Id of the group, description, title and the sequence. These are self-explanatory part. Important attribute to note here is the template attribute. In earlier posts of this series, we used the built in template. Here we have defined our custom template. We can define our own layout and put controls inside that.

So we defined the layout later in xml. But as of now we need to give that template ID.

<Controls Id="SPKings.Ribbon.CustomTab.SearchGroup.Controls">

<Button
Id="SPKings.Ribbon.CustomTab.SearchGroup.SearchBingButton"
Sequence="15" Image16by16="/_layouts/images/CustomImages/Bing-logo.jpg"
Image32by32="/_layouts/images/CustomImages/bing.png"
Description="Click to see Bing message"
Command="btnGoToBingCommand"
LabelText="Bing"
TemplateAlias="BingSearch" />

</Controls>


Then in controls collection, we have defined one single button and set its attribute. Again how this button will render is based on the templatealias. That means when we define our custom layout we need to give alias to that template and mention here for the controls.

Till now we have added, controls into group, group into tabs. Now we need to define how they will appear. Hence we need to add templates to the ribbon now.

Declare another instance of UIDefinition. We have added now the template that we used earlier. We need to refer this template when using templateID given to the group. Now here what we want is because we have one single button, I would like to place it in a single row in a table. So just like how we use single TR element, in the same way I have defined one single table here its Section element and then single TR here its Row element and then referencing the button control here with the help of template alias. This means we want that button control to appear here. And we want that button to be displayed as a large control section.


<CommandUIHandlers>
<CommandUIHandler
Command="btnGoToBingCommand"
CommandAction="javascript: var statusId = SP.UI.Status.addStatus('This will take you to Bing search');
SP.UI.Status.setStatusPriColor(statusId, 'green');"></CommandUIHandler>

</CommandUIHandlers>

And after defining the template, we have defined the action that happens when button is clicked through the handlers. We have to give the command name which we mentioned in the button control and what happens when the button is clicked in the commandaction element.

Keep reading Part-6 to explore further.