--- loncom/interface/loncommon.pm	2002/04/26 18:57:27	1.36
+++ loncom/interface/loncommon.pm	2002/06/24 20:17:55	1.39
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # a pile of common routines
 #
-# $Id: loncommon.pm,v 1.36 2002/04/26 18:57:27 matthew Exp $
+# $Id: loncommon.pm,v 1.39 2002/06/24 20:17:55 matthew Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -65,7 +65,7 @@ Current things done:
 This is part of the LearningOnline Network with CAPA project
 described at http://www.lon-capa.org.
 
-=head2 Subroutines
+=head2 General Subroutines
 
 =over 4
 
@@ -79,14 +79,13 @@ use Apache::lonnet();
 use POSIX qw(strftime);
 use Apache::Constants qw(:common);
 use Apache::lonmsg();
-
 my $readit;
 
 # ----------------------------------------------- Filetypes/Languages/Copyright
 my %language;
 my %cprtag;
 my %fe; my %fd;
-my %fc;
+my %category_extensions;
 
 # -------------------------------------------------------------- Thesaurus data
 my @therelated;
@@ -99,6 +98,9 @@ my $thethreshold=0.1/$thefuzzy;
 my $theavecount;
 
 # ----------------------------------------------------------------------- BEGIN
+
+=pod
+
 =item BEGIN() 
 
 Initialize values from language.tab, copyright.tab, filetypes.tab,
@@ -144,8 +146,8 @@ BEGIN {
 	    while (<$fh>) {
 		next if /^\#/;
 		chomp;
-		my ($key,$val)=(split(/\s+/,$_,2));
-		push @{$fc{$key}},$val;
+		my ($extension,$category)=(split(/\s+/,$_,2));
+		push @{$category_extensions{lc($category)}},$extension;
 	    }
 	}
     }
@@ -213,14 +215,16 @@ linked_select_forms takes the following
 
 =item $hashref, a reference to a hash containing the data for the menus.
 
+=back 
+
 Below is an example of such a hash.  Only the 'text', 'default', and 
 'select2' keys must appear as stated.  keys(%menu) are the possible 
 values for the first select menu.  The text that coincides with the 
-first menu values is given in $menu{$choice1}->{'text'}.  The values 
+first menu value is given in $menu{$choice1}->{'text'}.  The values 
 and text for the second menu are given in the hash pointed to by 
 $menu{$choice1}->{'select2'}.  
 
- my %menu = ( A1 => { text =>"Choice A1" ,
+my %menu = ( A1 => { text =>"Choice A1" ,
                       default => "B3",
                       select2 => { 
                           B1 => "Choice B1",
@@ -336,6 +340,24 @@ END
 }   #  end of sub linked_select_forms {
 
 ###############################################################
+
+=item csv_translate($text) 
+
+Translate $text to allow it to be output as a 'comma seperated values' 
+format.
+
+=cut
+
+sub csv_translate {
+    my $text = shift;
+    $text =~ s/\"/\"\"/g;
+    $text =~ s/\n//g;
+    return $text;
+}
+
+###############################################################
+
+###############################################################
 ##        Home server <option> list generating code          ##
 ###############################################################
 #-------------------------------------------
@@ -721,12 +743,12 @@ sub copyrightdescription {
 
 # ------------------------------------------------------------- File Categories
 sub filecategories {
-    return sort(keys(%fc));
+    return sort(keys(%category_extensions));
 }
 
 # -------------------------------------- File Types within a specified category
 sub filecategorytypes {
-    return @{$fc{lc(shift(@_))}};
+    return @{$category_extensions{lc($_[0])}};
 }
 
 # ------------------------------------------------------------------ File Types
@@ -767,12 +789,16 @@ sub get_previous_attempt {
       $prevattempts='<table border=2></tr><th>History</th>';
       foreach (sort(keys %lasthash)) {
 	my ($ign,@parts) = split(/\./,$_);
-	if (@parts) {
+	if ($#parts > 0) {
 	  my $data=$parts[-1];
 	  pop(@parts);
 	  $prevattempts.='<th>Part '.join('.',@parts).'<br />'.$data.'</th>';
 	} else {
-	  $prevattempts.='<th>'.$ign.'</th>';
+	  if ($#parts == 0) {
+	    $prevattempts.='<th>'.$parts[0].'</th>';
+	  } else {
+	    $prevattempts.='<th>'.$ign.'</th>';
+	  }
 	}
       }
       for ($version=1;$version<=$returnhash{'version'};$version++) {
@@ -847,16 +873,13 @@ sub get_student_answers {
   foreach my $element (@elements) {
     $ENV{'form.grade_'.$element}=$old{$element};
   }
-  $userview=~s/\<body[^\>]*\>//gi;
-  $userview=~s/\<\/body\>//gi;
-  $userview=~s/\<html\>//gi;
-  $userview=~s/\<\/html\>//gi;
-  $userview=~s/\<head\>//gi;
-  $userview=~s/\<\/head\>//gi;
-  $userview=~s/action\s*\=/would_be_action\=/gi;
   return $userview;
 }
 
+###############################################
+
+###############################################
+
 sub get_unprocessed_cgi {
   my ($query,$possible_names)= @_;
   # $Apache::lonxml::debug=1;
@@ -907,11 +930,19 @@ sub add_to_env {
   }
 }
 
-#---CSV Upload/Handling functions
+=pod
+
+=head2 CSV Upload/Handling functions
+
+=over 4
 
-# ========================================================= Store uploaded file
-# needs $ENV{'form.upfile'}
-# return $datatoken to be put into hidden field
+=item  upfile_store($r)
+
+Store uploaded file, $r should be the HTTP Request object,
+needs $ENV{'form.upfile'}
+returns $datatoken to be put into hidden field
+
+=cut
 
 sub upfile_store {
     my $r=shift;
@@ -930,9 +961,13 @@ sub upfile_store {
     return $datatoken;
 }
 
-# ================================================= Load uploaded file from tmp
-# needs $ENV{'form.datatoken'}
-# sets $ENV{'form.upfile'} to the contents of the file
+=item load_tmp_file($r)
+
+Load uploaded file from tmp, $r should be the HTTP Request object,
+needs $ENV{'form.datatoken'},
+sets $ENV{'form.upfile'} to the contents of the file
+
+=cut
 
 sub load_tmp_file {
     my $r=shift;
@@ -947,10 +982,13 @@ sub load_tmp_file {
     $ENV{'form.upfile'}=join('',@studentdata);
 }
 
-# ========================================= Separate uploaded file into records
-# returns array of records
-# needs $ENV{'form.upfile'}
-# needs $ENV{'form.upfiletype'}
+=item upfile_record_sep()
+
+Separate uploaded file into records
+returns array of records,
+needs $ENV{'form.upfile'} and $ENV{'form.upfiletype'}
+
+=cut
 
 sub upfile_record_sep {
     if ($ENV{'form.upfiletype'} eq 'xml') {
@@ -959,9 +997,12 @@ sub upfile_record_sep {
     }
 }
 
-# =============================================== Separate a record into fields
-# needs $ENV{'form.upfiletype'}
-# takes $record as arg
+=item record_sep($record)
+
+Separate a record into fields $record should be an item from the upfile_record_sep(), needs $ENV{'form.upfiletype'}
+
+=cut
+
 sub record_sep {
     my $record=shift;
     my %components=();
@@ -1006,7 +1047,12 @@ sub record_sep {
     return %components;
 }
 
-# =============================== HTML code to select file and specify its type
+=item upfile_select_html()
+
+return HTML code to select file and specify its type
+
+=cut
+
 sub upfile_select_html {
     return (<<'ENDUPFORM');
 <input type="file" name="upfile" size="50">
@@ -1019,9 +1065,14 @@ sub upfile_select_html {
 ENDUPFORM
 }
 
-# ===================Prints a table of sample values from each column uploaded
-# $r is an Apache Request ref
-# $records is an arrayref from &Apache::loncommon::upfile_record_sep
+=item csv_print_samples($r,$records)
+
+Prints a table of sample values from each column uploaded $r is an
+Apache Request ref, $records is an arrayref from
+&Apache::loncommon::upfile_record_sep
+
+=cut
+
 sub csv_print_samples {
     my ($r,$records) = @_;
     my (%sone,%stwo,%sthree);
@@ -1044,10 +1095,15 @@ sub csv_print_samples {
     $r->print('</tr></table><br />'."\n");
 }
 
-# ======Prints a table to create associations between values and table columns
-# $r is an Apache Request ref
-# $records is an arrayref from &Apache::loncommon::upfile_record_sep
-# $d is an array of 2 element arrays (internal name, displayed name)
+=item csv_print_select_table($r,$records,$d)
+
+Prints a table to create associations between values and table columns.
+$r is an Apache Request ref,
+$records is an arrayref from &Apache::loncommon::upfile_record_sep,
+$d is an array of 2 element arrays (internal name, displayed name)
+
+=cut
+
 sub csv_print_select_table {
     my ($r,$records,$d) = @_;
     my $i=0;my %sone;
@@ -1071,11 +1127,16 @@ sub csv_print_select_table {
     return $i;
 }
 
-# ===================Prints a table of sample values from the upload and
-#                      can make associate samples to internal names
-# $r is an Apache Request ref
-# $records is an arrayref from &Apache::loncommon::upfile_record_sep
-# $d is an array of 2 element arrays (internal name, displayed name)
+=item csv_samples_select_table($r,$records,$d)
+
+Prints a table of sample values from the upload and can make associate samples to internal names.
+
+$r is an Apache Request ref,
+$records is an arrayref from &Apache::loncommon::upfile_record_sep,
+$d is an array of 2 element arrays (internal name, displayed name)
+
+=cut
+
 sub csv_samples_select_table {
     my ($r,$records,$d) = @_;
     my %sone; my %stwo; my %sthree;
@@ -1106,6 +1167,14 @@ sub csv_samples_select_table {
 1;
 __END__;
 
+=pod
+
+=back
+
+=head2 Access .tab File Data
+
+=over 4
+
 =item languageids() 
 
 returns list of all language ids
@@ -1144,6 +1213,12 @@ returns description for a specified file
 returns description for a specified file type with
 extra formatting
 
+=back
+
+=head2 Alternate Problem Views
+
+=over 4
+
 =item get_previous_attempt() 
 
 return string with previous attempt on problem
@@ -1156,9 +1231,22 @@ show a snapshot of what student was look
 
 show a snapshot of how student was answering problem
 
-=item get_unprocessed_cgi() 
+=back
+
+=head2 HTTP Helper
+
+=over 4
+
+=item get_unprocessed_cgi($query,$possible_names)
 
-get unparsed CGI parameters
+Modify the %ENV hash to contain unprocessed CGI form parameters held in
+$query.  The parameters listed in $possible_names (an array reference),
+will be set in $ENV{'form.name'} if they do not already exist.
+
+Typically called with $ENV{'QUERY_STRING'} as the first parameter.  
+$possible_names is an ref to an array of form element names.  As an example:
+get_unprocessed_cgi($ENV{'QUERY_STRING'},['uname','udom']);
+will result in $ENV{'form.uname'} and $ENV{'form.udom'} being set.
 
 =item cacheheader()