Sunday, 10 March 2013

SharePoint Ribbon Customization

Ribbon is one of the new features introduced in SharePoint 2010. After office client, Microsoft introduced ribbon in the similar fashion in SharePoint.

Ribbon in SharePoint 2010 provides the common place for most of the controls that you will need, Ribbon  is divided into basic four sections as shown in Fig 1 below.

1. Tab
2. Group
3. Controls
4. Contexual Tab

The architecture of Ribbon allows you to customize by creating xml files.

Inorder to understand how SharePoint implements its Ribbon, there is a XML element file at
%Program Files %\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\GLOBAL\XML\CMDUI.XML

If you open this xml file, you will see that its a huge file. Don't get afraid with this huge file.
Lets understand how SharePoint implements the Ribbon functionality.

The main element in the "CMDUI.xml" file is the "CommandUI" element, this element holds all the controls and the templates for the Ribbon.

Ribbon element holds all the controls like Tabs, Group, Controls, Contextual Tab.

Templates element has GroupTemplate element. Each GroupTemplate element specifies the mode in which the controls within that group will be rendered.

As you can see in the ribbon image Fig 1, some of the controls are rendered as large icons whereas  others like "Page History", "Delete Page" etc. (under Manage group) are rendered in medium size icons. All of these are controlled by GroupTemplate element.

Now, Lets have a close look at Ribbon element. Ribbon element has two child elements "Tabs" and "ContexualTabs". Each of these element further has Groups and Controls element which hold the html contols like label, textbox , combobox, dropdown. etc.

I hope you have got the clear understanding of the CMDUI.xml file.

Now lets try to customize the ribbon. In this example I am going to add the caption to the table when a user inserts the table into the page. 

When a user edits the page and inserts the table into the page, "Table Tools" contextual tab shown below is displayed. What I am trying to achieve using this custom control is, when user enters some text into this highlighted textbox and hits save,  I am adding the Caption child element to the table. This is achieved by specifying the custom .js code into the command handler element.

Adding any custom controls into the ribbon can be achieved by creating custom action element.xml file in SharePoint 2010.

The CustomAction element has two main elements: CommandUIDefinitions and CommandUIHandlers.

CommandUIDefinitions hold all the custom controls definitions and the CommansUIHandlers hold the actions against each controls.

There are few things to keep in mind.
CustomAction Location="CommandUI.Ribbon" -  tells SharePoint that you are adding controls into the Ribbon.

CommandUIDefination Location="Ribbon.Table.Layout.Summary.Controls._children" - tells SharePoint that the controls need to be added into the "Ribbon.Table" contextual tab under "Layout" tab under "Properties" group.

Command attribute of the control is the place you specify what action you need when a user clicks on the control. Action is specified in the CommandUIHandler element. In my example I am adding the caption element to the table.

QueryCommand attribute of the control is fired when the page is rendered. Action is specified in the CommandUIHandler element. In my example I am fetching the caption element of the table and storing into the textbox.

There are few .js files for Ribbon which are present at 14 Hive layouts folder. These files hold the actions (CommandUIHandler) part of the ribbon.

For Rich Text Editor : "SP.UI.RTE.js"
For Publishing Site Rich Text Editor:  "SP.UI.RTE.Publishing.js"

Hope you find this blog useful.

Isha Jain

1 comment: