Perl

• Accessing Form Parameters
• CGI.pm

Accessing Form Parameters

• In order to access form parameters, we need to decode the data sent to the CGI script

• Decoding algorithm:
  1. Read the query string from $ENV{QUERY_STRING}
  2. If $ENV{REQUEST_METHOD} is POST, determine length of request body and read from STDIN
  3. Append data to data read from query string, if present
  4. Split the result on the "&" character
  5. Split each resulting name-value pair on the "=" character
  6. Decode the URL-encoded characters in name and value
  7. Associate each name with its value(s)

Reading the Query

• If $ENV{REQUEST_METHOD} is GET, assign $ENV{QUERY_STRING} to the query

  my $query;
  
  if ($ENV{'REQUEST_METHOD'} eq 'GET') {
  	$query = $ENV{'QUERY_STRING'};
  }

Reading the Query

• If $ENV{REQUEST_METHOD} is POST, determine length of request body and read data from STDIN
• If $ENV{QUERY_STRING} exists, append the data to it

  elsif ($ENV{'REQUEST_METHOD'} eq 'POST') {
  	read(STDIN, $query, $ENV{'CONTENT_LENGTH'});
  	$query = $ENV{'QUERY_STRING'} . "&" . $query 
  		if ($ENV{'QUERY_STRING'});
  }

Parse the Query

• Parse the query into its constituent name-value pairs, and extract a hash of parameters, $formInput

  foreach $_ (split(/&/, $query)) {
  	tr/+/ /;
  	s/\%(..)/pack(C, hex($1))/ge;
  	($_, $param) = split (/=/, $_);
  	if ($param{$_}) {
  		$param{$_} .= ",$param";
  	} else {
  		$param{$_} = $param;
  	}
  }

• Analysis:
  • Split the query on the "&" character
  • Replace each "+" character by spaces
  • Translate from hex-encodings back to characters
  • Split each name-value pair on the "="
  • If a parameter already exists by that name, append the value, separated by a comma
  • Otherwise add a new parameter to the hash

Putting it All Together

• Define a library, ParseInput.lib, with this code

  my $query;
  
  # Read data from GET
  if ($ENV{'REQUEST_METHOD'} eq 'GET') {
  	$query = $ENV{'QUERY_STRING'};
  } 
  
  # Read data from POST
  elsif ($ENV{'REQUEST_METHOD'} eq 'POST') {
  	read(STDIN, $query, $ENV{'CONTENT_LENGTH'});
  	$query = $ENV{'QUERY_STRING'} . "&" . $query 
  		if ($ENV{'QUERY_STRING'});
  }
  
  # Parse the query
  foreach $_ (split(/&/, $query)) {
  	tr/+/ /;
  	s/\%(..)/pack(C, hex($1))/ge;
  	($_, $param) = split (/=/, $_);
  	if ($param{$_}) {
  		$param{$_} .= ",$param";
  	} else {
  		$param{$_} = $param;
  	}
  }
  
  1;

ParseInput.lib (Example)

• Here is an example using our new library

  require "ParseInput.lib";
  
  # Print mime header
  print "Content-type: text/html\n\n";
  
  # Check input parameters
  unless ($param{'user'} && $param{'email'}) {
  	print "Must fill out user and email"; 
  	exit;
  }
  
  # Process form
  print <<END_OF_UPDATE;
  <h1>Success</h1>
  Thanks for your input. The following update has been made:
  <p>
  <table border>
  <tr>
    <td>User:
    <td>$param{'user'}
  <tr>
    <td>Email:
    <td>$param{'email'}
  </table>
  END_OF_UPDATE

• The following form invokes this script

  <h1>Update</h1>
  <form action="update.cgi" method="GET">
  Please fill in your profile:
  <table>
  <tr>
    <td>User:
    <td><input type="text" name="user">
  <tr>
    <td>Email:
    <td><input type="email" name="email">
  <tr>
    <td>
    <td><input type="submit" value="Update">
  </table>
  </form>

• Run the example

• See the output

ParseInput.lib

• Although CGI.pm include most of the functionality developed here, CGI.pm cannot deal with forms
  • using the POST method
  • directing it to an URL with a query string
• For example, you might want to specify action parameters that must otherwise be passed in hidden fields

CGI.pm

• Handling input with CGI.pm
  • Get information about the environment
  • Get form input
  • Handle file uploads
• Generate output with CGI.pm
  • Generate headers
  • Generate HTML
• Handling errors
  • Trap class to die

Standard and Object-Oriented Syntax

• Two styles of usage:
  • Standard interface
  • Object-oriented interface
• CGI.pm is an object-oriented module
  • But can export functions into main name space
• Example of object-oriented syntax

  use CGI;
  
  my $q = new CGI;
  my $name = $q->param("name");
  print $q->header("text/html"),
  	$q->start_html("Welcome"),
  	$q->p("Welcome back, $name!"),
  	$q->end_html;

• Standard syntax looks like this

  use CGI qw( :standard );
  
  my $name = param("name");
  print header("text/html"),
  	start_html("Welcome"),
  	p("Welcome back, $name!"),
  	end_html;

Getting Information About the Environment

• Makes envrionment variables availabe via method calls
• Method names derived from name of the environment variable

  content_type    CONTENT_TYPE
  path_info       PATH_INFO
  query_string    QUERY_STRING
  request_method  REQUEST_METHOD
  script_name     SCRIPT_NAME
  Accept          HTTP_ACCEPT

• For example, to get the additional path information, use

  my $path = $q->path_info;

Accessing Form Parameters

• One of the most common reasons for using CGI.pm
  • The param method allows you to access the parameters submitted to your script
• Without arguments param returns all parameter names

  foreach $name ($q->param) {
  	print "$name";
  }

• With the name of a parameter, it will return its value

  $email = $q->param("email");
  print "Email: $email";

• For parameters with multiple values, param returns
  • just the first value (if called in a scalar context)
  • a list of all values (if called in a list context)

  $color  = $q->param("color");   # just the first one
  @colors = $q->param("color");   # list of all colors

Modifying Parameters

• CGI.pm also lets you add, modify, or delete the value of parameters
  • Setting default values
  • Converting values to a common format

  $q->param(sku => "102030");
  $q->param(interests => "music", "dining", "sport");
  $q->delete("age");
  $q->delete_all;

Modifying Parameters (Example)

• One good application is to support image and regular submit buttons interchangeable
  • With image buttons, the browser sends two separate variables, name.x and name.y
  • For regular submit buttons, their name is sent
• May replace submit buttons by image buttons later
• The code below sets a form parameter for each parameter whose name ends in .x

  foreach ($q->param) {
   	$q->param($1 => 1) if /(.*)\.x/;
  }

Generating Output with CGI.pm

• Methods for embedding HTML in your code
• Headers and HTML elements can be generated by a corresponding method

  use CGI;
  
  my $q = new CGI;
  my $timestamp = localtime();
  
  print $q->header("text/html"),
  	$q->start_html(-title => "Current Time", -bgcolor => "blue"),
  	$q->h1("Current Time"),
  	$q->hr,
  	$q->p("The current time is:", $q->b($timestamp)),
  	$q->end_html;

• See the output

Generating Header Fields

• To set header fields, pass a name-value pair for each field to the header method
  • With one argument, sets the content type
• The following header fields can be set
  • Content type (-type)
  • Status (-status)
  • Caching (-expires)
  • Target (-target)
  • Redirection (-redirect)
  • Others (use name-value pair)

  print $q->header(-type => "text/html", 
    -status("404 Not Found"));
  print $q->header(-type => "text/html", 
    -expires => "+30m");
  print $q->header(-type => "text/html", 
    -target => "main");
  print $q->redirect("/thanks.html");

Starting and Ending Documents

• Methods for starting and ending documents
• start_html
  Returns <html> tag, <head> section, and <body> tags

  <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
  <HTML>
    <HEAD><TITLE>Current Time</TITLE></HEAD>
    <BODY BGCOLOR="blue">

• end_html
  Returns the </body> and </html> tags

Standard HTML Elements

• HTML elements can be generated by methods with corresponding names

  print $q->hr;

• If you provide one argument, opening and closing tags are created

  print $q->p("One paragraph");

• If you provide multiple arguments, they are joined

  print $q->p("Thanks for the update,", $user);

• This provides a simple way for nesting elements

  print $q->p("Thanks for the update,", $q->em($user));

• If the first argument is a reference to a hash, its elements are interpreted as attributes of the HTML element

  print $q->a({ -href => "http://www.yahoo.com" }, 
  	"Yahoo!");

• If you provide a reference to an array as an argument, the tag is distributed across each element in the array

  print $q->ol($q-li(["One", "Two", "Three"]));

Standard HTML Elements (Example)

• The following creates a table

  print $q->table(
  	{ -border => 1,
  	  -width  => 200 },
  	$q->Tr( [
  		$q->th(["Name", "Age"]),
  		$q->td(["Bob", 29]),
  		$q->td(["Alice", 22]),
  		$q->td(["Mary", 24])
  	])
  );

• See the output

Form Elements

• For each type of input element, CGI.pm provides corresponding methods

• Starting and ending forms

  print $q->start_form(
  	-method => "get", 
  	-action => "/cgi-bin/script.cgi");
  print $q->end_form;

• Text fields

  print $q->textfield(
  	-name => "user",
  	-default => "Enter your name");
  print $q->password_field(
  	-name => "secret");

• Hidden fields

  print $q->hidden(
  	-name => "action",
  	-value => "checkout");

• Submit buttons

  print $q->submit(
  	-value => "Edit");
  print $q->reset(
  	-value => "Undo");
  print $q->button(
  	-value => "Recalculate",
  	-onClick => "updateShoppingCart();");

• Checkboxes

  print $q->checkbox(
  	-name => "help",
  	-value => "yes",
  	-label => "Display context-sensitive help",
  	-checked => 1),

• Image buttons

  print $q->image_button(
  	-name => "order",
  	-src => "/shop/images/order.jpg"),

• Text areas

  print $q->textarea(
  	-rows => 10,
  	-cols => 60,
  	-default => "Enter a comment");

Form Elements (Example)

• Note: Instead of CGI, you can also use CGI::Pretty
  • It supports all features of CGI.pm, but produces neatly indented HTML

  use CGI::Pretty;
  
  my $q = new CGI::Pretty;
  
  print $q->header("text/html"),
  	$q->start_html("Register"),
  	$q->h1("Register"),
  	$q->hr;
  	
  print $q->start_form(
  		-method => "post", 
  		-action => "update.cgi"),
  	$q->textfield(
  		-name => "user",
  		-value => "Enter your name"),
  	$q->p(
  		$q->textfield(
  			-name => "email",
  			-value => "Enter your email")),
  	$q->p(
  		$q->checkbox(
  			-name => "junk",
  			-value => "yes",
  			-label => "Sign me up for junk mail",
  			-checked => 1)),
  	$q->p(
  		$q->submit(
  			-value => "Register"),
  		$q->reset(
  			-value => "Clear")),
  	$q->end_form;
  	
  print $q->end_html;

• See the output

Grouped Form Elements

• Support for input elements sharing the same name
  • -values
    Generate multiple elements (checkboxes, menu options, etc.) with the same name supplied in an array reference

  • -default
    Indicate the values that are checked

  • -labels
    Associate the value of each element to a label the browser displays supplied in a hash reference

  • -size
    Other attributes such as SIZE can be passed as additional arguments

• Methods:
  • checkbox_group
  • radio_group
  • popup_menu
  • scrolling_list

  print $q->radio_group(
  	-name => "movie",
  	-values => [ "a", "b", "c" ],
  	-default => "a",
  	-labels => { 
  		"a" => "Movie A",
  		"b" => "Movie B",
  		"c" => "Movie C" } );

• See the output

Handling Errors

• The CGI::Carp module allows you to "trap" errors and have them displayed to the browser instead
• Display full error messages

  use CGI::Carp qw( fatalsToBrowser );
  
  $result = 1/0;   # buggy script

• See the output

• Pass error messages to your own subroutine, which displays a user-friendly message

  use CGI::Carp qw( fatalsToBrowser );
  
  BEGIN {
  	sub handleError {
  		my $error = shift;
  		my $q = new CGI;
  		print $q->start_html("Error"),
  			$q->h1("Error"),
  			$q->p("An error has occurred:"),
  			$q->p($q->em($error)).
  			$q->end_html;
  	}
  	CGI::Carp::set_message( \&handleError );
  }

• This can be extremely useful during debugging

Handling Errors

• One challenge is to know whether or not to print an HTTP header
  • If a header has already been printed, the header will appear at the top of the error page
  • If one has not been printed, and you don't print one, you will trigger