Client-side Programming Using the WPSC
Applies to: SharePoint Foundation 2010
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. The component applies to Web Parts derived from the Microsoft.SharePoint.WebPartPages.WebPart class, but not to Web Parts derived from the System.Web.UI.WebControls.WebParts.WebPart class of ASP.NET.
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 SharePoint Foundation 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 SharePoint Foundation 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 property.
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 ASPX 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 make Web Parts refer to themselves by using these variables and element identifiers in combination with tokens in client-side script.
varPart
Toward 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 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_. Take care 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">
<script>
function buttonClicked()
{
MyForm.MyText.value="Hello World!";
}
</script>
</form>
As an alternative, the line of code in this function could also read:
document.all("MyText").value="Hello World!";
Either of these two options is acceptable.
Note
This is an issue only if an <INPUT> tag is being used.