From: "Mark J. Reed" <markjreed@...>
Date: 2003-07-15T07:23:58+09:00
Subject: Re: CGI and checkboxes

On Tue, Jul 15, 2003 at 06:55:12AM +0900, Kurt M. Dresner wrote:
> How do I get the value from a checkbox made with cgi.checkbox ?
> 
> I need to make a decision based on whether or not the checkbox is
> checked - will that be sent to me as a parameter?

You might want to invest in an introductory book on CGI programming.
The language doesn't matter, since you're looking for the mechanisms, not the
syntax, but the Perl/CGI book would be a good choice since Ruby's 'cgi' module
is based on Perl's CGI.pm.  

In any case, it sounds like there's some confusion about the sequence
of events, possibly because of the wide range of functions in the
cgi module.

Your basic web browser/server interaction works like this:

1. Browser sends request to some web server for some page.

2. Server sends requested page to the browser.  This time it 
   happens to be HTML containing a <form>.

	Sometimes this page is generated dynamically by a CGI (or Java
	servlet or JavaServerPage or ActiveServerPage or PHP page
	or whatever), but it can be a plain old static HTML file
	if the form itself doesn't change.

3. Browser renders form for the user's benefit.

4. User fills out the form and clicks the submit button.

5. Browser sends a new request to some web server (possibly a different
   web server) for some page (possibly a different page, even if it's on
   the same server as before).  (The page requested is determined by
   the value of the "action" attribute in the HTML <form> tag; this is how
   you can have a static form that results in a CGI being invoked when it's
   submitted.)  The request includes data about the way the user filled out
   the form.

6. The server sends the results of the submittal back to the browser.
   Usually this is another HTML page, but it could be an image, or
   XML that the browser needs to transform with a stylesheet, 
   or plain text, or whatever.

7. The browser displays results

For this to be useful, the page requested by the browser to the
server in step 5 - which is the one specified by the action attribute
of the <form> tag - is usually to some sort of dynamic page: CGI,
Java servlet, JSP, ASP, etc.  That way the page sent back to the browser
in step 6 can depend upon the contents of the form.  (It is possible, however,
request a staitic page containing some JavaScript; then when displaying the
results in step 7 the browser might execute some JavaScript code that changes
what's displayed based on the data submitted.  You could also skip
the round trip to the server entirely by just having a button that invokes
some JavaScript in the browser that does something based on the contents
of the form.  But I digress.)

The data submitted to the server in step 5 is a sequence of (name,
value) pairs.  If you don't specify a method attribute on the <form>
tag, or specify it as "GET", then you can see these name=value
pairs at the end of the URL requested in step 6.  Something like
http://myserver/cgi-bin/myCgi?name1=value1&name2=value2&name2=value2
(name2 has more than one value in this case), etc.  Different types
of <input> tags fill these out differently, but in all cases,
the name and value are just strings:

	For a text input, the value is the typed in text.

	For most other inputs, there is a value="" attribute in the HTML
	which tells the browser what to send when that option is selected.
	This includes the <option>s within a <select> (whose values can be
	different from the strings shown to the user, like this:

		<strong>Country:</strong>
		<select name="country">
	 	<option value="jp">Japan</option>
	 	<option value="us">United Kingdom</option>
	 	<option value="uk">United States</option>
		</select>

	It also includes buttons, radio buttons, and checkboxes.
	In these cases, the paramter given by the name="" is not
	sent at all unless the element is clicked.

	For instance:

		<input type="checkbox" name="spamMe" value="yes" 
		       checked="checked" /> Send me email!

	If the user leaves that box checked, then the CGI will see
	an input parameter named "spamMe" whose value is "yes".
	If the user unchecks it, then the CGI will not see any input
	parameter of that name.  The code to check looks something
	like this:

		require 'cgi';
		q = CGI.new;
		.
		.
		.
		if q['spamMe'].length > 0 then
		    # check box was checked
		    spamTheHeckOutOf(q['email_address'][0])
		else
		    # check box wasn't checked
		    spamTheHeckOutOfThemAnyway(q['email_address'][0])
		end
	   
-Mark