How to: Customize a Delegate Control

Applies to: SharePoint Foundation 2010

This example shows the basic process of creating and implementing a delegate control. The delegate control resides in the AdditionalPageHead control on the page. It registers some ECMAScript (JavaScript, JScript) on the page.

To build the delegate control

1. Start SharePoint development tools in Microsoft Visual Studio 2010.

2. On the File menu, point to New, and then click Project.

3. In Project Types, under Visual Basic or C#, select Empty SharePoint Project.

4. Type EcmaScriptDelegate as the project name. Click OK.

5. In the SharePoint Customization Wizard, choose Deploy as a farm solution. Click Finish.

6. In the Solution Explorer, right-click the EcmaScriptDelegate project. Select Add and then New Item.

7. In the Add New Item dialog box, click the Code group and choose the Class template. Type EcmaScriptDelegateControl as the Name and then click Add.

8. Next, you must add a reference to System.Web. In the Solution Explorer, right-click the References folder and select Add Reference. In the Add Reference dialog, click the .NET tab and find System.Web in the list. Click OK.

9. In the EcmaScriptDelegateControl file that is displayed, add the following using statement.

   using System.Web.UI.WebControls;
   

   Imports System.Web.UI.WebControls
   

10. Change the base class of EcmaScriptDelegateControl to WebControl by modifying the following line.

    class EcmaScriptDelegateControl : WebControl
    

    Public Class EcmaScriptDelegateControl
      Inherits WebControl
    

11. Override the OnLoad method by adding the following code.

    protected override void OnLoad(EventArgs e)
    {
      base.OnLoad(e);
    }
    

    Protected Overrides Sub OnLoad(ByVal e As System.EventArgs)
      MyBase.OnLoad(e)
    End Sub
    

12. Inside the OnLoad method, add the following code to put JavaScript on the page.

      string helloAlert = "alert('Hello, world!');";
      this.Page.ClientScript.RegisterClientScriptBlock(this.GetType(), "popup", helloAlert, true);
    

      Dim helloAlert As String = "alert('Hello, world!');"
      Me.Page.ClientScript.RegisterClientScriptBlock(Me.GetType(), "popup", helloAlert, True)
    

Now, you have built the delegate control for the project. Next, you will create the Feature to deploy the control.

To create a Feature to deploy the control

1. In the Solution Explorer, right-click the EcmaScriptDelegate project and select Add and then New Item.

2. In the Add New Item dialog box, choose the Empty Element template and type EcmaScriptDelegateFeature as the Name. Click Add.

3. Insert the following XML inside the Elements element. The Id attribute identifies the delegate where the control is rendered. The ControlAssembly and ControlClass attributes are unique to your control. For more information about how to find the full assembly name, see How to: Create a Tool to Get the Full Name of an Assembly.

   <Control Id="AdditionalPageHead" ControlAssembly="EcmaScriptDelegate, Version=1.0.0.0, Culture=neutral, PublicKeyToken=public key token" ControlClass="EcmaScriptDelegate.EcmaScriptDelegateControl">
   

You now have both the control and the Feature you need to deploy the control. Controls require a SafeControl entry in the web.config file in order to run on the page. The following procedure adds a SafeControl entry for your control.

To add a SafeControl entry

1. In the Solution Explorer, click EcmaScriptDelegateFeature and click ... in the Safe Control Entries property.

2. Click Add in the Safe Control Entries dialog.

3. In the Properties box, ensure that the Namespace property is the correct value. This is the namespace of your control. Also, ensure that the Safe property is set to true. Click OK.

Now that the SafeControl entry is added, you can deploy the solution.

To deploy and test the delegate control

1. Press F5 to run the solution.

2. When the page loads, a dialog box appears that says Hello, world!. This is the script that the delegate control has added to the page.

See Also

Reference

DelegateControl

Concepts

Delegate Control (Control Templatization)

Delegate Controls