Bamboo Nation
Your SharePoint Community - Powered by Bamboo Solutions

SharePoint 2010 Cookbook: How to Customize the Document Set Ribbon

SharePoint 2010 delivers a comprehensive set of document management features as well as improvements to the user interface.   In this article, we will take a look at a how to customize the Ribbon of the Document Set.

Challenge:

As previous articles in the SharePoint 2010 Cookbook series have shown, we are able to create and customize a Document Set to fit our business requirements.  Now, we would like to be able to also customize some of the user interface experience, especially the action icons of the Ribbon.

Is there a way to customize the Ribbon in the Document Set and add our own action menu?

Solution:

As you will see, the ability to customize the Ribbon for the Document Set is actually pretty straightforward.  One of the most frequently requested features of the Document Set is the ability to download the entire Document Set, which is not something that SharePoint 2010 provides out of the box.  Fortunately, Microsoft provides sample code here which shows how to do this. 

In this article, we will extend that sample by adding a new menu to download all files in the Document Set, check out selected files, check in selected files and send selected files as links.  We will walk through the example, and we will also provide a finished program and scripts that you can use to upload in your SharePoint server.

Step 1 - Add buttons to the Ribbon Set

To add a button to the Ribbon, you need to create a couple of XML files and place them in the Features folder of the SharePoint hive 14 directory, which is located here:  Program Files\common files\Microsoft shared\web server extensions\14\template\features by default.

In this example, I will create four buttons in a new group called "Bamboo Manage" to download all files in a Document Set as a ZIP file, send selected files as links, check out selected files, and check in selected files.

The first file is Element.xml, which is required to define the action menu in the Ribbon:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction
    Id="Ribbon.Documents.DocsetZip"
    Title="Document Set Example"
    RegistrationType="ContentType"
    RegistrationId="0x0120D520"
    Location="CommandUI.Ribbon"
    >
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition
          Location="Ribbon.ManageDocumentSet.MDS.Groups._children">
          <Group
            Id="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup"
            Sequence="61"
            Description="Bamboo Document Set Group"
            Title="Bamboo Manage"
            Template="Ribbon.Templates.Flexible2">
            <Controls Id="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.Controls">
              <Button
                Id="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.DownLoadAllAsZip"
                Command="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.DownLoadAllAsZip"
                Image16by16="/_layouts/images/menupersonalize.gif"
                Image32by32="/_layouts/images/menupersonalize.gif"
                LabelText="Download All"
                Alt="Download this folder as a zip file"
                Description="Download this folder as a zip file"
                TemplateAlias="o1"
                Sequence="1" />
              <Button
                Id="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.CheckOutTheseFiles"
                Sequence="2"
                Command="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.CheckOutTheseFiles"
                Alt="Check Out Selective"
                Image16by16="/_layouts/images/menupersonalize.gif"
                Image32by32="/_layouts/images/menupersonalize.gif"
                LabelText="Check Out Selective"
                ToolTipTitle="Check out multiple files"
                ToolTipDescription="Use this tool to check out multiple files and folder"
                TemplateAlias="o1"/>
              <Button
                Id="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.CheckInTheseFiles"
                Sequence="3"
                Command="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.CheckInTheseFiles"
                Alt="Check In Selective"
                Image16by16="/_layouts/images/menupersonalize.gif"
                Image32by32="/_layouts/images/menupersonalize.gif"
                LabelText="Check In Selective"
                ToolTipTitle="Check In Selective"
                ToolTipDescription="Use this tool to check in multiple files without comment."
                TemplateAlias="o1"/>
              <Button
               Id="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.SendTheseFiles"
               Sequence="3"
               Command="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.SendTheseFiles"
               Alt="Send Links Selective"
               Image16by16="/_layouts/images/menupersonalize.gif"
               Image32by32="/_layouts/images/menupersonalize.gif"
               LabelText="Send Links Selective"
               ToolTipTitle="Send Links Selective"
               ToolTipDescription="Use this tool to send mail all these items as link."
               TemplateAlias="o1"/>
            </Controls>
          </Group>
        </CommandUIDefinition>
        <CommandUIDefinition
            Location="Ribbon.ManageDocumentSet.MDS.Scaling._children">
          <MaxSize
            Id="Ribbon.ManageDocumentSet.MDS.Scaling.BambooDocSetGroup.MaxSize"
            Sequence="15"
            GroupId="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup"
            Size="LargeLarge" />
        </CommandUIDefinition>
        <CommandUIDefinition Location="Ribbon.Templates._children" >
          <GroupTemplate Id="Ribbon.Templates.Flexible2">
            <Layout Title="LargeLarge">
              <OverflowSection Type="OneRow" TemplateAlias="o1" DisplayMode="Large"/>
              <OverflowSection Type="OneRow" TemplateAlias="o2" DisplayMode="Large"/>
            </Layout>
            <Layout Title="LargeMedium">
              <OverflowSection Type="OneRow" TemplateAlias="o1" DisplayMode="Large"/>
              <OverflowSection Type="ThreeRow" TemplateAlias="o2" DisplayMode="Medium"/>
            </Layout>
            <Layout Title="LargeSmall">
              <OverflowSection Type="OneRow" TemplateAlias="o1" DisplayMode="Large"/>
              <OverflowSection Type="ThreeRow" TemplateAlias="o2" DisplayMode="Small"/>
            </Layout>
            <Layout Title="MediumLarge">
              <OverflowSection Type="ThreeRow" TemplateAlias="o1" DisplayMode="Medium"/>
              <OverflowSection Type="OneRow" TemplateAlias="o2" DisplayMode="Large"/>
            </Layout>
            <Layout Title="MediumMedium">
              <OverflowSection Type="ThreeRow" TemplateAlias="o1" DisplayMode="Medium"/>
              <OverflowSection Type="ThreeRow" TemplateAlias="o2" DisplayMode="Medium"/>
            </Layout>
            <Layout Title="MediumSmall">
              <OverflowSection Type="ThreeRow" TemplateAlias="o1" DisplayMode="Medium"/>
              <OverflowSection Type="ThreeRow" TemplateAlias="o2" DisplayMode="Small"/>
            </Layout>
            <Layout Title="SmallLarge">
              <OverflowSection Type="ThreeRow" TemplateAlias="o1" DisplayMode="Small"/>
              <OverflowSection Type="OneRow" TemplateAlias="o2" DisplayMode="Large"/>
            </Layout>
            <Layout Title="SmallMedium">
              <OverflowSection Type="ThreeRow" TemplateAlias="o1" DisplayMode="Small"/>
              <OverflowSection Type="ThreeRow" TemplateAlias="o2" DisplayMode="Medium"/>
            </Layout>
            <Layout Title="SmallSmall">
              <OverflowSection Type="ThreeRow" TemplateAlias="o1" DisplayMode="Small"/>
              <OverflowSection Type="ThreeRow" TemplateAlias="o2" DisplayMode="Small"/>
            </Layout>
            <Layout Title="Popup" LayoutTitle="LargeMedium" />
          </GroupTemplate>
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler
          Command="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.DownLoadAllAsZip"
          CommandAction="BLOCKED SCRIPT__doPostBack('DownloadZipDelegateEvent', '')"
          EnabledScript="BLOCKED SCRIPTsingleEnable();"/>
        <CommandUIHandler
          Command="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.CheckOutTheseFiles"
          CommandAction="BLOCKED SCRIPT__doPostBack('CheckOutTheseFiles', '')" 
          EnabledScript="BLOCKED SCRIPTsingleEnable();"/>
        <CommandUIHandler
          Command="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.SendTheseFiles"
          CommandAction="BLOCKED SCRIPT 
            var context = SP.ClientContext.get_current(); 
            var items = SP.ListOperation.Selection.getSelectedItems();
            var p_body = '';
            for(var k = 0; k &lt; items.length; k++) {
              var dv = document.getElementById(items[k]['id']);
              var tagsA = dv.getElementsByTagName('A');
              p_body += tagsA[0].href + '\n';
            }
            SP.Ribbon.EMailLink.openMailerWithUrl(p_body);
          "
          EnabledScript="BLOCKED SCRIPTsingleEnable();"/>
        <CommandUIHandler
          Command="Ribbon.ManageDocumentSet.MDS.BambooDocSetGroup.CheckInTheseFiles"
          CommandAction="BLOCKED SCRIPT__doPostBack('CheckInAllTheseFiles', '')" 
          EnabledScript="BLOCKED SCRIPTsingleEnable();"/>
      </CommandUIHandlers>
    </CommandUIExtension>
  </CustomAction>
  <Control Id="GlobalSiteLink0" Sequence="90"
    ControlClass="Bamboo.DocSetExample.DownloadAsZip"
    ControlAssembly="Bamboo.DocSetExample, Version=1.0.0.0, Culture=neutral, >
            PublicKeyToken=972e48e7af0d9424"
    <Property Name="IsVisible">false</Property>
  </Control>
</Elements>

 

Step 2 - Provide the code to handle these menu actions

In the supplied sample program, you can unzip the file Bamboo.DocSetExample.zip.  This is a Visual Studio project file that implements the bulk download.  You can modify this code to suit your own needs.  The output of this project is a DLL that the action menu shown above will call to perform the bulk download from the new menu above.

using System;
using Microsoft.SharePoint;
using Microsoft.Office.DocumentManagement.DocumentSets;
using System.Web.UI.WebControls;
 
namespace Bamboo.DocSetExample
{
    public class DownloadAsZip: WebControl
    { 
        protected override void OnLoad(EventArgs e)
        {
           this.EnsureChildControls();
           base.OnLoad(e);
        
        if (this.Page.Request["__EVENTTARGET"] == "DownloadZipDelegateEvent")
            {
                SPListItem currentItem = SPContext.Current.ListItem;
                this.Page.Response.ContentType = "application/zip";
                DocumentSet currentDocset = DocumentSet.GetDocumentSet(currentItem.Folder);
                currentDocset.Export(this.Page.Response.OutputStream, 1024);
                this.Page.Response.End();
            }
            else if (this.Page.Request["__EVENTTARGET"] == "CheckOutTheseFiles")
            {
                SPListItem currentItem = SPContext.Current.ListItem;
                foreach (SPFile file in currentItem.Folder.Files)
                {
                    if (file.CheckOutType == SPFile.SPCheckOutType.None)
                    {
                        file.CheckOut();
                    }
                }
            }
            else if (this.Page.Request["__EVENTTARGET"] == "CheckInAllTheseFiles")
            {
                SPListItem currentItem = SPContext.Current.ListItem;
                foreach (SPFile file in currentItem.Folder.Files)
                {
                    if (file.CheckOutType != SPFile.SPCheckOutType.None)
                    {
                        file.CheckIn(string.Empty);
                    }
                }
             }
        }
    }
}

If you modify this code, make sure to get the compiled DLL into the package of Bamboo.DocSetExample. Exception for Send selective files as link uses Client Object Modal to perform the action, and the remaining functions are in the code behind, and are complied to a DLL. This DLL will be installed into the GAC when we install the feature.

<Control Id="GlobalSiteLink0" Sequence="90"
    ControlClass="Bamboo.DocSetExample.DownloadAsZip"
    ControlAssembly="Bamboo.DocSetExample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=972e48e7af0d9424">
    <Property Name="IsVisible">false</Property>
  </Control>

The ID of this control is a controlid of the SharePoint Delegate control which typically has already been designed in the site master page. If SharePoint found the Element, these controls will render as HTML on the page like a normal Web Part. So, the position of the Web Part is also important. 'AdditionalPageHead' is a controlid of a SharePoint delegate control which is inserted into the <HEAD> tag so that the Web Part will render in the <HEAD> tag.  In this example, I will put my Web Part in GlobalSiteLink0 and hide the Web Part by setting the IsVisible property to False.

For more about SharePoint Delegate Control, click here.

Step 3 - Installation

From our downloaded ZIP file, just unzip the content on your server and run the InstallSample.bat file to install everything on your SharePoint farm.  Follow these steps:

  1. Unzip our sample file
  2. Edit the InstallSample.bat, replace this part with your server name, and the path where you've installed SharePoint server
  3. Run command line as Administrator, change the current path to the path including file InstallSample.bat
  4. Type the command: InstallSample.bat <Site_URL> (Site_URL is the URL of the site which configured Document Set to activate the feature)

Alternately, you can perform the following commands

  • stsadm.exe -o installfeature -name "Bamboo.DocSetExample" -force
  • stsadm.exe -o activatefeature -name "Bamboo.DocSetExample" -url ">http://<server>

The DocumentSet Web Part must also declare in web.config, which is typically at C:\inetpub\wwwroot\wss\VirtualDirectories\[port].  Edit the web.confog and then add this line before the end of </SafeControls> tag:

<SafeControl Assembly="Bamboo.DocSetExample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=972e48e7af0d9424" Namespace="Bamboo.DocSetExample" TypeName="*" Safe="True" SafeAgainstScript="True" />   

Step 4 - Try It

Once the installation has completed, you should be able to see the menu in the Ribbon of the Document Set:

11-9-2010 8-42-04 PM

Notes:

  • Document Set is only available in SharePoint 2010 Server and is not part of the SharePoint Foundation 2010.
  • In order to install and run this sample program, you must have Farm Admin and Local Admin rights on the SharePoint server in order to modify the web.config and run the stsadm command.

See Also:

Posted Nov 12 2010, 01:00 PM by Hai Tuan Nguyen
Filed under: , , , ,

Comments

Conor wrote re: SharePoint 2010 Cookbook: How to Customize the Document Set Ribbon
on Wed, Nov 17 2010 6:21 AM

Excellent technical SharePoint blog. The instructions are really clear. Something to take inspiration from for our own blog!

Hai Tuan Nguyen wrote re: SharePoint 2010 Cookbook: How to Customize the Document Set Ribbon
on Wed, Nov 17 2010 7:35 AM

Thanks Connor.

Add a Comment

Please sign into Bamboo Nation to leave a comment.

About Hai Tuan Nguyen

I am a SharePointer, belong to Bamboo Nation Smile, and straying in the big wide desert of SharePoint. I am the founder of SharePointVietNam.NET community for Vietnamese Developers and Administrators who are working on SharePoint technology. With over 3 years of experience in SharePoint configuring and developing, I have finally understood what the Collaboration is in SharePoint. However, I am still improving my knowledge and sharing all things on my community site. Please visit my site at SharePointVietNam.NET  and share everything with us and help us to improve the SharePoint Tech in Viet Nam.

Bamboo Solutions Corporation, 2002-2012