MsgBox - A custom ASP.NET web-control to display message box dialogs in a web-browser

Source Code for this Article

The following help file maybe downloaded:

• MsgBox.chm - Complete source code for the MsgBox custom web-control, a sample ASP.NET application, and reference documentation for the MsgBox web-control.

Contents

Introduction

Features

How does it work?

Things to remember

Conclusion

Introduction

The MsgBox control is a custom ASP.NET web-control which provides a user-defined message box to appear following a page postback to the browser.  The message boxes are generated by client-side javascript alert(), confirm(), or prompt() function call.  When the dialog is dismissed, the page is then submitted via javascript from the client, and the message box return value is available to the ASP.NET page code-behind assembly via an event generated by the MsgBox web-control.

Features

The following features make the MsgBox web-control easy to use:

• The control can be dragged onto the ASP.NET web-form as with any other web-control (provided it has been added to a Visual Studio toolbar tab - see Installation and Usage for more information).
• In most instances only one MsgBox control is added to service multiple displays of the message box in response to button and other web-control clicks. See the attached sample ASP.NET application for more information. the web-control provides a programmatic interface (see the Execute methods) that allows the message box to be customized and called with a few lines of code.
• The web-control is self-contained and all client-side javascript is generated by the control itself when it is rendered to the browser.

How does it work?

The  MsgBox web-control works in the following way:

• The control is dragged onto the ASP.NET web-form and properties such as the MessageBoxType, Text and PromptValue can be set, if required.
• Assuming that for a another web-control element, a button, a message box response is required when the button is clicked, a OnClick is defined and the following code will activate the message box:
  private void btnPrompt_Click(object sender, System.EventArgs e)
  {
    this.MsgBox1.Execute(
      MsgBox.MsgBoxType.Prompt,
      "Prompt message shown in response to button click!",
      "Default Prompt Value", sender as Control);
  }

  In the above example, the Execute method is called, which overrides the properties of MsgBox1: a prompt() type message box is displayed, with Text set to the value of the second parameter, while PromptValue is set to the third parameter.  The fourth parameter, if used, will return the control that caused the post-back in the first instance. Later, when the message box return value is retrieved, this control will be referenced so that the application has knowledge of which control originally caused the message box to be displayed.

  Note that the alternative Execute method can be used, if the control properties have been set already, as follows:

  private void btnPrompt_Click(object sender, System.EventArgs e)
  {
    this.msg.Execute(sender as Control);
  }
• When the OnClick response method has executed, the page is then posted back to the browser. During the rendering of the page for post-back, the control registers a startup script using the Page.RegisterStartupScript method, and it registers two hidden fields using the Page.RegisterHiddenField method, namely a field for the message box return value (string), and another for the ID of the control that originally caused the message box to be displayed.
  In the script generation (private method CreateMessageScript), the appropriate javascript function is called to display the message box.  When the message box is dismissed, the return value is saved in the hidden field for the message box return.  Script is also generated to cause a post-back when the message box is dismissed by calling the Page.GetPostBackEventReference method. Typically, the generated script for the above code example looks like this:
  <script>
    document.getElementById('__MsgBox1_Return').value=
       prompt('Prompt message shown in response to button click!','Default Prompt Value');
    __doPostBack('MsgBox1','')
  </script>
  Note that the __doPostBack script function is also generated by the Page.GetPostBackEventReference method.

• Once the script has run the page is posted to the server again. The hidden fields are correctly updated by ASP.NET and are available to the control's code-behind assembly for use. The correct place to act on this is in a response method to the ReturnValueChanged event that the control generates. The ReturnValueChanged event is fired only if the message box ReturnValue has changed. The way the control knows this is by interpreting the post-back data sent to it by implementing the IPostBackDataHandler interface.  The PostBackDataHandler.LoadPostData implementation allows the control to check for changes to the ReturnValue. The IPostBackDataHandler.RaisePostDataChangedEvent allows the control to fire the ReturnValueChanged event, if it is implemented by the web-form. Finally, in order for a control to handle post-back data it must register to do so using the Page.RegisterRequiresPostBack method. This is done in the control's OnInit method override. A typical event handler for the above example would be:
  private void MsgBox1_ReturnValueChanged(object sender, System.EventArgs e)
  {
    MsgBox msgBox = sender as MsgBox;
    if(msgBox != null)
    {
      ...
    }
    MsgBox.MsgBoxReturnArgs msgArgs = e as MsgBox.MsgBoxReturnArgs;
    if(msgArgs != null)
    {
      Control ctl = msgArgs.Source;
      ...
    }
  }
  The ReturnValueChanged event handler is passed a sender object of type MsgBox, and an event arguments object of type MsgBox.MsgBoxReturnArgs.

Things to remember

Conclusion

The MsgBox control is a custom ASP.NET web-control that provides an easy way to display message boxes for user alerts, confirmations and prompts.  The control provides extensive client scripting functionality without the application program having to write (or maintain) any client-side script.