NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Postback Event Handling

Web Forms provides a built-in event infrastructure that enables controls to capture and process postback form submits from a client. This enables control developers to better encapsulate functionality (for example, a calendar control could automatically handle the next month and previous month button events from the client, without requiring code on the ASP+ page to execute). It also enables control consumers to more intelligently interact with the controls (for example, a button control could capture a postback and then expose an OnServerClick event that it raised on the server when a client user clicked it).

Controls indicate that they are interested in capturing postback events by implementing the IPostBackEventHandler interface. Postback event notifications, which are indicated by a call to the IPostBackEventHandler.RaisePostBackEventmethod, can then be routed to the control in response to either a postback from a standard HTML form submit (that is, from something like a submit or image button), or as a result of a custom ECMAScript method that initiates a submit on the client.

Standard Form Submit Postback Handling

HTML supports two intrinsic tag controls—<input type=submit> and <input type=image>—that, when clicked, cause their containing form to be submitted to the server. Note that the name/value pair of one of these HTML elements is only included in the posted contents if it is the actual control initiating the submit; otherwise, its value is excluded. For example:

<form action="Test.aspx" method="GET">
   Name: <input type="text" name="Name">
   <input type=submit name="Button1">   |   <input type=submit name=Button2>
</form>

If Button1 is clicked on the above form, the following querystring will be posted:

   Test.aspx?name=scott&Button1

If Button2 is clicked on the above form, the following querystring will be posted:

   Test.aspx?name=scott&Button2

Web Form controls can easily render the intrinsic HTML types, setting each type's name property to that of its UniqueId, to capture postbacks on the server. For example:

public class MyButton : Control, IPostBackEventHandler {
   private EventHandler   clickHandler;

   // Register delegate to external "OnServerClick" event listener 
   public void AddOnServerClick(EventHandler value) {
      clickHandler = (EventHandler) Delegate.Combine(clickHandler, value);
   }

   // Remove delegate to external "OnServerClick" event listener 
   public void RemoveOnServerClick(EventHandler value) {
     clickHandler = (EventHandler) Delegate.Remove(clickHandler, value);
   }

   protected void OnServerClick(EventArgs e) {
     if (clickHandler != null) {
        clickHandler(this, EventArgs.Empty);
     }
   }

   // Process and raise appropriate incoming events
   public void RaisePostBackEvent(String eventArgument) {
     OnServerClick(EventArgs.Empty);
   }

   // Generate html button that will cause a postback to the control
   public override void Render(HTMLTextWriter output) {
     output.Write("<input type=submit name=" + this.UniqueId + ">");
   }
}

When a postback event on the page occurs, the page framework will iterate over every posted value in the appropriate form/querystring collection, searching for a control in the hierarchy tree that implements the IPostBackEventHandler interface and whose UniqueID matches the value key. If found, the page framework will invoke its RaisePostBackEvent method (passing null as the argument value). The server control is then free to do anything it wants and/or raise appropriate control events (for example, OnServerClick, OnMoveNext, OnCancel, and so on) to external listeners.