Andrey Markeev on SharePoint

Add ribbon tab to all site pages using Fluent Ribbon API

October 24, 2011

Recently I've commited a piece of new code to my SharePoint 2010 Fluent Ribbon API opensource project. And I'm gratified to announce the new feature of the project: ability to create a RibbonControl, which can add a custom Ribbon Tab all over your site.

This capability can save you, if you need some functionality which should be shown up on all pages of your site. Common approach in this case is to use masterpage customizations, however, putting your customizations into a ribbon tab often could be considered much more felicitous. For example, we use RibbonControl in our real project at work for delivering users a fast interface for managing their workflow tasks.

An interesting point, which deserves attention here, is that you can adjust the tab if you need, hiding or replacing some controls, depending of current user or current page url or whatever. Also, you can hide your tab completely - for example, for popup dialogs.

All this functionality is very simple and obvious in terms of usage. All you need - is to create a delegate control, inherit it from RibbonControl class, and override two properties. SharePoint 2010 Fluent Ribbon API will take care about all that complex stuff like javascript page components, and will protect you from dealing with typo-prone XML.

Give me the code!

Let's have a look at the sample code:

public partial class TestRibbonControl : RibbonControl
{
    public override TabDefinition GetTabDefinition()
    {
        return new TabDefinition()
        {
            Id = "CommonTasks",
            Title = "Common tasks",
            Groups = new GroupDefinition[]
            {
                new GroupDefinition()
                {
                    Id = "Sample",
                    Title = "Sample",
                    Template = GroupTemplateLibrary.SimpleTemplate,
                    Controls = new ControlDefinition[]
                    {
                        ControlLibrary.CreateRandomButton()
                    }
                }
            }
        };
    }
}

All is very obvious here, I hope. We're inheriting our control from RibbonControl class, overriding its abstract method GetTabDefinition, and creating a sample tab titled "Common tasks" - intended for storing some frequent functionality for a portal user.

As a result, we will have our ribbon tab on all pages of the site:

How To

Actually, you need to perform several additional actions to get the result shown above.

  1. Create an Empty SharePoint Project.
  2. Add a reference to FluentRibbon.dll
  3. Open Package.package file, switch to Advanced tab, and add FluentRibbon.dll for deployment to GAC.
  4. Add a user control to your project, it will automatically appear in ControlTemplates SharePoint Mapped Folder.
  5. Add a delegate control item, enter "AdditionalPageHead" as ID of this control, and point it to your ascx file, as it shown on the screenshot below.

The DelegateControl project item type is from CKS:Dev plugin. If you don't have it installed, you can simply create any element (Module, for instance), and then replace contents of Elements.xml with the following code:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Control Id="AdditionalPageHead" ControlSrc="~/_controltemplates/FluentRibbon.DelegateControl/RibbonControlTest.ascx" />
</Elements>

Assure performing all the 5 steps stated above, then paste the sample code to your ascx.cs CodeBehind class, and finally, deploy!

What else can be done here?

For now, the example is rather limited, so for better understanding we can continue improving our solution. What can we do:

  1. With the current code, the custom tab will be shown everywhere, occasionally looking particularly clumsy, especially in popup dialogs. So, I assume it would be a good idea to remove the tab from popup windows.
  2. Different users often have different privilegies and hence, the interface must be changed correspondingly. To cover this situation, let's add additional button, only for portal administrators.

These tasks are very easy to accomplish, actually.

First of all, I have a special virtual property in the RibbonControl class, named DisplayTab. This property must return false, if the tab is not intended to be shown on the current page. To prevent the tab from displaying in popup dialogs, we need to write following code:

public override bool DisplayTab
{
    get
    {
        return !SPContext.Current.IsPopUI;
    }
}

Our second improvement is also obvious. The code will look like this:

public override TabDefinition GetTabDefinition()
{
    var controls = new List<ControlDefinition>();
    controls.Add(ControlLibrary.CreateRandomButton());
    if (SPContext.Current.Web.CurrentUser.IsSiteAdmin)
        controls.Add(ControlLibrary.CreateRandomButton());

    return new TabDefinition()
    {
        Id = "CommonTasks",
        Title = "Common tasks",
        Groups = new GroupDefinition[]
        {
            new GroupDefinition()
            {
                Id = "Sample",
                Title = "Sample",
                Template = GroupTemplateLibrary.SimpleTemplate,
                Controls = controls.ToArray()
            }
        }
    };
}

And that's all, you're done!

To use RibbonControl feature, you should download a new version of  the FlientRibbon.dll assembly. At the moment, it is in pre-release state.

Note 1: In examples above, I'm using ControlLibrary.CreateRandomButton method for clarity. In a real code, you should create particular buttons, using ButtonDefinition class or other control classes, like SplitButton or FlyoutAnchor. Their list and descriptions could be found on the Fluent Ribbon API documentation site.

Note 2: RibbonControl feature will not work for sandboxed solutions.

Like it?

Posts of this series

  1. Add ribbon tab to all site pages using Fluent Ribbon API (this post)
  2. SharePoint Ribbon ToggleButton: creating multiview pages

About me

I'm SharePoint MVP, published author, frequent speaker, opensource projects creator and online expert.

I'm one of the top 10 experts on SharePoint StackExchange:

profile for omlin at SharePoint, Q&A for SharePoint enthusiasts

You can learn more about me on LinkedIn and Facebook.

Want to follow?

Subscribe to RSS!

Twitter

Blog archive