Customizing the SharePoint Ribbon: C# sample

If you’ve used SharePoint, I’m sure the first thing you would’ve noticed is the Ribbon UI. The SharePoint ribbon provides users with a familiar Office user interface and it is also extensible for developers. This means developers can add their own tabs, groups and controls to the ribbon.

In this post I’ll show you how to create your own simple tab and elements for the tab in SharePoint 2010. If your pc is not set up for SharePoint 2010 development yet, read my last post Setting up your PC for SharePoint 2010 development.

Let’s get started by creating a new Empty SharePoint Project in Visual Studio 2010. You can find the project template under Visual C# > SharePoint > 2010.

The SharePoint Customization Wizard will start. Validate the site address to make sure you’re using the correct site for debugging and select Deploy as a sandboxed solution. Selecting this option will allow us to deploy this customization to Office 365 as well as a local instance of SharePoint.

We’ll add our own tab to any page that contains a list view, to do this we need to add a feature. To add a feature right-click on the Features folder and select Add Feature.

Change the feature title to My Custom Ribbon.

In the Solution Explorer select Feature1 in the Features folder and rename it to MyRibbon. The solution explorer should now look like this:

Next add a new Empty Element item to the project and call it MyCustomRibbonTab.

After you’ve added the Empty Element, the Elements.xml file will open and the Solution Explorer should look like this:

The Elments.xml file will be used to define the Ribbon Tab layout. But I have to warn you that the xml can turn into a bit of a nightmare. First, we need to define an extension to the user interface. To do this you’ll add a CustomAction section to the xml file.

<CustomAction
    Id="ADXSampleRibbonTab"
    Location="CommandUI.Ribbon.ListView"
    RegistrationId="101"
    RegistrationType="List">
  </CustomAction>

The Id attribute is not required, however, it is a good idea to include it as it is used to uniquely identify the custom action. Location specifies the location for the custom action – in this case it will be on any Listview pages’ ribbon. You can see a list of custom action locations in the SharePoint 2010 SDK or on MSDN. The RegistrationType attribute specifies the registration attachment for per item actions. The possible values for it are:

• List
• ContentType
• ProgId
• FileType
• None

The following mark-up will add a ribbon tab with two buttons, two textboxes as well as logic that will show a modal dialogue with the SharePoint calendar when the user clicks the one button. And if the user clicks the other button, the total numbers in the two textboxes will be displayed.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <CustomAction
    Id="ADXSampleRibbonTab"
    Location="CommandUI.Ribbon.ListView"
    RegistrationId="101"
    RegistrationType="List">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition
          Location="Ribbon.Tabs._children">
          <Tab
            Id="Ribbon.ADXSampleTab"
            Title="ADX Sample Tab"
            Description="A Sample Tab"
            Sequence="501">
            <Scaling
              Id="Ribbon.ADXSampleTab.Scaling">
              <MaxSize
                Id="Ribbon.ADXSampleTab.MaxSize"
                GroupId="Ribbon.ADXSampleTab.CalendarGroup"
                Size="OneLargeTwoMedium"/>
              <Scale
                Id="Ribbon.ADXSampleTab.Scaling.SampleTabScaling"
                GroupId="Ribbon.ADXSampleTab.CalendarGroup"
                Size="OneLargeTwoMedium" />
            </Scaling>
            <Groups Id="Ribbon.ADXSampleTab.Groups">
              <Group
                Id="Ribbon.ADXSampleTab.CalendarGroup"
                Description="This is a the calendar shortcut group."
                Title="Calendar Shortcut"
                Sequence="52"
                Template="Ribbon.Templates.CustomTemplateExample">
                <Controls Id="Ribbon.ADXSampleTab.CalendarGroup.Controls">
                  <Button
                    Id="Ribbon.ADXSampleTab.CalendarGroup.ShowCalendar"
                    Command="ADXSampleTab.ShowCalendarCommand"
                    Description="Displays the SharePoint calendar"
                    LabelText="Show Calendar"
                    TemplateAlias="cust1" />
                  <TextBox
                    Id="Ribbon.ADXSampleTab.CalendarGroup.NumberOne"
                    ImeEnabled="true"
                    MaxLength="20"
                    ShowAsLabel="false"
                    TemplateAlias="cust2"
                    ToolTipTitle="Text"
                    ToolTipDescription="Text"
                    ToolTipHelpKeyWord="Text"
                    ToolTipShortcutKey="Text"
                    Width="100" />
                  <TextBox
                    Id="Ribbon.ADXSampleTab.CalendarGroup.NumberTwo"
                    ImeEnabled="true"
                    MaxLength="20"
                    ShowAsLabel="false"
                    TemplateAlias="cust3"
                    ToolTipTitle="Text"
                    ToolTipDescription="Text"
                    ToolTipHelpKeyWord="Text"
                    ToolTipShortcutKey="Text"
                    Width="100" />
                  <Button
                    Id="Ribbon.ADXSampleTab.CalendarGroup.AddNumbers"
                    Command="ADXSampleTab.AddNumbersCommand"
                    Description="Add the two numbers"
                    LabelText="Add"
                    TemplateAlias="cust4" />
                </Controls>
              </Group>
            </Groups>
          </Tab>
        </CommandUIDefinition>
        <CommandUIDefinition Location="Ribbon.Templates._children">
          <GroupTemplate Id="Ribbon.Templates.CustomTemplateExample">
            <Layout
              Title="OneLargeTwoMedium"
              LayoutTitle="OneLargeTwoMedium">
              <Section Alignment="Top" Type="OneRow">
                <Row>
                  <ControlRef DisplayMode="Large" TemplateAlias="cust1" />
                </Row>
              </Section>
              <Section Alignment="Top" Type="TwoRow">
                <Row>
                  <ControlRef DisplayMode="Medium" TemplateAlias="cust2" />
                </Row>
                <Row>
                  <ControlRef DisplayMode="Medium" TemplateAlias="cust3" />
                </Row>
              </Section>
              <Section Alignment="Top" Type="OneRow">
                <Row>
                  <ControlRef DisplayMode="Large" TemplateAlias="cust4" />
                </Row>
              </Section>
            </Layout>
          </GroupTemplate>
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler
          Command="ADXSampleTab.ShowCalendarCommand"
          CommandAction="javascript: 
              var options = {              
                url: '../../Lists/Calendar/calendar.aspx',
                tite: 'ADX Modal Calendar',
                allowMaximize: false,
                showClose: true,
                width: 600,
                height: 400};              
              SP.UI.ModalDialog.showModalDialog(options);" />
        <CommandUIHandler
          Command="ADXSampleTab.AddNumbersCommand"
          CommandAction="javascript:            
              var textNumberOne=document.getElementById('Ribbon.ADXSampleTab.CalendarGroup.NumberOne');
              var textNumberTwo=document.getElementById('Ribbon.ADXSampleTab.CalendarGroup.NumberTwo');
              var numberOne = parseInt(textNumberOne.value);
              var numberTwo = parseInt(textNumberTwo.value);
              var total = numberOne + numberTwo;              
              alert('The total is ' + total);          
          " />
      </CommandUIHandlers>
    </CommandUIExtension>
  </CustomAction>
</Elements>

As you can see it takes a lot of XML to generate just a few elements. You’ll notice two <CommandUIDefinition> sections where one is used to specify the Tab, it’s scaling, groups and controls. It has a relatively easy hierarchy to understand which you will recognise as it is similar to Microsoft Office’s ribbon. The <Scaling> section is used to specify how the tab will resize and display on different resolutions.

It is important that each control has a unique ID, I found the best way to do this is using a namespace approach e.g. Ribbon.ADXSampleTab.CalendarGroup.ShowCalendar. You’ll also notice that the button controls have a Command attribute. This command is declared further down in the XML in the <CommandUIHandlers> section.

The CommandAction attribute of the CommandHandler node can contain any JavaScript. In this example I showed the standard SharePoint calendar in a modal dialog using the built-in SharePoint API and by using plain vanilla JavaScript I added the number in the two textboxes and displayed the result using a JavaScript alert.

Once the XML is in place, you can build and run the project. In your SharePoint test site navigate to any list page (for example a document library) and you should see the custom tab.

When you click on the Show Calendar button a modal dialog will be displayed with the SharePoint Calendar.

Entering numbers in the two textboxes and clicking the Add button will display a JavaScript alert with the total:

Deploying the SharePoint ribbon to Office 365

Now that we have our solution we need to deploy it to Office 365. Visual Studio makes this very easy, all you need to do is right-click the project in Solution Explorer and choose Package. This will create a .wsp file which you would need to upload to Office 365. To do this, log into your Office 365 account and navigate to the Site Settings page and click on Solutions under Galleries

Click the Upload Solution button on the Solutions tab and upload the .wsp file. Once it is uploaded you need to activate it by selecting it in the list of solutions and clicking on the Activate button. If all went well, you should see your new tab when browsing to a page that contains a list.

Phew! That took some doing. I have barely scratched the surface of what can be done with the ribbon but I suggest you work through the SharePoint SDK as well as some examples available on the web.

Thank you for reading. Until next time, keep coding!

Available downloads:

C# sample project

You may also be interested in:

• SharePoint Ribbon customization with Ribbon Designer
• Video: Ribbon Designer for SharePoint and Office 365
• Video: Ribbon Designer for SharePoint and Office 365, end-to-end demo