GEHC JS
Class 3

About Forms
-----------

Forms are an essential part of any interactive site - they allow you to give the
user a chance to fill in data specific to them, whether it is a name, address,
credit card number, color preference, or email address. In addition, we can use
forms to build pages that gather data on one page and pass it along to many
other pages. We will leverage this ability in the very last week of class,
after we learn about Perl. In the meantime, JavaScript goes hand in hand with
almost every form that I build on the web. There are lots of reasons why, which
we'll touch on today.

Forms and data validation
-------------------------

Validation of data placed in forms by users is critical. It must be done
before the server tries to store the data, or else the data will be useless. We
can validate data on the server, but that's our last line of defense and the
one that is the least useful to users.

What users want is instant feedback about what they have done wrong. Using
JavaScript, we can validate user input before it ever leaves the client,
providing instant feedback to the user, and sparing our server a hit for simple
data validation.

Is it blank?
------------

One of the first tests we will want to do is find out if a data field is blank
or not. Very often, there are required fields in a form, and we will make sure
we are able to test those fields to see if they are blank.

** JS3-1 - a simple text box, with a first attempt at blankness testing.

This testing is broken, because it is too simple. If the user types nothing in
the box and presses Submit, it will tell them the box is empty. If they type
anything else in the box, it will say it is not empty... but if they type in
spaces, then that passes the != "" test, but is obviously wrong. We need a
function to test data for blankness.

*TIME OUT*

Let's take a few moments to look at the HTML and the corresponding JS in this
example. In the HTML, we have a form:

<form onSubmit="return(checkForm());">

This form tag is very basic, and includes a call to a new event, the onSubmit
event. The onSubmit event fires when the submit button is pressed. In other
words, when the user thinks they are done with the form, and we should start
checking data, the event fires.

In this case, when the event fires, we call the checkForm() function,
previously declared in the head. In the checkForm() function, we have this
code:

  if (document.forms[0].elements[0].value == "") {

Here we see the document object, and a new property of the object, the forms
array. Typically, there is only one form on a page, so referring to forms[0] is
much safer than referring to images[0]. Within a Form object, there is the
elements property. There is one member of the elements property for each
"widget" in the form (a widget is a text box, button, radio button, etc). Using
the index number here is as tricky as with the images array. Each of the
different kinds of elements has a different set of methods and properties, too.
Here, we want to see the data inside the text box on the screen. That is the
value property of the 0th element of the 0th form of the document.

We can examine the data, to test to see if it is not equal to something or, in
this case, if it is equal to something specific. If the value in the box is ""
(empty string) then we put up an alert box indicating the box is empty.
Otherwise, we put up an alert box saying it is filled in.

Just as we named the images before, we can also name the forms and the widgets
to make our lives easier. Doing so will make our code more robust and make
it much easier to read.

<form onSubmit="return(checkForm());" name=theform>

I name almost every one of my forms "theform" to make my code generally more
consistent, but you can name them what ever you wish.

<input type=text size=20 maxlength=30 name=inputbox>

Naming widgets is a little more important, because you want to pick something
short and descriptive, like "name," "address," or "city."  Here I've used a
generic name, inputbox. Now in my JS code, I can say:

  if (document.theform.inputbox.value == "") {

One other point to bring up, which just reinforces our discussion of return
values from last week. Note that the onSubmit event returns the value of
checkForm(). Note that checkForm() always returns false. This is perfect for
our needs - when the onSubmit function returns true, the form is actually
submitted. Here, until we learn about the server side, we always want to return
false, to keep the form from submitting. When we return false, the submission
itself is suppressed.

** JS3-2 - second try, with object names and an isblank function

Here I've named the objects, but I've also changed my checkForm() function to
call another function to do blankness testing. The isblank function is one we
will use a lot.

  if (isblank(document.theform.inputbox.value) == true) {

We have here a call to our isblank function. Based on its name, we can presume
that it returns a true if the data is blank, and a false if it is not blank. We
also see that we pass it one value, a variable to check. In this case, the
variable is the inputbox's contents, stored in inputbox.value.

In isblank, we're doing a couple if things.

  if (value.length == 0) {
    return true;
  }

First, we check to see if the field is truly blank - in other words, is it an
empty string. Rather than use the == "" test, we use a property of a string
object, the length property. I've found it to be more robust than the == ""
test. So, if the value.length is 0, then it is blank, and we return true. If
the string does not have a length of 0, our next task is to scan as much of the
string as we have to, to find out if there are any non-blank characters.

  for (i=0; i<value.length; i++) {
    if (value.charAt(i) != ' ' && value.charAt(i) != '\t' &&
        value.charAt(i) != '\n') {
      return false;
    }
  }

For this, we will use the for loop, which is perfectly suited for such a task.
We are going to examine each character in the string, and what we want to do is
return false if we find a non-blank. So we start at position 0, and keep
looping along the entire length of the string. We test for three blank
characters, the space, the tab, and the newline. The tests for the tab and
newline are probably not necessary, as they are hard to type in to a text box,
but they can appear in other widgets, the textarea in particular, so we'll be
proactive. The charAt() method belongs to the String object, and allows access
to a single character in a string. If the character at the current position is
not a space, a tab, or a newline, it must be a non-space. As soon as we know
that, we can return false, and we're done. If we go through the entire string
and never find a non-space, then we eventually finish the loop and return true.

So is the isblank test is a success, we alert the user. We add one more JS
method to the mix now, the focus() method. focus() is available to many
objects, but it is particularly useful with forms. It tells the cursor to go to
that field, to give it the user's focus. After you have told the user a field is
bad, it is nice to have the cursor sitting and waiting in the field the user has
an error in. It is a usability feature I will expect to see in your code.

Note the difference when you submit with good data in the box and without -
where is the cursor in both cases?

** JS3-3 - changes the contents of one box based on another

Changing data is as easy as reading it, and most of the properties of form
widgets are read and write.

  document.theform.outputbox.value = whatever;


** JS3-4 - a basic numeric test

We'll do a lot more on numeric testing, but this is a start. Once you're sure
the data is not blank, test to see if it is numeric. The parseFloat function
can be used to convert a string into a number. It is limited, but it works.

  num = parseFloat(value);

If value converts to a number, then num will hold that value. If the value
cannot be converted, then num will be set to a special value called "NaN", or
"not a number". The NaN value cannot be tested for directly, but JS includes
the isNaN() function to do the test for you:

  if (isNaN(num)) // then the num value holds a good number.

parseFloat is good, but not perfect. We will come up with a better isnum over
time.

Other widgets
-------------

Most of the rest of this lecture will be about how to use JS to interface with
the various form widgets.

textarea
button
submit
reset
checkbox
radio
hidden


Textarea
--------

The text area is nearly the same as the input type=text widget. The biggest
difference is how you insert a textarea:

<textarea name=bigtext></textarea>

The textarea can be named, just like a text box. To pre-fill the text area
with data, put the desired text in between the textarea start and end tags.
We will talk about textarea more when we come back to forms in the Perl
section of the class. As far as JavaScript is concerned, all the things you
can do with a text box, you can do with a text area.

Button
------

Using the button widget, we can create a button on the screen. With the
button's onClick event, we can trigger a function when the user clicks on the
button.

<input type=button name=tryit value="Click Me!" onClick="someFunc();">

The onClick can be used to submit the form:

  onClick="document.theform.submit();">

but please do not use this method. It only works if JS is available - if it is
not available, the button will be there but there will be no way to submit the
form. I use the button widget only when I know that JS is available.

** JS3-5 - button example.

Submit
------

To work intuitively, each form should have a submit widget.

  <input type=submit value="Submit">

Normally, this is all you need - there is rarely a time that you need to name
the button, and if you're satisfied with the default button text, there is no
need to use the value tag. When you click it, the form's onSubmit event is
fired. This also happens if you press ENTER in a text box (another nice thing
that goes away when you use the button widget).

In the example, there are actually two submit buttons. Note that you can have
each do something different by giving JS code to the button's onClick event. If
the onClick event returns false, the click is canceled and the submit does not
happen. If the onClick does not return false, the form's onSubmit event then
fires. See the difference between clicking Submit 1 and Submit 2. There is no
way for you to tell which submit button was clicked unless you code the buttons'
onClick events to tell the difference.

** JS3-6 - submit example.

Reset is much the same as the submit button - there is rarely any need for
multiple reset buttons.

Radio Buttons
-------------

<input type=radio name=yesno value=YES> Yes<br>
<input type=radio name=yesno value=NO> No

All radio buttons in a group have the same name, which is a perfect set up for
an array. When you create the array of radio buttons in HTML, an array of Radio
objects is also created in JS, as a property of the form.

document.theform.yesno[0]

The relevant properties of the Radio object are checked and value. checked is a
boolean which indicates which of the radio buttons in the group is checked.
Only one can be. value is the value specified in the HTML for that button. The
checked status can be changed.

Another useful property is the size of the array, using length - but we've seen
this before. With a for loop, we can determine the index number and value of
the checked button.

  yesno_selection = -1;
  for (i=0; i<document.theform.yesno.length; i++) {
    if (document.theform.yesno[i].checked == true) {
      yesno_selection = i;
      break;
    }
  }

If we get to the end of the loop, none of the buttons in the group were checked.

** JS3-7 - radio button example.

You can avoid having to do a check like this by using the checked keyword to
force one of the buttons to be checked by default. Once one is checked, you
cannot uncheck it.

Setting one button to checked forces all others to be unchecked:

  document.theform.yesno[0].checked = true;

Checkboxes
----------

Checkboxes look more like radio buttons on screen, but they act more like text
boxes, in that they are single objects, not members of an array.

  <input type=checkbox name=box1> <input type=checkbox name=box2>

This creates two distinct objects. The status of a checkbox can be checked or
changed by using booleans on the checked property.

** JS3-8 - example of a checkbox validation


Select list
-----------

The select list is the oddball of the group, both in terms of the HTML needed
to set it up and the JS needed to validate it.

<select name=select_list>
  <option>A</option>
  <option>B</option>
</select>

You can also specify a short name with a long label:

  <option value=A>Select this one for option A</option>

In the form is a select list object. That object contains several properties
that we'll use. The first is the selectedIndex:

  selected = document.theform.select_list.selectedIndex;

selectedIndex will be equal to the index number of the member selected, or -1 if
nothing was selected. Note that I am creating a new variable for simplicity's
sake, to avoid retyping the long bit of code. The array it indexes into is the
options array of the select list object:

  value = document.theform.select_list.options[selected].value;

The value stored in the option is the option text, if no value is given, or the
value if one is. There is also a text value, which is filled with the data
between the opening and closing options tag:

  <option>data             -- value is "data", text is "data"
  <option value=1>data     -- value is "1", text is "data"

Normally, you would test to see if the selectedIndex is -1 to see if nothing is
chosen, but you might have the first option in the list also be an unused
option, with explanatory text. In that case, you would want -1 or 0 to
indicate that no choice had been made:

  if (selected <= 0) {
    alert("Please choose an option");
  }

** JS3-9 - examples of various select lists

The first example is a standard list, where the option text is the option
value. In the second example, there is an explanatory note on the 0th member
of the list, which should not be chosen. The last two are the same, except one
reports the option's text, and the other the option's value. Both are
accessible, and both can be changed by JavaScript.

The last one uses a slightly different technique. First, it does not use
selectedIndex at all, but instead grabs name.value, where name is the select
tag's name. This returns the value of the option tag that was selected. This
is more convenient, but is also newer functionality. The selectedIndex version
works everywhere, so gives maximum compatibility. Accordingly, setting the
value finds the matching option in the list and selects it.

Note one other thing about this page - here I have multiple forms, and so I have
multiple validations, one for each.

** JS3-10 - an example of a multiple-select list

There is one other form of the select list that we can use, though it is less
common than the single-select we've already seen: multiple-select. When you
use the multiple attribute in the select tag, the user is no longer limited to
just one choice. By using their ctrl key, they can select multiple entries
from the list.

The JS used to process these choices is not too surprising, but now the
selectedIndex and ".value" methods are useless. We need to process the list as
a list. We need to examine each option's selected property to see if it is set
to true.

Hidden
------

The hidden widget is set up pretty much the same as the text box widget. The
biggest difference, however, is that the hidden widget is hidden. It is used
to pass data to another page or program, but with the user having no control
over that data. Hidden tags are much more useful when we know how to submit
data to a CGI program. One example of using a hidden tag might be as follows:

  selected = document.theform.select_list.selectedIndex;
  text = document.theform.select_list.options[selected].text;
  document.theform.hiddentag.value = text;

Here, we are saving the selected item's text in the hidden tag named
"hiddentag". The name of the selected data will now be sent to any CGI that
processes this form - normally only the value of the selected item is sent.


Processing mixed input forms
----------------------------

Normally, you know all of the names and values in a form because you set them.
But what if the form has no names for some particular reason... can you figure
out what kind of widgets a form has?  Yes. See Example 15-1 in the text for
one take.

**JS 3-11 - another take


** JS3-12 - a more real-world example

This is exactly the kind of thing a real form might have - a series of boxes
which must be filled in. Using the isblank, we can ensure that all the data
that is sent to the server is filled in properly. Note how we handle the
address, testing to see if one or the other of the two fields is filled in, and
not requiring both.

** JS3-13 - another validation routine

This one checks an input box for a valid zip code, using a combination of for
loops and character tests. What we're looking for is a specific pattern of
five numbers or five numbers followed by a dash and four more numbers. The
zip+4 will not work with parseFloat, so we have to write our own function to
test the zip code.