Creating a Web Part with Client-side Script
This programming task describes how to create a Web Part with client-side scripting.
About creating client-side scripts for Web Parts
Scripts are blocks of code that are inserted into a Web page and are interpreted at run time. Just like a browser interprets HTML on a Web page to determine what to display, a browser also interprets scripts to determine what actions to take when an event occurs (for example, what happens when a user clicks a button on a Web page).
Client-side scripts run on the client as opposed to the server. After a Web page is downloaded to the client computer, if the browser has enabled scripts to run, all the client-side scripts will run in the browser. Although script languages are simpler than programming languages, scripts can add sophisticated logic to Web pages and increase interactivity.
You can implement client-side scripting in a Web Part in one of two ways:
- Linking a script file to a Web Part
- Embedding a script in a Web Part
Linking a script file to a Web Part
You can write script in a separate file and place the file on a server running Microsoft Windows Server 2003 with Microsoft Windows SharePoint Services. The first time the script file is referenced, the file is fetched from the server and placed in the browser's cache. Subsequent references to the script file only require the script to be fetched from the browser's cache.
Advantages
- It is more efficient for different Web Parts and Web Part Pages to share script placed in a common script file because the script is only fetched from the server the first time it is referenced and subsequent references fetch the script from the browser's cache.
- The benefit is more obvious if the script is long. In this case, the Web Parts that reference the script are not burdened with the overhead of the lengthy script, and the script is only fetched once from the server and subsequently loaded into the browser's cache.
- Placing a complex script into a separate file is also organizationally more practical and easier to maintain than embedding the entire script in the Web Part class definition.
To Link a script file to a Web Part Embedding script in a Web Part
You can explicitly specify your script in a Web Part and have the script loaded only once for all instances of the same Web Part on a Web Part Page. The IsClientScriptBlockRegistered method of the System.Web.UI.Page class can check if the script has been loaded for the same Web Part Page.
Advantages
- Similar to linking to a script file, the script is loaded only once for all instance of the same Web Part on that Web Part Page.
- For short scripts, clarity and convenience outweigh performance gains.
To Embed a script in a Web Part For example, let us suppose that you have a script function called ByeBye() that you would like to add to your Web Part, WebPart_ClientScript. Add the following code so that the script is loaded only once for all instances of the same Web Part on the Web Part Page.
private const string ByeByeIncludeScriptKey = "myByeByeIncludeScript";
private const string EmbeddedScriptFormat =
"<script language=javascript>function ByeBye(){alert('Bye Bye'); }</script> ";
public WebPart_ClientScript()
{
this.PreRender += new EventHandler(WebPart_ClientScript_PreRender);
}
private void WebPart_ClientScript_PreRender(object sender , System.EventArgs e )
{
if(!Page.IsClientScriptBlockRegistered(ByeByeIncludeScriptKey))
Page.RegisterClientScriptBlock(ByeByeIncludeScriptKey,
EmbeddedScriptFormat);
}
Sample Web Part with client-side scripts
The following example shows how you can add two client-side scripts to a Web Part, WebPart_ClientScript, first by linking a separate script file to the Web Part, and then by embedding the script in the Web Part. The procedure assumes that you have a general understanding of how to create a Web Part programmatically. For information in this area, refer to the Creating a Basic Web Part programming task.
//---------------------------------------------------------------------
// File : WebPart_ClientScript.cs
//
// Purpose : Show an example of how to include client side script to your page.
// 1) Linking to a .js file
// 2) Added embedded script to the page.
//---------------------------------------------------------------------
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Xml.Serialization;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebPartPages;
namespace WebPartLibrary2
{
/// <summary>
/// Summary description for WebPart_ClientScript.
/// </summary>
[DefaultProperty("Text"),
ToolboxData("<{0}:WebPart_ClientScript runat=server></{0}:WebPart_ClientScript>"),
XmlRoot(Namespace="WebPartLibrary2")]
public class WebPart_ClientScript : Microsoft.SharePoint.WebPartPages.WebPart
{
private const string defaultText = "";
private string text = defaultText;
// Used for the linked script file
private const string HelloFileName = "myHello.js";
private const string HelloIncludeScriptKey = "myHelloIncludeScript";
private const string IncludeScriptFormat =
@"<script language=""{0}"" src=""{1}{2}""></script>";
// Used for the embedded script
private const string ByeByeIncludeScriptKey = "myByeByeIncludeScript";
private const string EmbeddedScriptFormat =
"<script language=javascript>function ByeBye(){alert('Bye Bye'); }</script> ";
// Contructor
public WebPart_ClientScript()
{
this.PreRender += new EventHandler(WebPart_ClientScript_PreRender);
}
[Browsable(true),Category("Miscellaneous"),
DefaultValue(defaultText),
WebPartStorage(Storage.Personal),
FriendlyName("Text"),Description("Text Property")]
public string Text
{
get
{
return text;
}
set
{
text = value;
}
}
/// <summary>
/// Gets the custom tool parts for this Web Part by overriding
/// the GetToolParts method of the WebPart base class. You must
/// implement custom tool parts in a separate class that
/// derives from
/// Microsoft.SharePoint.WebPartPages.ToolPart.
/// </summary>
///<returns>
/// An array of references to ToolPart objects.
///</returns>
// public override ToolPart[] GetToolParts()
// {
// ToolPart[] toolparts = new ToolPart[2];
// WebPartToolPart wptp = new WebPartToolPart();
// CustomPropertyToolPart custom = new CustomPropertyToolPart();
// toolparts[0] = custom;
// toolparts[1] = wptp;
// return toolparts;
// }
// Client script registration event
private void WebPart_ClientScript_PreRender(object sender , System.EventArgs e )
{
RegisterCommonScript();
}
//Function which will register the linked file script and the
//embedded script
protected void RegisterCommonScript()
{
string location = null;
// Make sure that the script was not already added to the
//page.
if (!Page.IsClientScriptBlockRegistered(HelloIncludeScriptKey))
{
location = this.ClassResourcePath + "/";
// Create the client script block.
string includeScript =
String.Format(IncludeScriptFormat, "javascript", location, HelloFileName);
Page.RegisterClientScriptBlock(HelloIncludeScriptKey, includeScript);
}
//Embedded Client Script
if(!Page.IsClientScriptBlockRegistered(ByeByeIncludeScriptKey))
Page.RegisterClientScriptBlock(ByeByeIncludeScriptKey,
EmbeddedScriptFormat);
}
/// <summary>
/// Render this Web Part to the output parameter specified.
/// </summary>
/// <param name="output">
/// The HTML writer to write out to
/// </param>
protected override void RenderWebPart(HtmlTextWriter output)
{
//Button which calls a function from the Included File .js
output.Write(
"<br><br><input class='ms-SPButton' value=\'Say Hello\' type=button onclick=\"Hello();\" >");
//Button which calls a function that is embedded in the page
output.Write(
"<br><br><input class='ms-SPButton' value=\'Say Bye Bye\' type=button onclick=\"ByeBye();\" >");
}
}
}
To deploy this sample Web Part Perform the steps described in the "Deploying Your Web" section of the Creating a Basic Web Part programming task, making sure to create a SafeControl block and a Web Part Definition file (.dwp) that reflects the appropriate values for your Web Part assembly and deploy the assembly in the GAC.