MySQL Cookbook

18.2 Creating Forms in Scripts

18.2.1 Problem

You want to write a script that gathers input from a user.

18.2.2 Solution

Create a fill-in form from within your script and send it to the user. The script can arrange to have itself invoked again to process the form's contents when the user submits it.

18.2.3 Discussion

Web forms are a convenient way to allow your visitors to submit information, for example, to provide search keywords, a completed survey result, or a response to a questionnaire. Forms are also beneficial for you as a developer because they provide a structured way to associate data values with names by which to refer to them.

A form begins and ends with <form> and </form> tags. Between those tags, you can place other HTML constructs, including special elements that become input fields in the page that the browser displays. The <form> tag that begins a form should include two attributes, action and method. The action attribute tells the browser what to do with the form when the user submits it. This will be the URL of the script that should be invoked to process the form's contents. The method attribute indicates to the browser what kind of HTTP request it should use to submit the form. The value will be either GET or POST, depending on the type of request you want the form submission to generate. The difference between these two request methods is discussed in Recipe 18.6; for now, we'll always use POST.

Most of the form-based web scripts shown in this chapter share some common behaviors:

• When first invoked, the script generates a form and sends it to the user to be filled in.

• The action attribute of the form points back to the same script, so that when the user completes the form and submits it, the script gets invoked again to process the form's contents.

• The script determines whether it's being invoked by a user for the first time or whether it should process a submitted form by checking its execution environment to see what input parameters are present. For the initial invocation, the environment will contain none of the parameters named in the form.

This approach isn't the only one you can adopt, of course. One alternative is to place a form in a static HTML page and have it point to the script that processes the form. Another is to have one script generate the form and a second script process it.

If a form-creating script wants to have itself invoked again when the user submits the form, it should determine its own pathname within the web server tree and use that value for the action attribute of the opening <form> tag. For example, if a script is installed as /cgi-bin/myscript in your web tree, the tag can be written like this:

<form action="/cgi-bin/myscript" method="POST">

Each API provides a way for a script to obtain its own pathname, so you don't have to hardwire the name into the script. That gives you greater latitude to install the script where you want.

In Perl scripts, the CGI.pm module provides three methods that are useful for creating <form> elements and constructing the action attribute. start_form( ) and end_form( ) generate the opening and closing form tags, and url( ) returns the script's own path. Using these methods, a script can generate a form like this:

print start_form (-action => url ( ), -method => "POST");
# ... generate form elements here ...
print end_form ( );

Actually, it's unnecessary to provide a method argument; if you omit it, start_form( ) supplies a default request method of POST.

In PHP, a simple way to get a script's pathname is to use the $PHP_SELF global variable:

print ("<form action=\"$PHP_SELF\" method=\"POST\">\n");
# ... generate form elements here ...
print ("</form>\n");

However, that won't work under some configurations of PHP, such as when the register_globals setting is disabled.^[1] Another way to get the script path is to access the "PHP_SELF" member of the $HTTP_SERVER_VARS array or (as of PHP 4.1) the $_SERVER array. Unfortunately, checking several different sources of information is a lot of fooling around just to get the script pathname in a way that works reliably for different versions and configurations of PHP, so a utility routine to get the path is useful. The following function, get_self_path( ), shows how to use $_SERVER if it's available and fall back to $HTTP_SERVER_VARS or $PHP_SELF otherwise. The function thus prefers the most recently introduced language features, but still works for scripts running under older versions of PHP:

^[1] register_globals is discussed further in Recipe 18.6.

function get_self_path ( )
{
global $HTTP_SERVER_VARS, $PHP_SELF;

    if (isset ($_SERVER["PHP_SELF"]))
        $val = $_SERVER["PHP_SELF"];
    else if (isset ($HTTP_SERVER_VARS["PHP_SELF"]))
        $val = $HTTP_SERVER_VARS["PHP_SELF"];
    else
        $val = $PHP_SELF;
    return ($val);
}

$HTTP_SERVER_VARS and $PHP_SELF are global variables, but must be declared as such explicitly using the global keyword if used in a non-global scope (such as within a function). $_SERVER is a "superglobal" array and is accessible in any scope without being declared as global.

The get_self_path( ) function is part of the Cookbook_Webutils.php library file located in the lib directory of the recipes distribution. If you install that file in a directory that PHP searches when looking for include files, a script can obtain its own pathname and use it to generate a form as follows:

include "Cookbook_Webutils.php";

$self_path = get_self_path ( );
print ("<form action=\"$self_path\" method=\"POST\">\n");
# ... generate form elements here ...
print ("</form>\n");

Python scripts can get the script pathname by importing the os module and accessing the SCRIPT_NAME member of the os.environ object:

import os

print "<form action=\"" + os.environ["SCRIPT_NAME"] + "\" method=\"POST\">"
# ... generate form elements here ...
print "</form>"

In JSP pages, the request path is available through the implicit request object that the JSP processor makes available. Use that object's getRequestURI( ) method as follows:

<form action="<%= request.getRequestURI ( ) %>" method="POST">
<%-- ... generate form elements here ... --%>
</form>

18.2.4 See Also

The examples in this section all have an empty body between the opening and closing form tags. For a form to be useful, you'll need to create body elements that correspond to the types of information that you want to obtain from users. It's possible to hardwire these elements into a script, but Recipe 18.3 and Recipe 18.4 describe how MySQL can help you create the elements on the fly based on information stored in your database.