JavaScript 101 - Part 3

The onSubmit Event Handler

The first step in verifying form submissions with JavaScript is to be able to respond to the user submitting a form. Fortunately, there is an event handler that makes this very easy.

<form action="blah.cgi" method="post" onSubmit="return false;">  
Your name: <input type="text" name="name">  
<input type="submit" name="submit" value="Go!">  
</form>

Here is a form that can never be submitted! The trick is in the onSubmit attribute of the form tag. Like the onClick, onMouseOver, and onMouseOut attributes we saw in Part 2, this is a JavaScript event handler. It specifies JavaScript code to be run in response to the form being submitted. Like those other event handlers, the value returned by this event handler lets you control whether the browser handles the event itself after it has finished executing your JavaScript code. In the above example, all the event handler does is return a value of false, which instructs the browser not to proceed with submitting the form! Thus, if you ever need a form that’s “just for show”, or which will be entirely handled by JavaScript, then simply returning false from the onSubmit event handler will be enough to block form submissions on browsers that support JavaScript.

Now, the onSubmit event handler really gets interesting when the value it returns depends on some condition. Here’s an example:

<script language="JavaScript" type="text/javascript">  
<!--  
function confirmSubmit() {  
 if (confirm("Really submit this form?")) return true;  
 else return false;  
}  
//-->  
</script>  
<form action="blah.cgi" method="post"  
     onSubmit="return confirmSubmit();">  
Your name: <input type="text" name="username">  
<input type="submit" name="submit" value="Go!">  
</form>

In this example, the onSubmit event handler returns whatever value is returned by the confirmSubmit() function. confirmSubmit() uses the built-in JavaScript function confirm(), which is similar to alert() in that it displays a message box to the user. But instead of just an OK button, the message box will have OK and Cancel buttons. If the user clicks OK, confirm() returns true; if the user clicks Cancel or closes the message box, it returns false. This returned value acts as the condition in an if statement, which in turn determines whether confirmSubmit() returns true or false.

So in brief, the above example intercepts the form submission and displays a message box asking the user to confirm the submission. If the user clicks OK, the submission goes forward; otherwise, the form submission is cancelled.

In fact, since the confirm() function so conveniently returns true or false itself, we could write the above example more efficiently by using confirm() directly in the event handler:

<form action="blah.cgi" method="post"  
     onSubmit="return confirm('Really submit this form?');">  
Your name: <input type="text" name="username">  
<input type="submit" name="submit" value="Go!">  
</form>

The use of a custom function for determining whether a form submission goes forward is an important technique for form validation, however, as we’ll see in the next section. For now, you can use the above code on any form to require confirmation from the user before a submission occurs.