IPostBackDataHandler and Postback Data

and Postback Data"-->

IPostBackDataHandler and Postback Data

We'll now look at the postback data processing architecture that enables a control to retrieve form data submitted by a user , update its state, and raise events in response to changes in its state. To participate in postback data processing, a control must implement the IPostBackDataHandler interface and render elements whose HTML name attributes have unique values on the page. The IPostBackDataHandler interface has the following two methods :

 publicinterfaceIPostBackDataHandler{ boolLoadPostData(stringpostDataKey, NameValueCollectionpostCollection); voidRaisePostDataChangedEvent(); } 

In the Load Postback Data phase, which occurs before the Load phase (as shown in Figure 9-1), a page looks at each name in the name/value form post collection and searches the control tree for a control with a UniqueID that matches that name. If the page finds such a control and that control implements IPostBackDataHandler , the page invokes LoadPostData on that control. If your control does not render the value of its UniqueID as the name attribute of a form element, as an alternative, it can participate in the Load Postback Data phase by invoking the RegisterRequiresPostBack method of the containing page in the control's PreRender method. Later in this chapter, we'll show a Login control example that uses this alternate technique.

The LoadPostData method has two arguments: a string that contains the name of the postback element, and a System.Collections.Specialized.NameValueCollection instance that contains the name/value collection of posted form data. Your control can use the postback data to update its state. If the state of your control changes on postback and you want to raise events to signal that change, you must return true from the LoadPostData method.

In the Raise Changed Events phase described in Figure 9-1, the page invokes the RaisePostDataChangedEvent method of each control that implements IPostBackDataHandler and returned true when the page called the LoadPostData method on the control. The RaisePostDataChangedEvent method is so named because a control that wants to raise events to signal changes in its state must do so here. For example, the TextBox control raises a TextChanged event in this phase, and the DropDownList control raises a SelectedIndexChanged event.

The Raise Changed Events phase occurs after the Load phase when the entire control tree has been loaded. The page framework splits postback data processing into two phases ”Load Postback Data and Raise Changed Events ”so that all the controls in the control tree have a chance to update their state before raising changed events.

If your control renders multiple form elements, you can generate unique names for them based on the UniqueID of your control, such as UniqueID + ":tag1" and UniqueID + ":tag2" . In Chapter 8, we developed the LoginUI control, which generates multiple form elements that have unique names.

Now let's look at an implementation of postback data processing in the SimpleTextBox example, which is similar to the ASP.NET TextBox control.

Processing Postback Data ”The SimpleTextBox Example

The SimpleTextBox control shown in Listing 9-9 renders an HTML text box and implements the IPostBackDataHandler interface. On postback, SimpleTextBox updates its Text property by using the posted value of the text box in the form post data and raises a TextChanged event if the Text property has changed on postback. The implementation of postback data processing is highlighted in the code listing.

Listing 9-9 SimpleTextBox.cs

 usingSystem; usingSystem.ComponentModel; usingSystem.Collections.Specialized; usingSystem.Web.UI; usingSystem.Web.UI.WebControls; namespaceMSPress.ServerControls{ [DefaultEvent("TextChanged"), DefaultProperty("Text")] publicclassSimpleTextBox:WebControl,IPostBackDataHandler{ privatestaticreadonlyobjectEventTextChanged=newobject(); [Bindable(true), Category("Behavior"), DefaultValue(""), Description("ThetextintheTextBox")] publicvirtualstringText{ get{ strings=(string)ViewState["Text"]; return((s==null)?String.Empty:s); } set{ ViewState["Text"]=value; } } 

 protectedoverrideHtmlTextWriterTagTagKey{ get{ returnHtmlTextWriterTag.Input; } } [Category("Action"), Description("Raisedwhenthetextinthetextboxischanged")] publiceventEventHandlerTextChanged{ add{ Events.AddHandler(EventTextChanged,value); } remove{ Events.RemoveHandler(EventTextChanged,value); } }  boolIPostBackDataHandler.LoadPostData(stringpostDataKey, NameValueCollectionvalues){ StringpresentValue=Text; StringpostedValue=values[this.UniqueID]; if(!presentValue.Equals(postedValue)){ Text=postedValue; returntrue; } returnfalse; }  voidIPostBackDataHandler.RaisePostDataChangedEvent(){ OnTextChanged(EventArgs.Empty); } protectedvirtualvoidOnTextChanged(EventArgse){ EventHandlertextChangedHandler= (EventHandler)Events[EventTextChanged]; if(textChangedHandler!=null){ textChangedHandler(this,e); } } protectedoverridevoidAddAttributesToRender(HtmlTextWriterwriter){ base.AddAttributesToRender(writer);  writer.AddAttribute(HtmlTextWriterAttribute.Name, this.UniqueID);  writer.AddAttribute(HtmlTextWriterAttribute.Type,"Text"); writer.AddAttribute(HtmlTextWriterAttribute.Value, this.Text); } protectedoverridevoidRender(HtmlTextWriterwriter){ //Makesurethiscontrolisinaserverform. if(Page!=null){ Page.VerifyRenderingInServerForm(this); } base.Render(writer); } } } 

Listing 9-10 contains a page that uses the SimpleTextBox control and attaches an event handler to its TextChanged event. As with other form controls, the SimpleTextBox control must be declared within server-side form tags. Figures 9-7 and 9-8 show the page viewed in a browser upon the first request and after submitting the form.

Listing 9-10 SimpleTextBoxTest.aspx

 <%@PageLanguage="C#"%> <%@RegisterTagPrefix="msp"Namespace="MSPress.ServerControls" Assembly="MSPress.ServerControls"%> <html> <head> <scriptrunat="server"> voidsimpleTextBox1_TextChanged(objectsender,EventArgse){ label1.Text="Thetextinthetextboxchangedafter"+ "postback.Itsnewvalueis:"+simpleTextBox1.Text; } </script> </head> <body> <formrunat="server"> <br> <asp:ButtonText="Submit"Runat="server"/> <br> Entersometext: <msp:SimpleTextBoxFont-Size="10pt"Font-Bold="true" runat="server"OnTextChanged="simpleTextBox1_TextChanged" id="simpleTextBox1"/> <br> <asp:LabelFont-Size="10pt"id="label1"runat="server" EnableViewState="false"/> </form> </body> </html> 

Figure 9-7. SimpleTextBoxTest.aspx viewed in a browser on first request

Figure 9-8. SimpleTextBoxTest.aspx viewed in a browser after text is entered and the form is posted

If you resubmit the page without changing the text, you will see that the TextChanged event is not raised by the SimpleTextBox control on postback. We set EnableViewState="false" on the Label control in the page so that the Label instance does not persist its text across round-trips and displays a message only when the text in the text box changes.