In your scripts you will often want to get information about a user, for example, the type of browser the user is running. You may also want to get information from a user, for example the information sent by the user in an HTML form. FoxWeb's Request object makes accessing this information easy.
The Request object gives you access to any information that is passed with an HTTP request. This includes:
| Form Fields | This is the collection of values of form elements posted to the HTTP request body by a form using the POST method. |
| Query String | The values of variables in the HTTP query string. The query string is the portion of a URL after the question mark. |
| Cookies | The values of cookies sent by the browser as part of the HTTP request. Cookies allow a set of information to be associated with a user. |
| Server Variables | ServerVariables contain header information sent as part of the HTTP request header as well as information provided by the Web server, regarding the current request. |
The request object provides a set of methods and properties that expose this information to the programmer.
HTML forms are the most frequently used method for getting information from a Web user. A form�s text boxes, option buttons, and check boxes, displayed on an HTML page in a browser, provide the user an easy way of submitting information. When the user clicks the Submit button, the browser sends the collected information to the Web server.
For example, the following HTML tags generate a form where a user can enter their first name, last name, gender and interests, and includes a button for submitting information to a Web server. The form also contains an hidden input tag (not displayed by the Web browser) that you can use to pass additional information to a Web server.
<FORM ACTION="register.fwx" METHOD="Post"> |
The above form looks like this:
Detailing the complete set of HTML form tags is outside the scope of this topic, however, there are numerous sources of information that you can use to learn about creating useful and engaging HTML forms. One method is to use your Web browser's source viewing feature to examine how HTML forms are created on other Web sites. Another good resource is the ContactMine sample application that is installed when you install FoxWeb on your server.
Once you create an HTML form, you will need to process user input, which means sending the information to a FoxWeb script file for processing. Looking at the HTML code from the previous example, you will notice that the <FORM> tag's ACTION attribute refers to a file called register.fwx. When the user submits HTML information, the browser uses the POST method to send to the information to a server side program -- in this case register.fwx. The .fwx file may contain scripts that process information and interact with other scripts, or resources, such as a database.
Using FoxWeb, there are three basic ways to collect information from HTML forms:
Depending on the situation you may find yourself using any of the three techniques above. The latter technique is particularly useful for validating form input, because based on the outcome of the validation process, the script may return the form so that the user can revise his/her input, or (if the input is validated successfully) it may continue with further processing of the input.
When constructing an HTML form you can instruct the browser to use one of two methods to send the form data to your application. The FORM tag's METHOD clause determines whether the form is submitted using the POST or the GET method. Omitting the METHOD clause causes the browser to default to the GET method. With the POST method, browsers send form data to the Web server in the HTTP request body. Data sent with the GET method, on the other hand, is URL-Encoded and appended to the end of the URL in an area known as the Query String. In most cases it is preferable to use the POST method. When using the GET method you risk losing some of the form data, because most servers (including FoxWeb) impose a limit on the size of the Query String.
The Request object provides three methods that provide access to the fields of forms submitted using the POST method:
The Form method returns the value of a particular HTML form field. For example, Request.Form("FullName") may return "Joe Smith".
The FormCount method, returns the number of instances of a field with the same name submitted. In the above example, if the user checks both "Golfing" and "Tennis" then Request.FormCount("interests") will return 2.
Finally, the FormArray method can be used to populate an array, with the select field names submitted by the user. Depending on whether the optional FieldName parameter is passed to this method, FormArray either populates the array with all form fields, or fields that match the name passed to it.
The QueryString contains values passed to your script as text following a question mark in the URL. The values can be appended to the URL by using either the HTTP GET method or by manually appending the values to the URL.
For example, if the previous form example used the GET method instead of the POST method in the FORM tag and the user typed "Joe", "Smith", "Male", "Golfing", "Tennis", then the following URL would be sent to the script:
http://ServerName/register.fwx?FullName=Joe+Smith&gender=M&interests=golf&interests=tennis&database=visitors
Even if you choose not to use the GET method in your forms, the Query String is still a useful method of exchanging information with the user in cases where you simply want to provide hyperlinks instead of an HTML form for parts of your application's user interface:
<a href="register.fwx?action=new">Register a new user profile<a><br> |
FoxWeb's Request object provides four methods to expose the values sent as part of the Query String:
The QueryString method returns the value of a particular Query String field. For example, Request.QueryString("FullName") may return "Joe Smith".
The QueryStringCount method, returns the number of instances of a field with the same name submitted.
The QueryStringArray method can be used to populate an array, with the values submitted by the user in the Query String.
In addition to the above methods, the ServerVariables("QUERY_STRING") method of the Request object can be used to access the full text contained in the Query String portion of the URL.
The information sent in the Query String does not need to be broken in name/value pairs. If you are simply trying to send a single value to your application, you can simply append that value after the question mark like so:
<a href="ShowFont.fwx?helvetica">Display text sample in Helvetica font<a>
|
Cookies are tidbits of information that Web servers can embed in a user's Web browser. The next time the same browser requests a page, it sends the cookie back to the Web server. FoxWeb provides commands to both set and retrieve cookies. For more information refer to the Session Management topic.
The Server Variables is a collection of values that provides information from the HTTP headers that are passed along with a user�s request as well as information provided by the Web server, regarding the current request. FoxWeb's Request object provides access to these values with the ServerVariables method. We have already seen a use of this method above, where it was used to retrieve the contents of the Query String. Some of these variables are more useful than others. If you decide to generate browser-specific HTML, you will most certainly use the Server Variable HTTP_USER_AGENT, which returns the type of browser making the current request. In some cases you will use the HTTP_REFERER variable to find which site referred the user to the current URL.
The complete list of Server Variables available to a script varies, depending on the browser and Web server being used, as well as the type of request. We include a list common Server Variables in the Reference section.
Following is a script that makes use of the REMOTE_ADDR variable to determine the IP-Address of the user. It provides a different response depending on whether the user originates from a particular domain:
|