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 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 Filescommon filesMicrosoft sharedweb server extensions14templatefeatures 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"
Image1616="/_layouts/images/menupersonalize.gif"
Image3232="/_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"
Image1616="/_layouts/images/menupersonalize.gif"
Image3232="/_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"
Image1616="/_layouts/images/menupersonalize.gif"
Image3232="/_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"
Image1616="/_layouts/images/menupersonalize.gif"
Image3232="/_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 < 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 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:
- Unzip our sample file
- Edit the InstallSample.bat, replace this part with your server name, and the path where you’ve installed SharePoint server
- Run command line as Administrator, change the current path to the path including file InstallSample.bat
- 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:inetpubwwwrootwssVirtualDirectories[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:
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:
- Document Sets for a Document Library [Bamboo Nation]
- How to Customize the Document Set Content Type [Bamboo Nation]
- How to Customize the Welcome Page of a Document Set [Bamboo Nation]
- How to: Customize the Document Set Ribbon [MSDN]
- Delegate Control (Control Templatization) [MSDN]
Excellent technical SharePoint blog. The instructions are really clear. Something to take inspiration from for our own blog!
Thanks Connor.
