1. CGI in Context CGI is Common Gateway Interface, supporting a greater degree of interaction between the user and a Web page, most commonly by means of a FORM. A FORM contains a number of elements each of which has a name. When the form is submitted a list of names and values is transmitted, using CGI protocols, indicating the contents of the form.

2. CGI processes The server transmits the document over the communication link. The browser renders the document, including the FORM. The user completes the FORM and submits it. The name/value pairs from the FORM are transmitted back to the server. The server starts the process identified in the FORM header and supplies the name/value pairs to it. The process takes some action, determined by the name/value pairs, and outputs a properly formatted HTML document. The HTML document produced by the process is returned to the browser as the response from the server to the user's input on the original FORM.

3. Form Basics <FORM ACTION = "http:\\www.sbu.ac.uk\cgi-bin\ cgiwrap\~fintan\cgiteach\test.cgi" METHOD = "POST"> Details of the form here The ACTION argument should be all on one line, it identifies the server-side process which will accept the information from the form and return a reply to the browser. The METHOD should always be POST. The server-side process given does exist and will return a list of name/value pairs from the form.

4. Submit & Reset Buttons <INPUT TYPE=SUBMIT NAME=CgiName VALUE="Button Label" > Pressing a submit button will transmit all the name/value pairs from the browser to the server <INPUT TYPE=RESET VALUE="Button Label" > Pressing a reset button will cause the form to clear all components back their default values

5. INPUT - TEXT Element <INPUT TYPE=TEXT NAME=CgiName {SIZE=VisibleSize} VALUE="Initial Value"> TEXT elements supply a single-line text input area. The SIZE argument determines the (approximate) number of characters to display, not the maximum number that can be entered. The VALUE argument determines the default contents.

6. SELECT - Pull-down menu OptionName etc. etc. etc. The options will be presented on a pull-down menu, with the first selected by default. The value part of the name/value pair will be the item selected when the form is submitted.

7. INPUT - Radio Buttons <INPUT TYPE=RADIO NAME=Colour VALUE=Red > Red <INPUT TYPE=RADIO NAME=Colour VALUE=Orange > Orange All tags with the same NAME act as a set of radio buttons and the value submitted will be the VALUE of the selected radio button. The button label is not the VALUE, but the text between the and tags.

8. INPUT - check boxes The TYPE argument specifies a checkbox, CHECKED specifies that it should be ticked by default. Only boxes that are ticked will send a NAME/VALUE pair to the server. If more then one checkbox has the same name a list of VALUEs is sent. <INPUT TYPE=CHECKBOX CHECKED NAME=Colour VALUE=Red > Red <INPUT TYPE= CHECKBOX NAME=Colour VALUE=Orange > Orange

9. SELECT - selection box The SIZE argument indicates that a element should be a selection box, not a pull-down menu. MULTIPLE indicates that more than one element may be selected. <SELECT NAME=CgiName SIZE=NumberVisible MULTIPLE> OptionName etc. etc. etc. The NAME/VALUE pair will not be sent if none are selected and will be a list if more than one is selected.

10. TEXTAREA COLS & ROWS, if specified, override the default size. They only specify the visible size of the field and do not prevent the user from typing much more. The entire contents are sent as the VALUE part of the NAME/VALUE pair. <TEXTAREA NAME=CgiName COLS=NumCols ROWS=NumRows> Default contents

11. PASSWORD A single line text field which does not echo the user’s input as they type. But should not be assumed to be secure when transmitted across the Web. <INPUT TYPE=PASSWORD NAME=CgiName VALUE="Default" >

12. IMAGES Acts as a SUBMIT button in its own right. In this format sends two name value pairs, CgiName.x and CgiName.y, containing the location of the mouse pointer when it was clicked. More complex formats allow server- or client- side image maps that can associate links with various parts of the image. <INPUT TYPE=IMAGE NAME=CgiName SRC=Filename>

13. Form Usability Layout of a FORM is vital if it is to be used effectively. The sequence in which the fields are presented and the language used to indicate to the user what to do are important. The most effective layouts can only be attained by using a to ensure that fields are vertically aligned. Using CGI it is not possible to validate a user’s input until the form is complete and has been submitted. Combined with the latency of the Web this can be very frustrating. Client-side scripting (next two lectures) can be used to validate upon entry or upon submission.

14. CGI Process The form processing in these notes will use Tcl, not PERL. <FORM ACTION=“http://www.sbu.ac.uk/cgi-bin/cgiwrap/ ~myuserid/mycgiscript.cgi” METHOD = POST> The ACTION argument has to be on a single line and identifies the name of a file ( mycgiscript.cgi ) which must be in the cgi-bin subdirectory of the.public_html directory and must have execute permissions. #!/usr/local/bin/bash export env./myformexample.tcl This is a minimal.cgi file that exports the current environment and then starts a tcl process. The tcl process is scripted in the source myformexample.tcl, which must also have execute permission.

15. AddUp FORM <FORM ACTION="http:\\www.sbu.ac.uk\cgi-bin\cgiwrap\ ~fintan\addup.cgi" METHOD="POST"> Enter two numbers and then press Submit.

16. addup.tcl #!/usr/local/bin/tclsh # Filename myformexample.tcl. Example Tcl CGI # script. # # Fintan Culwin, v0.1, March 1996. source GetPostedData.tcl GetPostedData The first thing the tcl process has to do is to decode the CGI protocol encoded name/value pairs. There are two ways to do this …. Write your own routine … Copy one from ~fintan/.public_html/cgi-bin/GetPostedData.tcl Assuming that you have done this, and copied GetPostedData.tcl into your cgi-bin directory, the start of the addup.tcl file is: This calls the GetPostedData routine and places the values into an associative array whose index values are the names.

17. addup.tcl - HTML header # Output the appropriate MIME header puts "Content-type: text/html” puts "” # Output a complete HTML header.... puts " \n " puts " \nAdd Up Script\n " puts " \n\n " Which produces this on the tcl processes’ output stream. This stream is connected back to the browser which submitted the form in the first place. Content-type: text/html Add Up Script

18. addup.tcl - 3 puts " \nThis document was generated " puts -nonewline "by a tickle script on ” puts -nonewline [ exec date ] puts ".\n \n " This document was generated by a tickle script on Tue Mar 5 12:27:16 GMT 1996.

19. addup.tcl - 4 # Calculate the answer set TheAnswer [ expr $FormData(FirstNumber) +...... $FormData(SecondNumber)] # Send the information back to the browser puts " \n$FormData(FirstNumber) “ puts “ plus $FormData(SecondNumber) \n" puts "is $TheAnswer. \n " 54 plus 22 \n is 76.

20. addup.tcl - 5 puts " ” puts -nonewline " ” puts "Return to FORMs addup example.” puts " \n \n \n ” puts “ ” Return to FORMs, addup example.

21. Visitor’s Book - Context In this the information received from the form is used to update files held on the server, and the contents of those files are used to supply the contents of the reply.

22. Visitor’s Book - HTML <FORM ACTION="http:\\www.sbu.ac.uk\cgi-bin\cgiwrap\ ~fintan\visitor.cgi" METHOD="POST"> Visitor's Book Please enter your personal name and your family name

23. Visitor’s Book - CGI - 1 puts "Content-type: text/html" puts "" # Output a complete HTML header.... puts " \n " puts " \nVisitor's Book\n " puts " \n\n " # Obtain the data from the form GetPostedData puts " Mr. Blobby's Visitor's Book\n \n " if { ( [ info exists FormData(PersName)]) && ( [ info exists FormData(FamName)]) } { ProcessForm } else { puts " \nThank you for visiting my home page.\n " puts " Maybe next time you will leave your name.\n \n " } This makes sure that the user has replied.

24. Visitor’s Book - CGI - 2 proc ProcessForm {} { global FormData # Store the information from the form (in html) format # at the end of a file called 'visitors.dat'. # Open the file in append (a) mode. set FileId [ open visitors.dat a ] # Write the information in HTML format as a single line puts -nonewline $FileId $FormData(PersName) puts -nonewline $FileId $FormData(FamName)" puts -nonewline $FileId " visited on " puts -nonewline $FileId [exec date] puts $FileId # close the visitors.dat file close $FileId This adds their details to the end of the visitors.dat file.

25. Visitor’s Book - CGI - 3 # Obtain the number of visitors from visitors.num file. set FileId [ open visitors.num r ] gets $FileId NumVisitors close $FileId # Then increment the value and return it to the file. incr NumVisitors set FileId [ open visitors.num w ] puts $FileId $NumVisitors close $FileId This obtains the number of visitors from the visitors.num file, increments it and writes it back to the file.

26. Visitor’s Book - CGI - 4 # Finally send the information back to the user. puts " \nHello $FormData(PersName)!" puts " " puts " Your are visitor number $NumVisitors. " puts "previous visitors have included:" puts " \n \n " set Visitors [exec tail visitors.dat] puts $Visitors puts " \n \n " puts "Please call again some time.." puts " " This writes the reply to the user, in HTML format, onto the output stream. (The Unix tail command will obtain the last 20 lines from the file specified).

27. Visitor’s Book - reply