Integrating Custom Components with Sharepoint 2007

Recently I worked on a partner project that integrated a third party search engine with Sharepoint (MOSS) 2007.  The most interesting use case in the project was to construct a custom component to replace the search bar in the Sharepoint site page headers.  The component was to be designed to access the third party search engine, which had been configured to crawl the Sharepoint content store.

It's an interesting use case because, in general, Sharepoint is not designed to easily integrate components into the Master Pages that govern the header display.  Sharepoint readily accepts Webpart components into the content areas of the pages, but the Master pages are not Webpart enabled.  Also, there is already a default search bar incorporated into the Master Page header as a ContentPlaceHolder, and it doesn't go away easily.  The project was even more interesting because I used the Microsoft Ajax Toolkit in my custom component.  As you might know, MOSS does not natively support Ajax in the current release.  Taken together, all of these challenges promised an interesting development effort.

I started by creating a Webpart.  Why, you might ask?  Well the project would ultimately need a Webpart for context based search within the site pages.  And Webparts are more easily integrated into Sharepoint, which gave me an opportunity to test the third party search engine connectivity in a straightforward implementation.  Of course, I built Ajax UpdatePanel functionality into the Webpart, which made the installation into Sharepoint non-trivial, but I'll get to that later.  The Webpart installed pretty much without issue and worked as designed.  Now it was time to convert the Webpart into a regular component so that it could be used in the Master Page.

I had several false starts in doing the conversion.  I first thought that a user control would be the thing to do.  Sharepoint supports dropping user controls (as .ascx files) into the page layouts and using them.  However, user controls have some drawbacks in terms of reusability because a user control actually becomes part of the web site source code, rather than being in a DLL that is reused across web sites (ref. http://support.microsoft.com/kb/893667).  So then I decided that an Ajax enabled Custom Control would be the thing to do.  So I started a Custom Control project only to discover that there is a significant amount of re-write involved in putting Webpart source code into the Custom Control framework.  After several frustrating hours, I decided to try something else.  Some googling revealed the existence of the Composite Control class, which could be compiled as a DLL, and which shared its base class with the Webpart class.  This made porting the code much more straightforward.  In about four hours, I had the code ported and was ready to install the component into the Sharepoint framework for testing.

If you have installed custom components or Webparts into Sharepoint, you probably know that it is non-trivial.  Here are the major steps involved for most any deployment:

1) Stop IIS, drop your component DLL and any dependent DLLs into the _app_bin for your website, then restart IIS

2) In the base directory for your Sharepoint site, modify the web.config to include your control in the Safe Controls list.  Typically that code looks like this;
<SafeControl Assembly="VelocitySearchWebPart,
             Version=1.0.0.0, Culture=neutral,
             PublicKeyToken=bc2316305294cfc7"
             Namespace="VelocitySearchWebPart"
             TypeName="SearchWebPart" Safe="True" />
Remember that you will need to have compiled your component with strong naming turned on, and you will need to know the GUID that was assigned to your component at compile time.  I use .NET Reflector to retrieve the GUID because it's so simple to use.  You just drop the component into it and the GUID is revealed in the properties.

3) If you used Ajax like I did, you need to modify the web.config to support Ajax also.  This can be done using these instructions:
http://sharepoint.microsoft.com/blogs/mike/Lists/Posts/Post.aspx?ID=3
Don't forget that you need to drop the AjaxControlToolkit.dll in with your DLL above, otherwise the ajax controls will fail at runtime and Sharepoint won't like that at all.
ALSO NOTE:  The version numbers in the instructions on the web site referenced in this step are wrong.  You need to change all version numbers to 3.5.0.0 in the web.config entries for the Ajax assemblies.

Now these next steps apply only to replacing the search component in the Master Page for Sharepoint.

4) Add a script manager into the Sharepoint Master Page by
a) logging into the Sharepoint site that you want to modify as an Administrator.
b) Then go to Site Actions/Site Settings/Galleries/Master Pages and Page Layouts
c) Choose the Master Page that is being used by the site and edit it in the Sharepoint Designer
d) Add this line of code just under the webpartmanager in the Master Page
    FIND THIS:  <WebPartPages:SPWebPartManager id="m" runat="Server"/>
    ADD THIS: <asp:ScriptManager runat="server" ID="ScriptManager1"></asp:ScriptManager>

5) Hide the default search box in the Master Page
a) While editing the master page above, find the Search Content Area
    <asp:ContentPlaceHolder id="PlaceHolderSearchArea" runat="server">
b) Add Visible="false" to this place holder
    <asp:ContentPlaceHolder id="PlaceHolderSearchArea" runat="server" Visible="False">

6) Add your component into the Master Page
a) While editing the master page above, insert your component as a table just
below the content area that you just made invisible
  <td style="padding-top:8px;" valign=top>
    <asp:ContentPlaceHolder id="PlaceHolderSearchArea" runat="server" Visible="False">
    <SharePoint:DelegateControl runat="server" ControlId="SmallSearchInputBox"/>
    </asp:ContentPlaceHolder>
            <cc1:SearchControlCGI ID="SearchControlCGI1" runat="server" />
  </td>
b) At the top of the page, register cc1 as your component
   <%@ Register assembly="VelocitySearchControlCGI" namespace="VelocitySearchControlCGI" tagprefix="cc1" %>

7) Fix the Sharepoint CSS file to add styles for your component (if necessary)
a) Create a text file with the correct styles inside of it and name it *.css.
      I have created captech.css and saved it to the desktop
b) In your site, go to Site Actions/Manage Structure and Content
c) Find the Style Library/en-US/Core Styles
d) Upload your .css file
e) Drop down the context menu beside the new file and check it in
f) Drop down the context menu beside the new file and publish it
g) Go to Site Actions/Site Settings/Modify All Settings
h) Open the Master Page under Look and Feel
i)  Scroll to the bottom of the page, and select your .css file as the alternate css for the page

That's it.  Your component should show up in the Master Page header on your sites.  There is one thing to keep in mind when adding components to the Master Page.  You won't be able to modify the settings for the component dynamically like you can a Webpart.  This is one of the code changes that you have to make.  I suggest using the web.config to store your application settings.  The .NET AppSettings class makes it easy to get to them, and they are secured by IIS.

I had fun modifying Sharepoint to use my custom component and Webpart.  I hope you found this post useful.  If you have questions or comments, feel free to post them or drop me an e-mail at wsmith@captechventures.com.