--- loncom/interface/loncommon.pm	2002/04/26 18:57:27	1.36
+++ loncom/interface/loncommon.pm	2002/07/01 15:24:44	1.42
@@ -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.42 2002/07/01 15:24:44 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;
 	    }
 	}
     }
@@ -188,6 +190,92 @@ BEGIN {
     
 }
 # ============================================================= END BEGIN BLOCK
+###############################################################
+##           HTML and Javascript Helper Functions            ##
+###############################################################
+
+=pod 
+
+=item browser_and_searcher_javascript 
+
+Returns scalar containing javascript to open a browser window
+or a searcher window.  Also creates 
+
+=over 4
+
+=item openbrowser(formname,elementname,only,omit) [javascript]
+
+inputs: formname, elementname, only, omit
+
+formname and elementname indicate the name of the html form and name of
+the element that the results of the browsing selection are to be placed in. 
+
+Specifying 'only' will restrict the browser to displaying only files
+with the given extension.  Can be a comma seperated list.
+
+Specifying 'omit' will restrict the browser to NOT displaying files
+with the given extension.  Can be a comma seperated list.
+
+=item opensearcher(formname, elementname) [javascript]
+
+Inputs: formname, elementname
+
+formname and elementname specify the name of the html form and the name
+of the element the selection from the search results will be placed in.
+
+=back
+
+=cut
+
+###############################################################
+sub browser_and_searcher_javascript {
+    return <<END;
+    var editbrowser;
+    function openbrowser(formname,elementname,only,omit) {
+        var url = '/res/?';
+        if (editbrowser == null) {
+            url += 'launch=1&';
+        }
+        url += 'catalogmode=interactive&';
+        url += 'mode=edit&';
+        url += 'form=' + formname + '&';
+        if (only != null) {
+            url += 'only=' + only + '&';
+        } 
+        if (omit != null) {
+            url += 'omit=' + omit + '&';
+        }
+        url += 'element=' + elementname + '';
+        var title = 'Browser';
+        var options = 'scrollbars=1,resizable=1,menubar=0';
+        options += ',width=700,height=600';
+        editbrowser = open(url,title,options,'1');
+        editbrowser.focus();
+    }
+    var editsearcher;
+    function opensearcher(formname,elementname) {
+        var url = '/adm/searchcat?';
+        if (editsearcher == null) {
+            url += 'launch=1&';
+        }
+        url += 'catalogmode=interactive&';
+        url += 'mode=edit&';
+        url += 'form=' + formname + '&';
+        url += 'element=' + elementname + '';
+        var title = 'Search';
+        var options = 'scrollbars=1,resizable=1,menubar=0';
+        options += ',width=700,height=600';
+        editsearcher = open(url,title,options,'1');
+        editsearcher.focus();
+    }
+END
+}
+
+
+
+###############################################################
+
+=pod
 
 =item linked_select_forms(...)
 
@@ -213,14 +301,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 +426,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 +829,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
@@ -750,8 +858,18 @@ sub filedescriptionex {
     return '.'.$ex.' '.$fd{lc($ex)};
 }
 
+# ---- Retrieve attempts by students
+# input
+# $symb             - problem including path
+# $username,$domain - that of the student
+# $course           - course name
+# $getattempt       - leave blank if want all attempts, else put something.
+# 
+# output
+# formatted as a table all the attempts, if any.
+#
 sub get_previous_attempt {
-  my ($symb,$username,$domain,$course)=@_;
+  my ($symb,$username,$domain,$course,$getattempt)=@_;
   my $prevattempts='';
   if ($symb) {
     my (%returnhash)=
@@ -764,30 +882,37 @@ sub get_previous_attempt {
 	  $lasthash{$_}=$returnhash{$version.':'.$_};
         }
       }
-      $prevattempts='<table border=2></tr><th>History</th>';
+      $prevattempts='<table border="0" width="100%"><tr><td bgcolor="#000000">';
+      $prevattempts.='<table border="0" width="100%"><tr bgcolor="#e6ffff"><td>History</td>';
       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>';
+	  $prevattempts.='<td>Part '.join('.',@parts).'<br />'.$data.'&nbsp;</td>';
 	} else {
-	  $prevattempts.='<th>'.$ign.'</th>';
-	}
-      }
-      for ($version=1;$version<=$returnhash{'version'};$version++) {
-        $prevattempts.='</tr><tr><th>Attempt '.$version.'</th>';
-        foreach (sort(keys %lasthash)) {
-	  my $value;
-	  if ($_ =~ /timestamp/) {
-	    $value=scalar(localtime($returnhash{$version.':'.$_}));
+	  if ($#parts == 0) {
+	    $prevattempts.='<th>'.$parts[0].'</th>';
 	  } else {
-	    $value=$returnhash{$version.':'.$_};
+	    $prevattempts.='<th>'.$ign.'</th>';
 	  }
-	  $prevattempts.='<td>'.$value.'</td>';   
-        }
+	}
       }
-      $prevattempts.='</tr><tr><th>Current</th>';
+      if ($getattempt eq '') {
+	for ($version=1;$version<=$returnhash{'version'};$version++) {
+	  $prevattempts.='</tr><tr bgcolor="#ffffe6"><td>Transaction '.$version.'</td>';
+	    foreach (sort(keys %lasthash)) {
+	       my $value;
+	       if ($_ =~ /timestamp/) {
+		  $value=scalar(localtime($returnhash{$version.':'.$_}));
+	       } else {
+		  $value=$returnhash{$version.':'.$_};
+	       }
+	       $prevattempts.='<td>'.$value.'&nbsp;</td>';   
+	    }
+	 }
+      }
+      $prevattempts.='</tr><tr bgcolor="#ffffe6"><td>Current</td>';
       foreach (sort(keys %lasthash)) {
 	my $value;
 	if ($_ =~ /timestamp/) {
@@ -795,9 +920,9 @@ sub get_previous_attempt {
 	} else {
 	  $value=$lasthash{$_};
 	}
-	$prevattempts.='<td>'.$value.'</td>';
+	$prevattempts.='<td>'.$value.'&nbsp;</td>';
       }
-      $prevattempts.='</tr></table>';
+      $prevattempts.='</tr></table></td></tr></table>';
     } else {
       $prevattempts='Nothing submitted - no attempts.';
     }
@@ -847,16 +972,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 +1029,19 @@ sub add_to_env {
   }
 }
 
-#---CSV Upload/Handling functions
+=pod
 
-# ========================================================= Store uploaded file
-# needs $ENV{'form.upfile'}
-# return $datatoken to be put into hidden field
+=head2 CSV Upload/Handling functions
+
+=over 4
+
+=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 +1060,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 +1081,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 +1096,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 +1146,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 +1164,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 +1194,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 +1226,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 +1266,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 +1312,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 +1330,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()