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 https://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