Client ScriptRelated API


Client Script “Related API

We will now examine the APIs in the page framework that provide the basic functionality needed to incorporate client-side behavior in your server controls.

Each control has a ClientID property that is generated by the page framework and is guaranteed to be unique across all controls within the page. The default implementation of WebControl renders the ClientID as the HTML id attribute on the primary tag rendered by the server control. ClientID is a script-friendly version of the UniqueID property and can be used in client script to programmatically access the HTML element rendered by the control.

The Page class provides a number of other methods to emit client-side script. A control should invoke these methods on its containing page in the PreRender phase by overriding the OnPreRender method, as shown in the HtmlEditor example later in the chapter. It is important to call these methods at the right time in the control life cycle. Calling these methods during the PreRender phase allows every control to inform the page about any client-side script that the page should render on the control's behalf . Subsequently in the Render phase, the page renders all the client-side script that it collected as a result of these methods. You should not call these methods from your control's Render method because the page has already completed a portion of its rendering before your control is called to render itself.

Table 13-1 lists the methods of the Page class that allow your control to generate client-script and include this script in the page's rendering.

Table 13-1. Methods Exposed by Page to Enable Client-Script Rendering  

Method

Description

RegisterClient ­ScriptBlock

void RegisterClientScriptBlock(string key, string script)

Allows you to emit the specified script block at the top of the page. Every script block is associated with a key. Every instance of your control on the page should use the same key. This allows the page to render the registered script a single time, even though it may be registered several times. The script is rendered before the control and therefore enables the control to refer to script methods implemented in the script block in event handlers for client-side events. The script block can contain embedded code or can be a reference to an external script file.

IsClientScript ­BlockRegistered

bool IsClientScriptBlockRegistered(string key)

Checks whether the specified script block has been registered. Strictly speaking, you do not need to call this method because registering the same script block multiple times is allowed, as described in the explanation of the RegisterClientScriptBlock method. However, you might find it useful to check whether the script block has been registered if generating the script block for registration purposes is expensive and time-consuming .

RegisterStartup ­Script

void RegisterStartupScript(string key, string script)

Shares the same semantics as the RegisterClientScriptBlock method. However, instead of rendering the script at the top of the page, this method renders the specified script block at the bottom of the page. This allows controls to generate script that needs to refer to the tags that the control renders into the page, which requires the tags to precede the script in the generated HTML. This method is especially useful for emitting inline script that executes as the document loads.

IsStartupScript ­Registered

bool IsStartupScriptRegistered(string key)

Shares the same semantics as the IsClientScriptBlockRegistered method.

RegisterArray ­Declaration

void RegisterArrayDeclaration(string arrayName, string arrayValue)

Allows your control to emit a value within the specified array. A page creates a single array variable in client script with the name given in arrayName which contains all the values registered with the same arrayName . This allows all instances of your control to add entries into a single array or list of values that can then be easily processed by client script that your control also generates.

RegisterHidden ­Field

void RegisterHiddenField(string hiddenFieldName, string initialValue)

Allows your control to render a hidden field that can be accessed by using client-side script to submit values back to the server when the page is submitted. Chapter 9, "Control Life Cycle, Events, and Postback," explains the details of handling postback data.

RegisterOn ­SubmitStatement

void RegisterOnSubmitStatement(string key, string script)

Registers the specified script statement to be executed when the page is submitted and allows your control's client-side behavior to participate in the submission process. The statement is executed as part of the onsubmit event of the <form> tag that is raised before the page is submitted to the server. The script statement is executed only once, even if it is registered multiple times (with the same key).

As you will see later in this chapter, the HtmlEditor sample control uses the RegisterClientScriptBlock , RegisterStartupScript , and RegisterArrayDeclaration methods in its implementation.



Developing Microsoft ASP. NET Server Controls and Components
Developing Microsoft ASP.NET Server Controls and Components (Pro-Developer)
ISBN: 0735615829
EAN: 2147483647
Year: 2005
Pages: 183

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net