Retaining attachment functionality when using the Custom List Form Control in SharePoint 2007 / WSS 3.0

If you have found this post then you are just one of many people who have been frustrated by a ‘feature’ in SharePoint 2007 (or WSS 3.0) whereby you lose the Attachment functionality if you replace the standard list form control with the Custom list form control within SharePoint Designer. I recently ran into this problem while trying to dress-up some standard forms in my SharePoint deployment.

Like many of you I searched the Internet & tried many of the user-inspired workarounds. But I could not find any usable solution. So I spent a week working with Microsoft – who acknowledged the problem exists – but no solution was forthcoming. Finally I got a hold of our account representative and laid into him about this issue and the lack of a workaround. Well, 3 phone calls later followed by an Impact Analysis (and a bit of groveling) I managed to get an unsupported workaround out of Redmond.

I’ve managed to clean the process up a bit – hopefully it will go smoothly for you. That being said – here is the usual disclaimer: This is an unsupported workaround – no warranties or guarantees. Always backup your system before making a change of this nature.

And to be safe – here is the official disclaimer from Microsoft. Just so we are clear:

 Important Disclaimer: The information contained in this document is not supported under any Microsoft™ standard support program or service, and is provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the information contained in this document remains with you. In no event shall Microsoft, its authors, or anyone else involved in the implementation or configuration of the information contained in this document be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the information contained in this document, even if Microsoft has been advised of the possibility of such damages.

OK – Let’s get started.

First – a very brief understanding of the problem. WSS 3.0 does not implement the SharePoint custom list form control properly. The code blocks for the Attach File functionality are missing when the page is rendered in SharePoint. Many users have tried to reverse engineer the missing pieces with limited success. This workaround implements a new DLL which takes the place of the missing functionality.

Prerequisites

1.       You will need the following files from my SkyDrive Public folder:

a.       http://cid-6d5649bcab6a7f93.skydrive.live.com/self.aspx/Public/SPDataSourceEx.zip

b.      http://cid-6d5649bcab6a7f93.skydrive.live.com/self.aspx/Public/SPXSLT_BLOCK1.txt

c.       http://cid-6d5649bcab6a7f93.skydrive.live.com/self.aspx/Public/SPXSLT_BLOCK2.txt

2.       You will need Visual Studio 2005 or Visual Studio 2005 Express Edition to rebuild the solution provided in the ZIP file above. A precompiled DLL is included in the ZIP file if you experience problems building it.

3.       You will need access to the SharePoint Server(s) to install a DLL into the Global Assembly Cache.

4.       You will need the .NET Framework 2.0 SDK installed or the ability to drop the DLL into the Windows\Assembly folder.

Actions to be performed on the Server(s)

1.       Download the ZIP file to a computer that has Visual Studio 2005 installed and rebuild the Solution using the ‘Release Configuration’. The resulting DLL will be in the ‘\SPDataSourceEx\bin\Release’ folder: SPDataSourceEx.DLL

2.       Install the SPDataSourceEx.DLL into the Global Assembly Cache of the SharePoint Servers. You can use GACUTIL.EXE or you can copy the file directly into the \Windows\Assembly folder from the server console. Be sure to install the DLL on all of the SharePoint servers in the farm.

3.       Once the DLL is installed in the GAC you will need to register it as a Safe Control for the SharePoint web application. Add the following line to the web.config file:

<SafeControl Assembly="SPDataSourceEx, Version=1.0.0.0, Culture=neutral, PublicKeyToken=78678792a547c409" Namespace="SharePoint" TypeName="*" Safe="True" AllowRemoteDesigner="True"/>

Note: Be sure you modify the correct web.config file. SharePoint servers have a number of web.config files depending on the number of sites and SSPs. Also – make sure each server’s web.config file is the same (if you have more than one SharePoint server).

4.       Perform an IISRESET on all servers in the farm.

Actions to be performed within SharePoint Designer 2007

1.       Open a list within SharePoint Designer that you want to modify. These steps will need to be performed on any page that you use the Custom List Form Control and desire the Attachment functionality to work as advertised. For this example we’ll be working with the NewForm.aspx file. Only minor differences from these instructions are needed for the EditForm.aspx file and they are noted inline. The DispForm.aspx edits are easier and will be described at the end of this document.

2.       Open the NewForm.aspx file for the list you want to customize.

3.       Right-click on the ListFormWebPart and click ‘Web Part Properties’. Expand ‘Layouts’ and select ‘Close the Web Part’ and ‘Hidden’. Click OK to close. This step is VERY IMPORTANT. You DO NOT want to delete the existing ListFormWebPart from the page. Doing so will cause SharePoint to detach the page from the navigation system and you will not be able to fix it short of deleting the list, restoring the content database, or restoring the list if you happen to have a recovery tool that can recover individual lists.

4.       Add the following directive to the top of the page under the existing directives:

<%@ Register tagPrefix="BoADataSource" Namespace="SharePoint" Assembly="SPDataSourceEx, Version=1.0.0.0, Culture=neutral, PublicKeyToken=78678792a547c409" %>

5.       Now we are ready to insert the Custom List Form. Position the cursor immediately below the now disabled ListFormWebPart and click on Insert, SharePoint Controls, Custom List Form. Select the correct List, and choose New Item Form (or Edit Item Form if modifying the EditForm.aspx file)

6.       Switch to Code View. Use Find/Replace to change ‘SharePoint:SPDataSource’ to ‘BoADataSource:SPDataSourceEx’.

Note: If after replacing this string the Custom Form control fails to render when switching back to Design View, save the file and close SharePoint Designer. Then reopen the file. If the control continues to generate a rendering error you can switch the string back to its original value for the remainder of the steps and change it at the end before testing. This may also indicate that the DLL is not registered properly on the server(s) – verify the web.config file and be sure to do an IISRESET. Then restart SharePoint Designer.

7.       The next several steps involve modifying several XSL code blocks within the Custom List Form control. This is best done in Code View. Rather than clutter this document with XSL that won’t cut & paste cleanly I have put the changed code in SPXSLT_BLOCK1.TXT. Find the indicated block and replace it with the modified code.

Note: The XSLT code needs to have the ControlMode set to “New” for the custom New Item form and “Edit” for the custom Edit Item form. It is currently set to “New”.

8.       Now we are going to add an extra table row to display the attachments dynamically after they’ve been added. This section will not be visible on the published form until a file has been attached. Use ‘Find’ to locate the following line of code:

<xsl:if test="$dvt_1_automode = '1'" ddwrt:cf_ignore="1">

Paste the code block in SPXSLT_BLOCK2.TXT directly above this line.

Note 1: The XSLT code needs to have the ControlMode set to “New” for the custom New Item form and “Edit” for the custom Edit Item form. It is currently set to “New”. Additionally, in the __designer.bind attribute, the first parameter for the ddwrtDataBind Function should be set to ‘i’ for the custom New Item form and ‘u’ for the custom Edit Item form.

Note 2: After saving the file with the modified code, you may notice the Script section changes slightly. This is normal.

9.       If you ran into the rendering problem from Step 6, replace that string now and save the file. If all went well, you can create a new item in your list and attach a file just as you normally would if the page was still using the standard list form control.

10.   Now you can go back to your modified page and customize the control as you see fit – i.e. moving items around, hide unwanted fields, etc.

Custom List Form for DispForm.aspx

To add attachment functionality to the DispForm.aspx (or any other Display form) do the following:

1.       Open SharePoint Designer 2007; Click on File, Open Site and connect to your SharePoint Site.

2.       Browse to the desired list, expand out ‘Lists’, and open DispForm.aspx (or another Display Form)

3.       Right-click on the ListFormWebPart and click ‘Web Part Properties’. Expand ‘Layouts’ and select ‘Hidden’. Click OK to close. This step is VERY IMPORTANT. You DO NOT want to delete the existing ListFormWebPart from the page. Doing so will cause SharePoint to detach the page from the navigation system and you will not be able to fix it short of deleting the list, restoring the content database, or restoring the list if you happen to have a recovery tool that can recover individual lists.

4.       Now we are ready to insert the Custom List Form. Position the cursor immediately below the now hidden ListFormWebPart and click on Insert, SharePoint Controls, Custom List Form. Select the correct List, and choose Display Item Form.

5.       Depending on where you want the Attachments to display – put your cursor in a table cell within the custom form control and right-click, Insert, Row Below. There should now be a new table row with two columns.

6.       Put the cursor in the left table cell of the new row and type ‘Attachments’.

7.       Now put the cursor in the right table cell of the new row; goto Code View, and paste the following line:

<SharePoint:AttachmentsField ControlMode="Display" FieldName="Attachments" runat="server" Visible="true"/>

8.       Save the file and test.

Some Known Issues and Workarounds

1.       You might see an error in rendering the SharePoint:AttachmentUpload control (usually appears below the custom form). This is a benign rendering issue and should not affect the functioning of the page outside of SharePoint Designer.

2.       When you close and open the site – the first time you open the custom list form control – you might see that the controls do not render. If you close and reopen the page again the control should start rendering properly.

3.       If you make more changes to the page you might see that SharePoint Designer automatically tries to add a unique ID to the attachment code that was added. This may cause some JavaScript errors in the page when browsing. If this happens, you will find the ‘<tr id=”idAttachmentsRow”>’ line being changed to ‘<tr id=”idAttachmentsRow{generate-id}”>’. You can safely delete the {generate-id} tag that gets added. This should resolve the JavaScript error.

4.       You may (i.e. probably will) see this error message: “The data source control failed to execute the insert command” when trying to submit the form in the browser. To resolve it, do one or both of the following:

a.       Check Step 6 above. This error can be caused by the DLL not being registered properly. If you had to skip Step 6 earlier – you may still have this problem.

b.      Try moving the Custom List Form control outside of the web part zone. Place it directly after the </WebPartPages:WebPartZone> tag.

5.       Remember – you do not want to delete the existing ListFormWebPart control. Doing so will cause all kinds of problems that will result in you deleting the entire list. Please, backup your content database. You will thank me later.

Well that is it. I’m glad to say that the above solution resolved my Attachment issue with the Custom List Form control. I hope it can help you. Oh – and the official word from Redmond is that this ‘behavior’ will not be fixed in the current version of SharePoint. Now I truly appreciate Microsoft releasing this workaround to me. But there are so many other people having this problem that to not publish a workaround (even an unsupported one like many fixes are) is a disservice – especially since they’ve had this workaround since December 2007. Ok, rant over. Peace.

UPDATE: I'd like to thank Mike Mongeau for posting about this issue (and this workaround) on the SharePoint Designer Support Team Blog (http://blogs.msdn.com/spdsupport/archive/2008/04/29/cat-s-out-of-the-bag-how-to-get-back-attachment-functionality-with-custom-list-forms.aspx). It is definately good to hear that a real fix may be in the works. I fully agree with Mike that a supported fix is the best solution, and while this workaround is not very elegant, it does seem to work. So again, thanks to whoever (presumably Mike's team) developed the workaround and I look forward to seeing the official fix in the future.

Microsoft, SharePoint, WSS, and SharePoint Designer are trademarks of Microsoft Corporation. All other trademarks are the property of their respective companies.