Protocols for Communicating Between Windows SharePoint Services and an Online Web Part Gallery
Updated: August 2004
Microsoft® Windows® SharePoint™ Services
Microsoft Office SharePoint Portal Server 2003
Summary: Understand how the Windows SharePoint Services protocols communicate with the remote server that hosts an online Web Part gallery. (4 printed pages)
Microsoft® Windows® SharePoint™ Services provides four different types of Web Part galleries for delivering Web Parts to end users:
- A Web Part Page gallery that is a list of all Web Parts currently used on a specific Web Part Page.
- A site collection Web Part gallery that is a list of Web Parts added to a particular site collection.
- A server Web Part gallery that is a list of Web Parts added to a particular server.
- An online Web Part gallery that is a list of ready-to-use Web Parts available from a global service, such as the online Web Part gallery available on the Microsoft Web site.
When you connect to an online Web Part gallery, Windows SharePoint Services makes an HTTP request to the remote server that hosts the Web Part gallery. When the remote server receives the HTTP request, it uses the criteria contained in the request to perform a search operation and sends back a response. Windows SharePoint Services then displays the search results in the Add Web Parts tool pane. When you add a Web Part to a page, you may be prompted to agree to an End User Licensing Agreement (EULA). After you accept the EULA, Windows SharePoint Services retrieves the .dwp file that describes the Web Part from the remote server and adds the Web Part to the page.
Important Windows SharePoint Services requires the Online Galley Web service to be anonymously accessible. Therefore, the remote server hosting this service must have anonymous access enabled in Microsoft Internet Information Services (IIS).
If your organization runs Windows SharePoint Services on multiple servers, you may want to create an online Web Part gallery as a central location for deploying Web Parts to all of your SharePoint sites.
To build an online Web Part gallery, configure Windows SharePoint Services to point at the server that hosts the gallery. To do this, use an XML editor or a text editor to modify the Web.Config file located in the local_drive:\inetpub\wwwroot directory. In the Web.Config file, locate the OnlineLibrary node, which appears similar to the following sample:
Change the value of the Url attribute in the OnlineLibrary node to point to the server that hosts the Web Part gallery.
To build a Web Part gallery, you must understand how Windows SharePoint Services communicates with the remote server.
Step 1: Returning Search Results
The first exchange of information between Windows SharePoint Services and the remote server is when Windows SharePoint Services sends search information to the remote server, and the remote server sends back a list of Web Parts.
Windows SharePoint Services uses a form post with a null AssetID query parameter to send search information to the remote server. The remote server should be configured to handle the form fields described in the following table.
|Keywords||The search terms that Windows SharePoint Services send to the remote server. For browse operations, this field is null.|
|LCID||The locale ID of the current page or site.|
|maxResults||The number of results to return at a time.|
|startAt||The index among the search results from which to begin returning results.|
When the remote server receives this information, it uses its own search logic to return the Web Parts, using keywords to rank results from startAt to (startAt + maxResults + 1) and returning the results in the following format:
<Results count=count> <Details xmlns="urn:schemas-microsoft-com:office:AWS"> <AssetID>AssetID</AssetID> <Title>Title</Title> <EulaUrl>EulaAssetID</EulaUrl> <EulaVersion>EulaVersion</EulaVersion> <AssetDescription>Description</AssetDescription> </Details> </Results>
The following table describes the attributes and elements returned by the remote server.
|Attribute or Element||Description|
|Results||The Results element should contain a Details element for each Web Part which ranks from startAt to (startAt + maxResults + 1) given the search criteria.|
|Count||The total number of results which the remote server has found fitting the search criteria.|
|Details||The Details element describes a single search result.|
|AssetID||This is the unique identifier on the remote server of the search result in question.|
|Title||This is the title of the search result in question. It appears in the Add Web Parts tool pane.|
|EulaUrl||This is the unique identifier on the remote server of the EULA associated with the search result in question. If no EULA is required, it is empty.|
|EulaVersion||This is the version stamp of the EULA associated with the search result in question. If no EULA is required, it is empty.|
|AssetDescription||This is the description of the search result in question. It appears as a hover-tip in the Add Web Parts tool pane.|
Step 2: Returning the EULA (Optional)
After Windows SharePoint Services receives the results from the remote server, you can add a Web Part to your Web Part Page. If the EulaVersion attribute or the EulaUrl attribute contains information, Windows SharePoint Services sends the following request to the remote server
where http://server/page is the address for the remote server specified in the Web.Config file and EulaUrl is the value of the EulaUrl attribute for the selected Web Part.
The remote server returns an HTML page that contains the text of the EULA. If the user accepts the EULA, the Web Part is added to the Web Part Page.
Step 3: Returning the Web Part
When the user accepts the EULA, Windows SharePoint Services makes the following request to the remote server
where http://server/page is the address for the remote server specified in the Web.Config file and AssetID is the value of the AssetID attribute for the selected Web Part.
The remote server returns the XML for the Web Part in .dwp format, and the Web Part is added to the Web Part Page.
Windows SharePoint Services provides four different types of Web Part galleries for delivering Web Parts to end users. You can create a custom Web Part gallery to meet your deployment requirements. You can scope your Web Part gallery to a specific page, to a site collection, to a server, or make it accessible across an entire deployment depending on your requirements. In addition, you can determine whether or not to require users to accept a EULA when adding a Web Part to a Web Part Page.