Saturday, October 22, 2011

Creating a custom document library for SharePoint 2010

Introduction

It seems that it is not that obvious to find clear documentation to create a custom document library for SharePoint 2010.
Most of the Microsoft documentation is now based on using Visual Studio 2010 and are more focused on the lists than on the document libraries.

By the way document libraries in SharePoint 2010 seems to has become lists, but the lack of documentation regarding the creation of custom lists remains anyway, so after having perform some successful trials I have decided to publish a step by step guide.

Functional benefits

I won't spend much time in this post explaining the functional benefits of creating a custom document library because I plan to publish soon a new post explaining the difference between a custom list and a list instance and the functional benefits and drawbacks of each. But think carefully before creating a custom document library.
I have created one in a previous project for MOSS 2007 and had serious problems when migrating to SharePoint 2010.
In most of the cases, a list instance is enough so if it is possible, avoid creating a custom list or document library. In a general way, avoid as much as possible to create custom CAML definitions for sites, lists and so on... 

Required steps for creating a custom SharePoint 2010 document library

1 - Duplicate the native DocumentLibrary feature
2 - Change the attributes of the Feature tag of the Feature.xml file
3 - Change the attributes of the ListTemplate tag of the DocumentLibrary.xml file
4 - Rename the DocLib folder located in the DocumentLibrary folder
5 - Install the feature
6 - Activate the feature for a specific site
7 -Test

Detailed operations

1 - Duplicating the native DocumentLibrary feature

Locate the folder of th DocumentLibrary feature located in: C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\FEATURES
Copy and paste the folder and rename it. Assume we rename it MyCompany.MyCustomDocumentLibrary.

 

 

2 - Changing the attributes of the Feature tag of the Feature.xml file and adding some more attributes

Open the Feature.xml file with Visual Studio or a text editor, and change these attributes:

ID
Change the ID of the feature. I usually change the last figures by the new type of the list. Assume the new type is 10001 (it is not recommended to use a new type smaller than 10000), the new ID of the feature of my custom document library will be 00BFEA71-E717-4E80-AA17-D0C71B310001.

Title
The title will appear in the UI of SharePoint 2010 in the "Manage Site Features" page (because the attribute Scope is set to Web).

Description
The description will also appear in the UI of SharePoint 2010 in the "Manage Site Features" page (Because the attribute Scope is set to Web).

Hidden
Change the value of the attribute to FALSE in order to see the feature in the "Manage Features" page of your SharePoint 2010 so as you can activate it manually and allow a site administrator to activate it.

Add the following attributes

AlwaysForceInstall="TRUE"
This will avoid having an error at deployment time if you deploy this feature in a SharePoint solution (.wsp file) by retracting, removing the old version of your solution and re-deploying a new one.

ImageUrl
I have created a folder for MyCompany located in the SharePoint 2010 IMAGES folder located at:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\IMAGES
(I use a part of the SharePoint summit logo because I was speaker at this summit last year in Quebec and plan to be speaker on 2012 at Toronto and Quebec.)

Here is the new xml after the changes has been performed:

<?xml version="1.0" encoding="utf-8"?>
<
Feature Id="00BFEA71-E717-4E80-AA17-D0C71B310001"
                  Title="MyCompany MyCustom Document Library"
                  Description="Allow a custom document library to be created within this site"
                  Version="1.0.0.0"
                  Scope="Web"
                  Hidden="False"
                  AlwaysForceInstall ="TRUE"
                  ImageUrl ="MyCompany/sharePointSummitLogo.jpg"
                  DefaultResourceFile="core"
                 xmlns=http://schemas.microsoft.com/sharepoint/>
                 <
ElementManifests>
                          
<ElementManifest Location="ListTemplates\DocumentLibrary.xml" />
                 </
ElementManifests>
</
Feature>

 

3 - Changing the attributes of the ListTemplate tag of the DocumentLibrary.xml file

Name
This is the important key. This name and the name of the folder where the schema.xml file of the custom library is located MUST be the SAME !
I use customdoclib1

Type
As written before the new type will be 10001. The type can for example be used in a feature that will place a custom button in a document library ribbon so as when you activate the feature for the new button, only the document libraries with the 10001 type will have the new button. Changing the type is one of the good reasons to choose to create a custom document library rather to create a list instance. But it can also cause many problems later for example when migrating to a new version of SharePoint so be careful.
The base type will not be changed, BaseType 1 means the list is a document library...

DisplayName
This name will appear in your SharePoint site in the create page when you want to create a custom document library within your site.

Description
The description will appear in your SharePoint site below the display name in the create page when you want to create a custom document library within your site.

Here is the new xml after the changes has been performed:

<?xml version="1.0" encoding="utf-8"?>
<
Elements xmlns="http://schemas.microsoft.com/sharepoint/">
      <
ListTemplate
          Name="customdoclib1"
          Type="10001"
           BaseType="1"
           OnQuickLaunch="TRUE"
           SecurityBits="11"
           Sequence="110"
           DisplayName="My Company Document Library"
           Description="Create a document library with xyz functionalities"
           Image="/_layouts/images/itdl.png"
           DocumentTemplate="121"/>
</
Elements>

4 - Renaming the DocLib folder located in the DocumentLibrary folder

As written before, the important key is now to rename the folder where the document library schema.xml file is located so as it has the same name than the name attribute of the custom document library template.

So we rename the folder to customdoclib1

 

 

5 - Installing the feature

Now, all we have to do is install the feature so open a command prompt and be sure to have the administrator permissions on the machine. If the stsadm.exe path is referenced in the system variables of the machine you just have to type the following:

stsadm -o installfeature -name MyCompany.MyCustomDocumentLibrary

In order to obtain this screen

 

 

6 - Activating the feature for a specific site

So now, open a site and you should see your feature in the "Manage Site Features" page as shown in the next screen shot.

 

 

Notice that the description filled in the feature.xml file is displayed on the page.
Click the Activate button to enable the custom library creation within this site.

 

7 -Testing

Now if you navigate to the SharePoint 2010 Create pop up using the "Site Actions" menu and clicking "More Options..." then selecting Library in the pop up you will notice that the references to the custom library are actually displayed by the pop up.

Notice that the name and description typed previously in the documentlibrary.xml file are properly displayed.

So type a name for your new custom document library for SharePoint 2010 and check it is correctly provisioned within your site.

 

Well done !!!

3 comments:

Danny Bakker said...

Have you seen where after creating a custom document library, that when you are saving a document from Word (using "Save to SharePoint") to that library that the view of the library in the file dialog is blank? An OOTB doc lib will show you the column headings, files, and folders in there but the custom one will not.

Sreeni said...

Hi Marc,

really you’re blog more help ful for me .
I need some help/suggestions..
Present I am working BO with Xcelsius Dasboards using BI web services. So, I want to create Dashboards in Sharepoint usings with Webservices or any existing feature.
Could you please let me know.. is it possible ?

Thanks,
Sreeni.

Anonymous said...

Hi Marc,

really you’re blog more help ful for me .
I need some help/suggestions..
Present I am working BO with Xcelsius Dasboards using BI web services. So, I want to create Dashboards in Sharepoint usings with Webservices or any existing feature.
Could you please let me know.. is it possible ?

Thanks,
Sreeni.