Extending the Connect To menu item

Introduction

In my last two posts I discussed how third party clients can most efficiently synchronize with Windows SharePoint Services 3.0 In this article I look into extending the “Connect To… ” menu item. The “Connect To… ” menu item is extensible so that any client can make use of it.

Extending the “Connect To” menu item

Client applications must do two things in order for the Connect To menu item to be displayed:

1. Register the stssync:// protocol handler

2. Install an ActiveX control that returns the application name and an icon filename

 

More information about registering protocol handlers is available from http://msdn.microsoft.com/workshop/networking/pluggable/overview/appendix\_a.asp.

The ActiveX control must have a ProgID of SharePoint.Stssynchandler.3 and implement the following methods:

 

HRESULT GetStssyncAppNameForType([in] BSTR pbstrType, [out, retval] BSTR *pbstrAppName);

HRESULT GetStssyncIconName([out, retval] BSTR *pbstrIconName);

 

Before displaying the menu item, SharePoint calls the GetStssyncAppNameForType() method in the ActiveX control and passes in the current list’s sync type. Each list has a default sync type (accessed in the object model at SPList.SyncType) based on its base type, base template, and whether it allows content types. This type can be overridden as an attribute of the list template definition in a feature.

Typically, the ActiveX control checks the sync type against a list of supported types and returns the name of the application to display in the menu item, or null if the type is not supported – in which case the menu item is not displayed.

 

If a non-null application name is returned, SharePoint then calls the control’s GetStssyncIconName() method to get the filename of an icon to display in the menu item. The filename returned is used in the context menu for document library folders, while the “menu” prefix is added to the filename to get the image used in the toolbar menu item. Thus, clients should install two images in the images path of each SharePoint web front end – foo.gif and menufoo.gif.

 

If the browser does not support Active X, (Windows Internet Explorer 5 and later), we display the “Connect To…” menu with a default icon and assume that the stssync protocol is supported.

 

When the button is clicked, JavaScript redirects the browser to an stssync:// URL with the right context parameters. The URL is formatted as follows:

 

stssync://sts/?ver=1.1&type=Type&cmd=add-folder&base-url=WebUrl&list-url=ListUrl&guid=ListId&site-name=SiteName&list-name=ListName

 

Parameter Descriptions

Type

The sync type for this list

WebUrl

an absolute, encoded URL to the web on which the list is found

ViewUrl

a web-relative, encoded URL (starting with /) to the list’s default view page

ListUrl

a web-relative, encoded URL (starting and ending with /) to the list

ListId

the list’s GUID

SiteName

the title of the web on which the list is found, up to 20 characters long

ListName

the title of the list, up to 20 characters long

 

Document libraries may add two parameters to the end of the stssync:// URL when syncing a folder:

 

&folder-url=FolderUrl&folder-id=FolderId

 

Type

The sync type for this list

FolderUrl

a web-relative, unencoded URL (starting with /) to the context folder

FolderId

the item ID (an integer) of the context folder

 

Acknowledgements

Once again, I would like to acknowledge Matt Swann (Microsoft Corporation) and Bill Snead (Microsoft Corporation) for their gracious help in technical reviews of this material.

 See Also

http://blogs.msdn.com/sharepointdeveloperdocs/archive/2008/01/21/synchronizing-with-windows-sharepoint-services-part-1.aspx

http://blogs.msdn.com/sharepointdeveloperdocs/archive/2008/01/22/synchronizing-with-windows-sharepoint-services-part-2.aspx