Processing Postback Data

For a control to be able to examine form data that is posted back by the client, it must implement the System.Web.UI.IPostBackDataHandler interface. The contract of this interface allows a control to determine whether its state should be altered as a result of the postback and to raise appropriate events. The IPostBackDataHandler interface contains two methods.

public interface IPostBackDataHandler{
   public bool LoadPostData(string postDataKey, 
                           NameValueCollection postCollection);
   public void RaisePostDataChangedEvent();
}
[Visual Basic]
Public Interface IPostBackDataHandler
   Public Function LoadPostData(postDataKey As String, _
            postCollection As NameValueCollection) As Boolean
   Public Sub RaisePostDataChangedEvent()
End Interface

Upon postback, the page framework searches the posted content for values that match the UniqueIDs of server controls that implement IPostBackDataHandler. It then sequentially invokes LoadPostData on each control that implements this interface. The two arguments of LoadPostData are: a key that identifies the control and a collection, NameValueCollection, that contains the posted data. LoadPostData is typically implemented to update the state of a control as a result of the postback. The following example shows an implementation of LoadPostData for a custom text box control.

public virtual bool LoadPostData(string postDataKey, NameValueCollection postCollection) {
    string presentValue = Text;
    string postedValue = postCollection[postDataKey];
    
    if (!presentValue.Equals(postedValue)){
          Text = postedValue;
          return true;
    }
    return false;
}
[Visual Basic]
Public Overridable Function LoadPostData(postDataKey As String, postCollection As NameValueCollection) As Boolean
   Dim presentValue As String = Text
   Dim postedValue As String = postCollection(postDataKey)
   If Not presentValue.Equals(postedValue) Then
      Text = postedValue
      Return True
   End If
   Return False
End Function
      

If the state of the control is changed as a result of the postback, LoadPostData returns true; otherwise, it returns false. The page framework keeps track of all the controls that return true and invokes RaisePostDataChangedEvent on those controls. Change events, if any, are raised from this method. Postback data processing thus occurs in two phases — updating state and raising change notifications. This prevents change notifications from being raised during postback data loading, when they could incorrectly alter state before all controls have a chance to load postback data. The following code fragment shows an implementation of RaisePostDataChanged for a custom text box control.

public virtual void RaisePostDataChangedEvent() {
            OnTextChanged(EventArgs.Empty);      
      }
[Visual Basic]
Public Overridable Sub RaisePostDataChangedEvent()
   OnTextChanged(EventArgs.Empty)
End Sub

It is essential that the rendering logic assign the UniqueID to the name attribute of the control. Otherwise, the page framework will be unable to route postback data to your control. If your control emits multiple form elements, at least one of the elements must have a have a name attribute that corresponds to the UniqueID of the control. For an example of a custom control that emits multiple form fields, see Composition vs. Rendering. The following code fragment assigns the UniqueID to the name attribute.

protected override void Render(HtmlTextWriter output) 
{
output.AddAttribute(HtmlTextWriterAttribute.Type, "text");
output.AddAttribute(HtmlTextWriterAttribute.Value, this.Text);
output.AddAttribute(HtmlTextWriterAttribute.Name, this.UniqueID);
output.RenderBeginTag(HtmlTextWriterTag.Input);
output.RenderEndTag();
}
[Visual Basic]
Protected Overrides Sub Render(output As HtmlTextWriter)
output.AddAttribute(HtmlTextWriterAttribute.Type, "text")
output.AddAttribute(HtmlTextWriterAttribute.Value, me.Text)
output.AddAttribute(HtmlTextWriterAttribute.Name, me.UniqueID)
output.RenderBeginTag(HtmlTextWriterTag.Input)
output.RenderEndTag()
End Sub

For a sample of a custom text box control that participates in postback data processing, see Postback Data Processing Sample.

See Also

Postback Data Processing Sample