Creating Forms

Embedded Server Pages provides integrated support for processing client submitted data and forms. Whereas the venerable CGI interface usually required separate web pages and programs to display  and process forms, ESP provides a single integrated facility that allows a single ESP page to both display and process forms. This greatly reduces the code and complexity of creating dynamic user interfaces.

Accessing Client Data

The HTTP standard defines two methods for accepting user submitted data: GET and POST requests. GET requests are normally used for simple queries and commands where state is not modified. POST requests often contain more submitted data and typically are used to modify server state in some fashion.

Embedded Server Pages provides convenient access to client submitted data from both GET and POST requests. For each HTTP request, the ESP JavaScript forms[] array variable stores client submitted data. For both GET and POST requests user data is converted to keyword / value pairs and stored in the forms[] array.

The ESP forms[] array is an associative array where the array index is the keyword string. Using the keyword as an index allows the value for the client input field to be accessed. For example, if a web page used the following form HTML code:

<form name="userDetails" method="POST" action="userDetails.esp"> 
    <input name="firstName" type="text" value="">
    <input name="submit" type="submit" value="OK">
</form>

Then the following ESP code in the userDetails.esp file would extract the value typed by the user in the firstName field.

<% write("User name is " + forms['firstName']); %>

Note that you can use either single or double quotes in JavaScript around the array index. Often, when nesting quotes inside HTML you will need to use one quote form or the other. You can also directly access ESP variables using the @@ prefix notation.

<p>First Name: @@forms["firstName"]</p>

If an HTML input field name is supplied in both the query string and in a POST input field, the values are catenated in the forms array.

ESP Arrays

ESP also defines several key variable collections that store request status that are of interest when processing input forms. The following variables are a subset of what is available. See the JavaScript API for full details.

request[]

Keyword	Description
AUTH_TYPE	The authorization type (basic or digest) if authorization is being used.
CONTENT_LENGTH	The length of any posted reqeust content.
PATH_INFO	The portion of the path after the script name if extra path processing is being used. See the ExtraPath directive.
PATH_TRANSLATED	The physical path corresponding to PATH_INFO.
REQUEST_METHOD	The HTTP request method (GET|HEAD|OPTIONS|PUT|TRACE).
REQUEST_TRANSPORT	The request protocol used (http|https).
REQUEST_URI	The request URL portion after the site name with the query stripped off
QUERY_STRING	The request query string.
SCRIPT_FILENAME	The physical path name for SCRIPT_NAME.
SCRIPT_NAME	The name of the script in the URL. Useful to know the name of the current URL (without the directory portion). Use in the action keyword of a HTML form tag to refer to the current page for post-back.
SESSION_ID	Unique identifier for this session state store.

headers[]

Keyword	Description
HTT_REFERER	Referring URL. (i.e. the URL that linked to this current page).
HTTP_USER_AGENT	Description of the client's browser.

server[]

Keyword	Description
SERVER_ADDR	Destination IP address of this request. (i.e. The server address).
SERVER_PORT	Destination PORT of this address (i.e. The server port).
SERVER_PROTOCOL	Set to http for plain old HTTP. Set to https if using SSL.

Post-Back

Embedded Server Pages can be used to create web pages with dynamic data and it can also be used to process submitted user input. In fact, a single page can do both tasks. This paradigm where a single page supports both output and input is called "post-back" because the user data is posted back to the originating web page.

Post-back forms have a key advantage that they aggregate the logic in one place that deals with a specific user interaction with the application. By placing conditional code at the top of the page, it is easy to code a single page to do both tasks. Furthermore, it is much easier to re-display the web page after processing the input form when using post-back.

A useful trick is for the HTML form tag to specify request['SCRIPT_NAME'] as the action attribute. This evaluates to the name of the current web page. In this manner, the page can be renamed without breaking the script.

The paradigm for creating ESP forms using Post-back is to test at the top of the page before doing significant output whether the request is a POST request. This is done by testing to see if the request['REQUEST_METHOD'] is set to "POST". If so, the user input can be validated or alterntively you can create a custom JavaScript function to process the submitted data. It is recommended that validation of user input always be done at the server end rather than relying solely on client side validation. Even if client-side JavaScript validation is used, it is still essential to re-validate at the server-side for security.

The following HTML fragment demonstrates Post-back. It displays a simple form prompting the user for a name and address. If the user clicks Ok, then the page is re-run using the POST method. In that case, the processUserData() function is called with the entered name and address.

<%                                                              
    if (request['REQUEST_METHOD'] == "POST") {
        //
        //  Post-back. Process user data.
        //
        if (ok == "Cancel") {
            redirect(prev);                                                                                
         } else if (ok == "Ok") {
            // Can do first pass validation of user data here
            processUserData(form['name'], form['address']);
         }                                                                                
    } else {
         // 
         //  Normal GET request on the page
         //
         form['name'] = "Your Name";
         form['address'] = "Your Address";
    }
%>

<form method="POST" action="@@requst['SCRIPT_NAME']">
<table class="inputForm" border=0>
<tr>
    <td><b>Name</b></td>
    <td><input name="name" type="text" value="@@form['name']"></td>
</tr>
<tr>
    <td><b>Address</b></td>
    <td><input name="address" type="text" value="@@form['address']"></td>
</tr>
</table>
<input type="submit" name="ok" value="Ok">
<input type="submit" name="ok" value="Cancel">
</form>

Redirection

Often it is necessary to transfer the client to another web page. ESP provides a simple mechanism via the redirect JavaScript command to transfer to another URL. Because ESP buffers output data, you can call redirect even after doing some output. You should keep the output to a minimum as once the ESP output buffer is exceeded, the HTTP headers will be output and you will not be able to redirect the client's browser. The ESP output buffer is configurable via the LimitResponseBody configuration directive. It is set by default to 64K. For example:

<% 
    if (form['submit'] == "Cancel") {
        redirect("home.esp");
    }
%>

Custom Headers

Some HTTP clients require custom headers. The HTTP protocol allows server applications to define custom headers which can then transmit arbitrary information in the HTTP header. ESP provides the setHeader command.

Similarly to the redirect command, you can call setHeader even after doing some output. However, you must call it before exceeding the ESP output buffer. See redirect for more information.

For example:

<%
    setHeader("MyCustomHeader: order number" + orderNumber);
%>