This documentation is archived and is not being maintained.

Web Part Page Services Component (WPSC) Overview

SharePoint 2003

The Web Part Page Services Component (WPSC) adds dynamic capabilities to your Web Part Page by providing Web Part discovery, notification, and state management services used by Web Parts. It is a client-side component that is rendered as a client-side ECMAScript (JScript, JavaScript) component.

The WPSC is structured as an object model for ease of programming. Following is a simple diagram of the WPSC object model.

Web Part Page Services Component object model hierarchy

You can write code against the WPSC to support deeper integration of Web Parts or to manipulate your Web Part Page. For example, you can build applications composed of related Web Parts that respond to events in other Web Parts or change titles and captions at run time. You can also think of WPSC as a set of services where each service describes a type of functionality that Web Parts need. For more information about this set of services, see WPSC services later in this topic.

The WPSC is part of the Web Part infrastructure. The component installs with the Web Part infrastructure when you install Microsoft® Windows® SharePoint™ Services. At run time, the infrastructure embeds a WPSC instance on a Web Part Page, where it provides key services at the Web Part and Web Part Page levels.

The WPSC is available as two Microsoft JScript® files—one that supports Microsoft Internet Explorer 5.0, and another that supports Internet Explorer 5.5 and later. At run time, the Web Part infrastructure detects the browser type and provides the appropriate version during Web Part Page rendering.

The functionality of the Web Part Page Services Component (WPSC) is organized into services. There are multiple services, and each one defines a scope of functionality that targets a specific purpose. For example, the Web Part Discovery Service enables Web Parts to detect other Web Parts at run time, and the Web Part Notification Service sends and receives information about events occurring in various Web Parts or on a Web Part Page. A WPSC service is really a semantic creation—there is no binary aspect to a specific service.

A single JScript file (IE50UP.JS or IE55UP.JS) contains functionality for all WPSC services. By itself, a service is just a way to identify a set of objects, collections, methods, and properties to use if you want to accomplish a specific goal. Any given object can play a role in numerous services. No object or collection is restricted to a specific service, and no object or collection encapsulates a service.

Following are the three services provided by WPSC:

  • Web Part Discovery Service

    The Web Part Discovery Service provides a way for Web Parts to determine the presence of other Web Parts at run time, enabling you to create dependencies between Web Parts or to dynamically change a Web Part based on the state of another Web Part.

    The Web Part Discovery Service detects whether other Web Parts are present in the Parts collection of the Web Part Page. After you determine that a Web Part is available, you can check its state and use the results to determine how you want a Web Part or Web Part Page to respond.

    The Web Part Discovery Service enables the following scenario: Let's say you want to make an Order Web Part dependent upon a Customer Web Part, so that the Order Web Part is displayed only when the Customer Web Part is available. By enumerating the Parts collection, you can determine whether both are on the page. You can then check the Web Part state to determine a further course of action. For example, if Order is read/write, Customer is read/write. To use the Web Part Discovery service, you use the WPSC object, the WebPartPage object, the Parts collection, and one or more Part objects.

  • Web Part Notification Service

    The Web Part Notification Service provides a standard multicast event mechanism for Web Parts that hides the complexity of the underlying event mechanisms of the Web browser, such as DHTML events. Through the Web Part Notification Service, Web Parts can register for an event, and then provide a function that is called when the registered event runs. Events occur if an object changes state. Such objects can be system objects (that is, static objects that have a fixed name, such as the WebPartPage object or the Parts collection), or custom objects that you define (for example, Customers or Contacts).

    The scope of an event is a namespace that defines a context for the event. A Web Part can raise an event or respond to an event. Separating these two roles enables the coordination of Web Parts on a page. System and custom events are handled in the same way, which means that scripts can be simpler and Web Parts more encapsulated. It also makes it possible to surface session events from the browser or operating system.

  • State Management Service

    The State Management Service provides the ability to access and modify the built-in and custom properties of a Web Part from the client at run time. The state of a Web Part is the combination of standard Web Part properties and any user-defined or system-defined extensions. For example, a Web Part that displays a stock ticker must be able to save and retrieve customization information between sessions. In this case, the stock symbols the user selects are private data. This data and the values from the Web Part schema that you specify constitute the state of the Web Part.

    The State Management Service deals with state information for a particular Web Part. All access to a Web Part Page and Web Parts through the Parts collection retrieves state information based on the current view of the page. If you are in Personal mode, personalized information is retrieved; if you are in Shared mode, global information is retrieved. It is important to note that state information, whether personalized or global, is stored with the Web Part. If you delete a Web Part, its state information is lost.

A number of the WPSC features require communication back to the server. These are features such as saving or retrieving a property. The following illustration defines how information is exchanged between the various applications when a property is saved to the database.

Web Part Page Services Component data flow

When the Save() method is executed within a Web Part, the WPSC interacts with the SharePoint database using the WebPartPages Web Service. The WPSC passes all properties that were previously set on the client to the SharePoint database. The WebPartPages Web Service connects to the database and stores the property values.

The Web Part Page Services Component (WPSC) is an object model that you can use to script against a Web Part Page and the Web Parts it contains. When the client accesses a Web Part Page for the first time, the WPSC component is added to the client computer.

Name conflicts

When you script using the WPSC, use unique namespaces or tokens to avoid name conflicts. You can use namespaces or tokens for Web Part events, names, messages, and states to eliminate the risk of naming conflicts. You can also use variables and elements provided by the Web Part infrastructure when the page is rendered.

Using tokens

Tokens are placeholders for values that can be determined at run time. You can append predefined tokens to named entities in your code to simplify scripting and avoid naming conflicts. At render time, the Web Part infrastructure replaces the tokens with values until all tokens for the page are replaced. Tokens are case-insensitive, and they can appear anywhere in the name (that is, as a prefix, suffix, or in the middle of a variable).

Token replacement is one of the better strategies for avoiding name conflicts. At design time, you add a token to Web Part names, embedded content, or linked content. At run time, the Web Part infrastructure replaces the token with a generated value that guarantees the unique naming of the item in question. For example, you can include _WPQ_ as a prefix to HTML IDs and function names. At render time, the Web Part infrastructure converts this literal string to the WebPartQualifier.

The following table lists the predefined tokens in alphabetical order.

Token name Replacement value
_LogonUser_ Value retrieved from the Request.ServerVariables("LOGON_USER") of an ASP page. This value typically contains the domain and user name from the client and can be used for user identification within an intranet.
_WPID_ The GUID of a Web Part instance in g_ format, for example, g_632c887a_20ba_4e6d_98eb_7404ee4841f. This token provides a unique ID within the page.
_WPQ_ The unique ID of a Web Part within a Web Part Page. You can use this token to qualify HTML IDs and script function names to avoid name conflicts.
_WPR_ The URL of the resource folder for the Web Part on the server, not on the client.

Referring to Web Parts using varPart and WebPart

When a Web Part Page is rendered, Web Parts are assigned variables and element identifiers by the WebPartPage Web Service. You can have Web Parts refer to themselves by using these variables and element identifiers in combination with tokens in client-side script.

  • varPart

    Towards the end of the Web Part Page page loading process, each Web Part on the Web Part Page is assigned a variable (for example, varPartWPQ1). This variable points to the WPSC Part object for the Web Part. A Web Part can use this variable to refer to itself in embedded content using the _WPQ_ token. While it is possible to hard-code the variable (for example, refer to varPartWPQ2 in code instead of varPart_WPQ_), you could run into difficulties when the Web Part qualifier changes. There is no guarantee the Web Part qualifier for a Web Part will remain the same as the Web Part Page changes. Adding and renaming Web Parts can affect the order of the parts in storage, which can affect the Web Part qualifier and the value represented by the _WPQ_ token. It is best to use the _WPQ_ token where possible.

  • WebPart

    When the Web Part Page page is loaded, the Web Part is rendered on the page as a DIV element. This element is given an identifier by the Web Part infrastructure (for example, WebPartWPQ1). You can use this identifier to manipulate the HTML DOM for the Web Part by combining WebPart with the _WPQ_ token. Thus, the Web Part can refer to its own HTML structure by using WebPart_WPQ_. Care must be taken when manipulating the HTML DOM of a Web Part Page. Changes to the DOM structure of the Web Part or of the Web Part Page itself can affect your browser's behavior. The safest and most common use of WebPart_WPQ_ is to manipulate the InnerHTML for the Web Part or for elements within the Web Part. You can use script to update InnerHTML with data generated by the script.

Element references in a form

All Web Parts in a Web Part Page are contained within a form. This is because Web Part Pages are essentially ASPX pages. HTML requires every element in a form to be prefixed with a form ID or referenced using document.all. Following is a short example:

<form id="MyForm">
<input type="text" id="MyText">
<input type="button" id="MyButton" onclick="buttonClicked">

function buttonClicked()
   MyForm.MyText.value="Hello World!";

As an alternative, the line of code in this function could also read

document.all("MyText").value="Hello World!";

Either of these two options are acceptable. Note that this is only an issue if an <INPUT> tag is being used.

Web Parts can be registered to receive notifications for standard system events triggered in the browser. Because the browser supports only a single callback function for events, it is better that Web Parts register for system events rather than try to provide an event handler directly. Support for system events varies depending on whether the browser type is Microsoft Internet Explorer 5.5 or an HTML 3.2 browser.

The following table lists the events that are provided automatically by the Web Part infrastructure. The NamespaceURN property is "urn:schemas-microsoft-com:dhtml".

Event name Description Browser support
onafterprint Runs on the Window object immediately after its associated document prints. Internet Explorer 5.5
onbeforeprint Runs on the Window object before its associated document prints. Internet Explorer 5.5
onbeforeunload Runs before a page is unloaded. Internet Explorer 5.5
onblur Runs when the Window object loses the input focus. Internet Explorer 5.5
onclick Runs when a mouse click is detected in the browser window. Internet Explorer 5.5
onfocus Runs when the Window object receives the focus. Internet Explorer 5.5
onhelp Runs when the user presses the F1 key while the browser is the active window. Internet Explorer 5.5
onload Runs immediately after the browser loads the Window object. Internet Explorer 5.5
onresize Runs when the user changes the size of the Window object. Internet Explorer 5.5
onunload Runs immediately before the Window object is unloaded. Internet Explorer 5.5