Using ASP.NET to Prompt a User to Save When Leaving a Page

By Scott Mitchell

Introduction

Last week I wrote an article titled Prompting a User to Save When Leaving a Page, which looked at how to use the client-side onbeforeunload event to display a confirmation messagebox when a user attempted to leave a data-entry page after having modified the data's contents without explicitly saving the data. To summarize last week's article, adding such a feature required the following steps:

Writing code that saves the initial values of the page's input form fields in a client-side array.
Creating an event handler for the onbeforeunload event that checks to see if the input form fields' values differ from those in the array. If they do, then a string is returned, prompting the user if they really want to leave. Otherwise, no string is returned, and the user can leave the page as they normally would (i.e., without being prompted).
Finally, for buttons or other HTML elements that could cause the user to leave the page but should not require that the user be prompted, a client-side onclick event handler was used to set a flag that indicated that the onbeforeunload event handler didn't need to check for changes. This is typically used with a "Save" button that, when clicked, causes a postback, but whose posting back should not prompt the user that they are about to leave the page.

As last week's article examined, these steps could be accomplished by adding two client-side <script> blocks and client-side onclick events where needed. While adding this script code is not terribly difficult, I find it simpler to move this logic to server-side methods that will inject the appropriate client-side script for us. In this article we'll examine how to extend the base Page class, adding a couple of methods that will allow for a user to be prompted when they leave the page without saving without the page developer having to write a single line of client-side script code. (If you've yet to read Prompting a User to Save When Leaving a Page, please be sure to do so before continuing on.)

An Update to this Article...

Since the publication of this article I have received many questions from readers on a couple of issues - namely, being able to suppress the prompt when using a Web control whose AutoPostback property is set to True, and how to suppress client-side script error messages in Internet Explorer when leaving the page via client-side script using the eval() function. These two questions are discussed and answered in An Update on Prompting a User to Save When Leaving an ASP.NET Page.

- continued -

A High-Level Look at What We Want to Accomplish

The code-behind class for any ASP.NET Web page is derived, either directly or indirectly, from the Page class in the System.Web.UI namespace. The Page class contains the base functionality that all ASP.NET Web pages must provide. For example, the Page class includes properties like IsValid and IsPostBack, and events like Load (which triggers the Page_Load event handler to execute). If there is some functionality that you know you will need in a number of pages, you can provide this functionality by creating a custom class that derives from the Page class, and then have your ASP.NET Web pages' code-behind classes derive from this custom class (rather than from the Page class directly).

In this article we'll create such a custom class that extends the Page class. Our extended Page class will contain methods that we can call that will inject the appropriate client-side script so that if a user attempts to leave the page after making changes without saving, a confirmation will be displayed. Specifically, there will be two methods:

MonitorChanges(webControl) - this method accepts a Web control (such as a TextBox, CheckBox, DropDownList, etc.) and adds the necessary client-side script to monitor this control's value. That is, if this control's value is changed and then the user attempts to leave the page without saving, they'll be prompted with a warning.
BypassModifiedMethod(webControl) - this method is used to indicate that a particular Web control should not cause the confirmation to be displayed. This will typically be used on "Save" Buttons, LinkButtons - namely on Web controls that might cause a postback but, even if changes have been made, should not display the confirmation.

In order to squirt out the correct client-side script, these methods will utilize three methods from the Page class: RegisterClientScriptBlock(), RegisterStartupScript(), and RegisterArrayDeclaration(). These three server-side methods add client-side code to the ASP.NET page's rendered markup. Let's take a brief moment to examine these three methods.

Working with Client-Side Script Code in Server-Side Code

Working on Web applications requires a keen understanding of the logical, physical, and temporal differences. These differences were more apparent in classic ASP, but ASP.NET and its Web Forms paradigm effectively blurs the distinction between the client and server. Regardless, the distinction still very much exists and it is important to be familiar with the separation.

There are often times when we might want to inject client-side script from a server-side method. To facilitate this the Page class provides a number of methods. To add a block of client-side script code, use either RegisterClientScriptBlock(key, script) or RegisterStartupScript(key, script). These methods both accept two string values as input: a key and a script value. The key uniquely identifies the script block being injected, while the script value contains the actual client-side script to inject. (Note that the script input parameter must include the precise markup to inject, including the <script> tag itself.)

The main difference between these two methods is the location in the markup where the controls emits its script. Both methods inject their script content inside the <form>, but RegisterClientScriptBlock(key, script) adds it before the Web controls within the form, whereas RegisterStartupScript(key, script) adds the script after the Web control markup.

The other Page class that we'll need to utilize is the RegisterArrayDeclaration(arrayName, arrayValue). This method creates a client-side array with the values specified. To create an array named foo with values 1 through n you'd call the RegisterArrayDeclaration(arrayName, arrayValue) method n times, like so:

Page.RegisterArrayDeclaration("foo", "1"); Page.RegisterArrayDeclaration("foo", "2"); ... Page.RegisterArrayDeclaration("foo", "n");

A thorough discussion of the client-side injection methods in the Page class is a bit beyond the scope of this article. For more information, utilize the following two articles of mine: Working with Client-Side Script and Injecting Client-Side Script from an ASP.NET Server Control. (The first article also discusses in more detail the process of extending the functionality of the Page by creating a custom, derived class, and having ASP.NET pages' code-behind classes deriving from this custom class.)

Creating the `MonitorChanges(webControl)` Method

A page developer using our extended Page class - which I named ClientSidePage - can indicate that a particular Web control on the page should be monitored for changes by calling the MonitorChanges() method, passing in the Web control to watch. This method needs to do the following two tasks:

Add the Web control's client-side ID to a client-side array. (This array is what is used to grab the initial values of the input controls, and, upon page exit, is used to check to see if the input fields' values have changed.)
Inject the client-side script that saves the initial form field values and that handles the onbeforeunload client-side event.

This first task is accomplished directly in the MonitorChanges() method; the second task is delegated to an additional method, as shown below (the complete ClientSidePage class is available for download at the end of this article in both VB.NET and C#):

Public Class ClientSidePage Inherits System.Web.UI.Page Public Sub MonitorChanges(ByVal wc As WebControl) If wc Is Nothing Then Exit Sub If TypeOf wc Is CheckBoxList OrElse TypeOf wc Is RadioButtonList Then 'Add an array element for each item in the checkbox/radiobutton list For i As Integer = 0 To CType(wc, ListControl).Items.Count - 1 Page.RegisterArrayDeclaration("monitorChangesIDs", """" & _ String.Concat(wc.ClientID, "_", i) & """") Page.RegisterArrayDeclaration("monitorChangesValues", "null") Next Else Page.RegisterArrayDeclaration("monitorChangesIDs", _ """" & wc.ClientID & """") Page.RegisterArrayDeclaration("monitorChangesValues", "null") End If AssignMonitorChangeValuesOnPageLoad() End Sub Private Sub AssignMonitorChangeValuesOnPageLoad() If Not Page.IsStartupScriptRegistered("monitorChangesAssignment") Then Page.RegisterStartupScript("monitorChangesAssignment", _ "<script language=""JavaScript"">" & vbCrLf & _ " assignInitialValuesForMonitorChanges();" & vbCrLf & _ "</script>") Page.RegisterClientScriptBlock("monitorChangesAssignmentFunction", _ "<script language=""JavaScript"">" & vbCrLf & _ " function assignInitialValuesForMonitorChanges() {" & vbCrLf & _ " for (var i = 0; i < monitorChangesIDs.length; i++) {" & vbCrLf & _ " var elem = document.getElementById(monitorChangesIDs[i]);" & vbCrLf & _ " if (elem) if (elem.type == 'checkbox' || elem.type == 'radio') " & _ " monitorChangesValues[i] = elem.checked; " & _ " else monitorChangesValues[i] = elem.value;" & vbCrLf & _ " }" & vbCrLf & _ " }" & vbCrLf & vbCrLf & vbCrLf & _ " var needToConfirm = true;" & vbCrLf & _ " window.onbeforeunload = confirmClose;" & vbCrLf & vbCrLf & _ " function confirmClose() {" & vbCrLf & _ " if (!needToConfirm) return;" & vbCrLf & _ " for (var i = 0; i < monitorChangesValues.length; i++) {" & vbCrLf & _ " var elem = document.getElementById(monitorChangesIDs[i]);" & vbCrLf & _ " if (elem) if (((elem.type == 'checkbox' || elem.type == 'radio') && elem.checked != monitorChangesValues[i]) || (elem.type != 'checkbox' && elem.type != 'radio' && elem.value != monitorChangesValues[i])) { needToConfirm = false; setTimeout('resetFlag()', 750); return ""You have modified the data entry fields since last savings. If you leave this page, any changes will be lost. To save these changes, click Cancel to return to the page, and then Save the data.""; }" & vbCrLf & _ " }" & vbCrLf & _ " }" & vbCrLf & vbCrLf & _ " function resetFlag() { needToConfirm = true; } " & vbCrLf & _ "</script>") End If End Sub ... End Class

Before delving into the methods, first note that the ClientSidePage class derives from System.Web.UI.Page. It is vital that ClientSidePage extend the Page class in order to use this class as the base class for our ASP.NET pages' code-behind classes.

For More Information on Base Classes...

The ClientSidePage class is an example of a base class that is designed to be inherited by an ASP.NET page's code-behind class. This is a common practice in more involved ASP.NET Web applications and is discussed in more detail in the article Using a Custom Base Class for your ASP.NET Page's Code-Behind Classes.

The MonitorChanges() method's first task is to create an array that contains the client-side IDs of the input form fields to watch. This is done by creating two arrays: monitorChangesIDs, which holds the IDs of the elements to watch; and monitorChangesValues, which holds the initial values of these form fields. The MonitorChanges() method takes the passed-in Web control's ClientID and adds it to the first array, and then adds a null to the second. (The second array is populated through client-side code, which we'll examine in a bit.)

One thing to note is that the MonitorChanges() checks to see if the Web control passed in is a RadioButtonList or CheckBoxList. If it is one of these two types of Web controls, special care must be taken since these controls create a set of children radio buttons or checkboxes whose client-side IDs are of the form CheckBoxOrRadioButtonListID_indexOfCheckBoxOrRadioButton. That is, a RadioButtonList with an ID of favSport would have its rendered radio buttons with IDs of favSport_0, favSport_1, favSport_2, and favSport_3. Therefore, for RadioButtonLists and CheckBoxLists, the MonitorChanges() method registers each of the control's corresponding radio buttons or checkboxes in the client-side array. (One thing to note is that for data-bound RadioButtonLists and CheckBoxLists, you will need to call MonitorChanges() after you do the databinding.)

After adding the client-side IDs to the array, MonitorChanges() calls the AssignMonitorChangeValuesOnPageLoad() method, which does two things: injects startup script that calls the client-side assignInitialValuesForMonitorChanges() function (this function then populates the monitorChangesValues array with the specified form fields' initial values); and injects the actual code for the assignInitialValuesForMonitorChanges() function, along with the closeConfirm() function (which serves as the event handler for the onbeforeunload event).

The code in the client-side closeConfirm() function is virtually identical to the code examined in the last week's article, Prompting a User to Save When Leaving a Page. The only difference is that here when a discrepancy is found and the user is prompted if they really want to exit the page, we set the needToConfirm flag to false, but then setup a timer so that it's reset back to true in 0.75 seconds. You may, understandably, be wondering why this is done.

The reason is, admittedly, a bit of a hack. To understand why we need this hack, realize that whenever a hyperlink is clicked, the browser says, "Ok, you are leaving the page," and fires its onbeforeunload event. This sounds fine, but things can get a bit weird if the hyperlink contains client-side JavaScript in its href that causes the page to unload again. Specifically, if you have a hyperlink with an href with code that submits the form or redirects the user, when that hyperlink is clicked, the user will be prompted once, asking if they want to leave the page. If they click OK, the hyperlink's JavaScript will run, submitting the form or redirecting the user, which causes the browser to again prompt the user, asking them if they are sure they want to leave the page. To suppress this second message, we simply set needToConfirm to false for 0.75 seconds. What this does, is when the hyperlink is first clicked, it prompts the user. If the user clicks OK, and the JavaScript kicks in, the JavaScript doesn't cause a second, superfluous confirmation messagebox (assuming the JavaScript can run and complete in 0.75 seconds). This hack is especially pertinent to ASP.NET since LinkButtons are hyperlinks with JavaScript code in their href that submits (posts back) the form.

Excluding Buttons From Prompting the User

As we examined in Prompting a User to Save When Leaving a Page, the onbeforeunload event causes the user to be prompted if they want to save when they exit the page after having made changes, but without saving. Specifically, this onbreforeunload event fires when the user closes their browser, enters another URL, clicks on a hyperlink, or posts back the form. What we want to avoid is having the "Save" button display a confirmation messagebox. Rather, we want the "Save" button to be able to cause a postback without warning the user that values have been changed.

To accomplish this we need to have the "Save" button's client-side onclick event set the needToConfirm flag to false. This can be accomplished via the BypassModifiedMethod(webControl) method, which simply adds this needed client-side attribute to the passed-in Web control. The code for this method is rather simple, and shown below:

Public Class ClientSidePage Inherits System.Web.UI.Page ... Public Sub BypassModifiedMethod(ByVal wc As WebControl) wc.Attributes("onclick") = "javascript:" & GetBypassModifiedMethodScript() End Sub Public Function GetBypassModifiedMethodScript() As String Return "needToConfirm = false;" End Function End Class

Using the `ClientSidePage` Class in an ASP.NET Web Page

Let's wrap things up with looking at a simple data-entry Web page that utilizes the features we've examined thus far. Start by creating a Web page with a number of form fields, such as TextBoxes, CheckBoxes, DropDownLists, RadioButtonLists, and so on. Next, add a "Save" button. Now, to have the page exhibit the desired behavior - that is, to have it prompt the user if they make a change to one of the data entry form fields and attempt to leave the page without saving - do the following:

In the page's code-behind class, have it derive from ClientSidePage
In the Page_Load event handler have a call to the MonitorChanges() method for each data-entry Web control on the page. Do this on every page load (including postbacks). Also call BypassModifiedMethod(), passing in any Buttons that should not cause the user to be prompted.

In the download at the end of this article, there's a sample ASP.NET page, WebForm1.aspx, with a number of data-entry form fields. Here's the server-side code for monitoring changes to these fields:

Public Class WebForm1 Inherits ClientSidePage Private Sub Page_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load 'Monitor the changes for the Web controls whose values you 'want to watch MonitorChanges(name) MonitorChanges(useASPNET) MonitorChanges(favColor) MonitorChanges(musicLikes) MonitorChanges(favSport) 'For those controls (like "Save" buttons) that cause a postback ' that should NOT prompt the user, call BypassModifiedMethod BypassModifiedMethod(btnSave) End Sub ... End Class

Notice that the code-behind class is derived from ClientSidePage (and not System.Web.UI.Page), that there's a MonitorChanges() call for each data-entry form field, and that there's a call to BypassModifiedMethod() for the "Save" button.

Happy Programming!

By Scott Mitchell

Attachments

Download the complete source code (in ZIP format)

View the ClientSidePage class in C# code