1. Form

   Form is a window that connects client to CGI program on the server. Several control components (widgets) such as checkbox help complete this task. 'action' attribute of the _form command has a URL value that refers to a CGI program. 'method' attribute has one of the value GET, POST, and ENCTYPE. GET method sends the information through env variables; POST method sends the information through stdout; and ENCTYPE method specifies the MIME type for POST data (default 'application/x-www-form-data').

   _html
   _head
     _title; _quote "Form"; title_
   head_
   _body
     _form "action='/cgi-bin/form.sml' method='POST'"
     form_
   body_
   html_

2. Button
   • Submit

     'submit' button will send the name=value string to a CGI program. The 'type' attribute of the _input command must be the value 'submit'. The 'value' attribute sets the label of a button (default submit). Finally, 'name' attribute sets the submit name.

     _html
       _head
         _title
           _quote "Submit Button"
         title_
       head_
     _body
       _form "action='/cgi-bin/form.tcl' method='POST'"
       _input "type='submit' name='submit_name' value='button_label'"
       form_
       body_
     html_

   • Reset

     Reset button clears all the input data. The 'type' attribute of a _input command must be the value 'reset'.

     _html
     _head
       _title
         _quote "Reset Button"
       title_
     head_
     _body
       _form "action='/cgi-bin/form.sml' method='POST'"
         _input "type='reset'"
       form_
     body_
     html_

   • Image

     When user clicks on an image button, browser will send the coordinates of the mouse clicking point to a CGI program. The 'type' attribute of the _input command has the value 'image'; 'src' attribute specifies the file name of the image; and the 'name' attribute is the button id.

     _html
     _head
       _title; _quote "Image Button"; title_
     head_
     _body
       _form "action='/cgi-bin/form.sml' method='POST'"
         _input "type='image' src='icon.gif' name='icon'"
       form_
     body_
     html_

3. EditBox

   Editbox will open a box with width specified in the 'size' attribute. When 'type' attribute has the value 'text', _input command allows you input text in an editbox. If 'type' has the value 'password', the input characters will be displayed as asterisks. The 'hidden' value of 'type' will hide editbox from display.

   'name' attribute of the _input command specifies the name of an editbox. The 'value' attribute specifies the initial string in the editbox (default 'string'). 'maxlength' attribute specifies the max length of a string.

   _html
   _head 
     _title; _quote "EditBox"; title_
   head_
   _body
     _form "action='/cgi-bin/form.tcl' method='POST'"
       _input "type='text' name='user' size='20' maxlength='50'"
     form_
   body_
   html_

4. RadioBox

   Radiobox is a group of circle buttons that only one can be checked. The 'type' attribute in an _input command has the value 'radio'. In a group of radiobox all of them must be the same 'name' attribute. However, they must be different in the 'value' attribute. A CGI program will receive the selected radiobox. 'CHECKED' attribute sets a radiobox as default.

   _html
   _head
     _title; _quote "RadioBox"; title_
   head_
   _body
     _form "action='/cgi-bin/form.tcl' method='GET'"
       _quote "First"
       _input "type='radio' name='order' value='first'"
       _quote "Second"
       _input "type='radio' name='order' value='second'"
     form_
   body_
   html_

5. CheckBox

   Checkbox is a group of square buttons that can be checked on or off. The 'type' attribute of a _input command has the value 'checkbox'. Each checkbox must have a different 'name' attribute. The checked box will send a value 'on' to a CGI program in default. When the 'value' attribut is defined the name=value will be send. The 'CHECKED' attribute sets a checkbox on as default. You may check more than one box at the same time.

   _html
   _head
   _title; _quote "CheckBox"; title_
   head_
   _body
     _form "action='/cgi-bin/form.tcl' method='GET'"
       _input "type='checkbox' name='red' CHECKED"
       _input "type='checkbox' name='green'"
       _input "type='checkbox' name='blue' CHECKED"
     form_
   body_
   html_

6. MenuBox

   MenuBox shows a long selectable list in a small space. The 'size' attribute in _select command sets to 1 will make the form work as a menubox. An _option command lists an item. The 'SELECTED' attribute in the _option command selects this item as default.

   _html
   _head
     _title; _quote "MenuBox"; title_
   head_
   _body
     _form "action='/cgi-bin/form.tcl' method='GET'"
       _select "name='color' size='1'"	
         _option; _quote "red"
         _option; _quote "green"
         _option SELECTED; _quote "blue"
       select_
     form_
   body_
   html_

7. ListBox

   Similar to the MenuBox, however, ListBox must set 'size' a greater than 1 value in the _select command. It is displayed as scrolled list. 'MULTIPLE' attribute in the _select command will allow you select multiple items.

   _html
   _head; _title; _quote "ListBox"; title_; head_
   _body
     _form "action='/cgi-bin/form.tcl' method='GET'"
       _select "name='color' size='2' MULTIPLE"
       _option; _quote red
       _option; _quote green
       _option SELECTED; _quote blue
       select_
     form_
   body_
   html_

8. EditText

   _textarea command defines a scrolled text editbox with attribute 'rows' and 'cols'. The 'name' attribute specifies the name of a text area. Unlike the HTML text, the text in an EditText area will not ignore newlines.

   _html
   _head
     _title; _quote "EditText"; title_ 
   head_
   _body
     _form "action='/cgi-bin/form.tcl' method='GET'"
       _textarea "rows='20' cols='40' name='words'"
       _quote "Demo of Text Editor."
       textarea_
     form_
   body_
   html_

9. CGI and Form

   Client Form is a basic interactive interface connected to a CGI program. Client browser encodes form data by using a MIME type. The default MIME type in the ENCTYPES attribute is application/x-www-form-urlencoded. The value of 'name' attribute attached with '=' and the entered string construct a key/value pair. All the pairs are linked by the '&' character to form a string. CGI encoder will translate control characters into hexadecimal codes with the prefix '%'. For example, the space character is translated to %20.

   For EditBox and EditText in a form if user did not input anything, the value will be left to empty. For RadioBox and CheckBox in a form if a box is checked, the value will be the string in 'value' attribute. Its default value is 'on'. A client will not send a key/value pair if a box is not checked. For MenuBox and ListBox a client will send a key/value pair if user select the item of a _option command.

   Following procdure describes how a CGI program decode the data. First, it checks REQUEST_METHOD environment variable. If the value is GET then read QUERY_STRING and PATH_INFO, otherwise, get the CONTENT_LENGTH and read data from the stdin. In GET method, the QUERY_STRING is the string that has been appended to the URL after the '?' character. It is possible to access a CGI program without using a form. Furthermore, CGI program splits the string to get the key/value pairs. Finally, CGI program converts the hexadecimal and '+' characters for all the key/value pairs. It also sets an array where key is index and value is an elemnet. The ParseForm program has an error checking as well.

   #
   # Report      report the exception
   #   status    server status
   #   keyword   short description
   #   message   detail description
   #
   proc Report {status keyword message} {
     _quote "Status: $status; 
             Keyword: $keyword; 
             Message: $message"
   }
   
   #
   # ParseForm   parse CGI string
   #   aFormInfo return form data array with key/value. 
   # Return      RESULT_OK or RESULT_ERROR
   #
   proc ParseForm {aFormInfo} {
     upvar $aFormInfo sFormData
   
     set sMethod $::env(REQUEST_METHOD)
     switch -exact -- $sMethod {
       POST {set sQuery [file::read stdin $::env(CONTENT_LENGTH)]}
       GET  {set sQuery $::env(QUERY_STRING)}
       default {Report  500 "server error" "unsupport method"
                return RESULT_ERROR}
     }
   
     set pairs [string::split $sQuery &]
     foreach item $pairs {
       set pair [string::split $item "="] 
       set key [list::index $pair 0]
       set value [list::index $pair 1]
   
       regsub -all {\+} $value { } value
       set range {[0-9a-fA-F]}
       while {[regexp "%$range$range" $value match]} {
         scan $match "%%%x" hex
         set symbol [string::format %c $hex]
         regsub -all $match $value $symbol value
       }
   
       if {[info exists sFormData($key)]} {
         string::append sFormData($key) "\0" $value
       } else {
         set sFormData($key) $value
       }
     }
     return RESULT_OK
   }
   
   #
   # cgi main program
   #
   #!/usr/local/bin/tclsh8.0
   _cgi {Content-type: text/html}
   _html
     _head 
       _title 
         _quote "CGI Form Program Sample"
       title_ 
     head_
    _body
   
     if {[string::compare [ParseForm sForm] RESULT_OK] == 0} {
       foreach item $sForm {
         _quote "$item=$sForm($item)"
       }
     }
   
     body_
   html_
   		

Form

Button

EditBox

RadioBox

CheckBox

MenuBox

ListBox

EditText

CGI and Form