--- loncom/interface/Attic/lonchart.pm	2002/07/02 15:13:06	1.50
+++ loncom/interface/Attic/lonchart.pm	2002/07/08 15:03:25	1.57
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # (Publication Handler
 #
-# $Id: lonchart.pm,v 1.50 2002/07/02 15:13:06 stredwic Exp $
+# $Id: lonchart.pm,v 1.57 2002/07/08 15:03:25 stredwic Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -46,6 +46,59 @@
 #
 ###
 
+=pod
+
+=head1 NAME
+
+lonchart
+
+=head1 SYNOPSIS
+
+Quick display of students grades for a course in a compressed table format.
+
+=head1 DESCRIPTION
+
+This module process all student grades for a course and turns them into a 
+table like structure.
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org
+
+lonchart presents the user with a condensed view all a course's data.  The
+class title, the number of students, and the date for the last update of the
+displayed data.  There is also a legend that describes the chart values.  
+
+For each valid grade for a student is linked with a submission record for that
+problem.  The ability to add and remove columns of data from the chart was
+added for reducing the burden of having to scroll through large quantities
+of data.  The interface also allows for sorting of students by username,
+last name, and section number of class.  Active and expired students are
+also available.
+
+The interface is controlled by three primary buttons: Recalculate Chart, 
+Refresh Chart, and Reset Selections.  Recalculate Chart will update 
+the chart to the most recent data and keep the display settings for the chart
+the same.  Refresh Chart is used to redisplay the chart after selecting
+different output formatting.  Reset Selections is used to set the chart
+display options back to default values.
+
+=head1 CODE LAYOUT DESCRIPTION
+
+The code is broken down into five components: formatting data for printing,
+downloading data from servers, processing data, helper functions,
+and the central processing functions.  The module is broken into chunks
+for each component.
+
+=head1 PACKAGES USED
+
+ Apache::Constants qw(:common :http)
+ Apache::lonnet()
+ Apache::loncommon()
+ HTML::TokeParser
+ GDBM_File
+
+=cut
+
 package Apache::lonchart;
 
 use strict;
@@ -55,15 +108,51 @@ use Apache::loncommon();
 use HTML::TokeParser;
 use GDBM_File;
 
-my $jr; 
+#my $jr; 
+
+=pod
+
+=head1 FORMAT DATA FOR PRINTING
+
+=cut
+
 # ----- FORMAT PRINT DATA ----------------------------------------------
 
+=pod
+
+=item &FormatStudentInformation()
+
+This function produces a formatted string of the student's information:
+username, domain, section, full name, and PID.
+
+=over 4
+
+Input: $cache, $name, $studentInformation, $spacePadding
+
+$cache: This is a pointer to a hash that is tied to the cached data
+
+$name:  The name and domain of the current student in name:domain format
+
+$studentInformation: A pointer to an array holding the names used to
+
+remove data from the hash.  They represent the name of the data to be removed.
+
+$spacePadding: Extra spaces that represent the space between columns
+
+Output: $Str
+
+$Str: Formatted string.
+
+=back
+
+=cut
+
 sub FormatStudentInformation {
-    my ($cache,$name,$studentInformation,$reselected,$spacePadding)=@_;
+    my ($cache,$name,$studentInformation,$spacePadding)=@_;
     my $Str='';
 
     for(my $index=0; $index<(scalar @$studentInformation); $index++) {
-        if(!&ShouldShowColumn($reselected, 'heading', $index)) {
+        if(!&ShouldShowColumn($cache, 'heading'.$index)) {
             next;
         }
 	my $data=$cache->{$name.':'.$studentInformation->[$index]};
@@ -79,8 +168,42 @@ sub FormatStudentInformation {
     return $Str;
 }
 
+=pod
+
+=item &FormatStudentData()
+
+First, FormatStudentInformation is called and prefixes the course information.
+This function produces a formatted string of the student's course information.
+Each column of data represents all the problems for a given sequence.  For
+valid grade data, a link is created for that problem to a submission record
+for that problem.
+
+=over 4
+
+Input: $name, $studentInformation, $spacePadding, $ChartDB
+
+$name: The name and domain of the current student in name:domain format
+
+$studentInformation: A pointer to an array holding the names used to 
+remove data from the hash.  They represent 
+the name of the data to be removed.
+
+$spacePadding: Extra spaces that represent the space between columns
+
+$ChartDB: The name of the cached data database which will be tied to that 
+database.
+
+Output: $Str
+
+$Str: Formatted string that is an entire row of the chart.  It is a 
+concatenation of student information and student course information.
+
+=back
+
+=cut
+
 sub FormatStudentData {
-    my ($reselected,$name,$coid,$studentInformation,$spacePadding,$ChartDB)=@_;
+    my ($name,$studentInformation,$spacePadding,$ChartDB)=@_;
     my ($sname,$sdom) = split(/\:/,$name);
     my $Str;
     my %CacheData;
@@ -91,7 +214,7 @@ sub FormatStudentData {
     # Handle Student information ------------------------------------------
     # Handle user data
     $Str=&FormatStudentInformation(\%CacheData, $name, $studentInformation, 
-                                   $reselected, $spacePadding);
+                                   $spacePadding);
 
     # Handle errors
     if($CacheData{$name.':error'} =~ /environment/) {
@@ -113,7 +236,7 @@ sub FormatStudentData {
     my $problemsSolved  = 0;
     my $numberOfParts   = 0;
     foreach my $sequence (split(/\:/,$CacheData{'orderedSequences'})) {
-        if(!&ShouldShowColumn($reselected, 'sequence', $sequence)) {
+        if(!&ShouldShowColumn(\%CacheData, 'sequence'.$sequence)) {
             next;
         }
 
@@ -208,22 +331,52 @@ sub FormatStudentData {
         $Str .= $spacePadding;
     }
 
-    $Str .= '<font color="#000088">'.$problemsSolved.
-	    ' / '.$totalProblems.'</font><br>';
+    my $outputProblemsSolved = sprintf( "%4d", $problemsSolved );
+    my $outputTotalProblems  = sprintf( "%4d", $totalProblems );
+    $Str .= '<font color="#000088">'.$outputProblemsSolved.
+	    ' / '.$outputTotalProblems.'</font><br>';
 
     untie(%CacheData);
     return $Str;
 }
 
+=pod
+
+=item &CreateTableHeadings()
+
+This function generates the column headings for the chart.
+
+=over 4
+
+Inputs: $CacheData, $studentInformation, $headings, $spacePadding
+
+$CacheData: pointer to a hash tied to the cached data database
+
+$studentInformation: a pointer to an array containing the names of the data 
+held in a column and is used as part of a key into $CacheData
+
+$headings: The names of the headings for the student information
+
+$spacePadding: The spaces to go between columns
+
+Output: $Str
+
+$Str: A formatted string of the table column headings.
+
+=back
+
+=cut
+
 sub CreateTableHeadings {
-    my ($CacheData,$studentInformation,$headings,$reselected,$spacePadding)=@_;
-    my $Str='<pre>';
+    my ($CacheData,$studentInformation,$headings,$spacePadding)=@_;
+    my $Str='<tr>';
 
     for(my $index=0; $index<(scalar @$headings); $index++) {
-        if(!&ShouldShowColumn($reselected, 'heading', $index)) {
+        if(!&ShouldShowColumn($CacheData, 'heading'.$index)) {
             next;
         }
 
+        $Str .= '<td align="left"><pre>';
 	my $data=$$headings[$index];
 	$Str .= $data;
 
@@ -232,13 +385,15 @@ sub CreateTableHeadings {
 	$Str .= (' 'x($CacheData->{$$studentInformation[$index].'Length'}-
                       $length));
 	$Str .= $spacePadding;
+        $Str .= '</pre></td>';
     }
 
     foreach my $sequence (split(/\:/,$CacheData->{'orderedSequences'})) {
-        if(!&ShouldShowColumn($reselected, 'sequence', $sequence)) {
+        if(!&ShouldShowColumn($CacheData, 'sequence'.$sequence)) {
             next;
         }
 
+        $Str .= '<td align="left"><pre>';
         my $name = $CacheData->{$sequence.':title'};
 	$Str .= $name;
 	my @titleLength=split(//,$CacheData->{$sequence.':title'});
@@ -246,16 +401,46 @@ sub CreateTableHeadings {
                      (scalar @titleLength);
 	$Str .= (' 'x$leftover);
 	$Str .= $spacePadding;
+        $Str .= '</pre></td>';
     }
 
-    $Str .= 'Total Solved/Total Problems';
-    $Str .= '</pre>';
+    $Str .= '<td><pre>Total Solved/Total Problems</pre></td>';
+    $Str .= '</tr>';
 
     return $Str;
 }
 
+=pod
+
+=item &CreateColumnSelectionBox()
+
+If there are columns not being displayed then this selection box is created
+with a list of those columns.  When selections are made and the page 
+refreshed, the columns will be removed from this box and the column is
+put back in the chart.  If there is no columns to select, no row is added
+to the interface table.
+
+=over 4
+Input: $CacheData, $headings
+
+
+$CacheData: A pointer to a hash tied to the cached data
+
+$headings:  An array of the names of the columns for the student information.  
+They are used for displaying which columns are missing.
+
+Output: $notThere
+
+$notThere: The string contains one row of a table.  The first column has the 
+name of the selection box.  The second contains the selection box 
+which has a size of four.
+
+=back
+
+=cut
+
 sub CreateColumnSelectionBox {
-    my ($CacheData,$studentInformation,$headings,$reselected,$spacePadding)=@_;
+    my ($CacheData,$headings)=@_;
 
     my $missing=0;
     my $notThere='<tr><td align="right"><b>Select column to view:</b>';
@@ -264,7 +449,7 @@ sub CreateColumnSelectionBox {
     $notThere .= '<select name="reselect" size="4" multiple="true">'."\n";
 
     for(my $index=0; $index<(scalar @$headings); $index++) {
-        if(&ShouldShowColumn($reselected, 'heading', $index)) {
+        if(&ShouldShowColumn($CacheData, 'heading'.$index)) {
             next;
         }
         $name = $headings->[$index];
@@ -274,7 +459,7 @@ sub CreateColumnSelectionBox {
     }
 
     foreach my $sequence (split(/\:/,$CacheData->{'orderedSequences'})) {
-        if(&ShouldShowColumn($reselected, 'sequence', $sequence)) {
+        if(&ShouldShowColumn($CacheData, 'sequence'.$sequence)) {
             next;
         }
         $name = $CacheData->{$sequence.':title'};
@@ -289,75 +474,116 @@ sub CreateColumnSelectionBox {
         $notThere='<tr><td>';
     }
 
-    return $notThere.'</td></tr></tbody></table>';
+    return $notThere.'</td></tr>';
 }
 
+=pod
+
+=item &CreateColumnSelectors()
+
+This function generates the checkboxes above the column headings.  The 
+column will be removed if the checkbox is unchecked.
+
+=over 4
+
+Input: $CacheData, $headings
+
+$CacheData: A pointer to a hash tied to the cached data
+
+$headings:  An array of the names of the columns for the student 
+information.  They are used to know what are the student information columns
+
+Output: $present
+
+$present: The string contains the first row of a table.  Each column contains
+a checkbox which is left justified.  Currently left justification is used
+for consistency of location over the column in which it presides.
+
+=back
+
+=cut
+
 sub CreateColumnSelectors {
-    my ($CacheData,$studentInformation,$headings,$reselected,$spacePadding)=@_;
+    my ($CacheData,$headings)=@_;
 
     my $found=0;
     my ($name, $length, $position);
-    my $present='<pre>';
+
+    my $present = '<tr>';
     for(my $index=0; $index<(scalar @$headings); $index++) {
-        if(!&ShouldShowColumn($reselected, 'heading', $index)) {
+        if(!&ShouldShowColumn($CacheData, 'heading'.$index)) {
             next;
         }
-        $name = $headings->[$index];
-        $length=$CacheData->{$$studentInformation[$index].'Length'};
-        $position=int($length/2);
-	$present .= (' 'x($position));
+        $present .= '<td align="left">';
         $present .= '<input type="checkbox" checked="on" ';
-        $present .= 'name="heading'.$index.'">';
-        $position+=2;
-	$present .= (' 'x($length-$position));
-	$present .= $spacePadding;
+        $present .= 'name="heading'.$index.'" />';
+        $present .= '</td>';
         $found++;
     }
 
     foreach my $sequence (split(/\:/,$CacheData->{'orderedSequences'})) {
-        if(!&ShouldShowColumn($reselected, 'sequence', $sequence)) {
+        if(!&ShouldShowColumn($CacheData, 'sequence'.$sequence)) {
             next;
         }
-        $name = $CacheData->{$sequence.':title'};
-        $length=$CacheData->{$sequence.':columnWidth'};
-        $position=int($length/2);
-	$present .= (' 'x($position));
+        $present .= '<td align="left">';
         $present .= '<input type="checkbox" checked="on" ';
-        $present .= 'name="sequence'.$sequence.'">';
-        $position+=2;
-	$present .= (' 'x($length-$position));
-	$present .= $spacePadding;
+        $present .= 'name="sequence'.$sequence.'" />';
+        $present .= '</td>';
         $found++;
     }
 
-    if($found) {
-        $present .= '</pre>';
-        $present  = $present;
-    } else {
+    if(!$found) {
         $present = '';
     }
 
-    return $present.'</form>'."\n";;
+    return $present.'<td></td></tr></form>'."\n";;
 }
 
+=pod
+
+=item &CreateForm()
+
+The interface for this module consists primarily of the controls in this
+function.  The student status selection (active, expired, any) is set here.
+The sort buttons: username, last name, and section are set here.  The
+other buttons are Recalculate Chart, Refresh Chart, and Reset Selections.
+These controls are in a table to clean up the interface.
+
+=over 4
+
+Input: $CacheData
+
+$CacheData is a hash pointer to tied database for cached data.
+
+Output: $Ptr
+
+$Ptr is a string containing all the html for the above mentioned buttons.
+
+=back
+
+=cut
+
 sub CreateForm {
+    my ($CacheData)=@_;
     my $OpSel1='';
     my $OpSel2='';
     my $OpSel3='';
-    my $Status = $ENV{'form.status'};
+    my $Status = $CacheData->{'form.status'};
     if ( $Status eq 'Any' ) { $OpSel3='selected'; }
     elsif ($Status eq 'Expired' ) { $OpSel2 = 'selected'; }
     else { $OpSel1 = 'selected'; }
 
     my $Ptr .= '<form name="stat" method="post" action="/adm/chart" >'."\n";
-    $Ptr .= '<table border="0"><tbody>';
     $Ptr .= '<tr><td align="right">';
     $Ptr .= '</td><td align="left">';
-    $Ptr .= '<input type="submit" name="sort" ';
+    $Ptr .= '<input type="submit" name="recalculate" ';
     $Ptr .= 'value="Recalculate Chart"/>'."\n";
     $Ptr .= '&nbsp;&nbsp;&nbsp;';
     $Ptr .= '<input type="submit" name="refresh" ';
-    $Ptr .= 'value="Refresh Chart"/></td>'."\n";
+    $Ptr .= 'value="Refresh Chart"/>'."\n";
+    $Ptr .= '&nbsp;&nbsp;&nbsp;';
+    $Ptr .= '<input type="submit" name="reset" ';
+    $Ptr .= 'value="Reset Selections"/></td>'."\n";
     $Ptr .= '</tr><tr><td align="right">';
     $Ptr .= '<b> Sort by: </b>'."\n";
     $Ptr .= '</td><td align="left">';
@@ -378,6 +604,16 @@ sub CreateForm {
     return $Ptr;
 }
 
+=pod
+
+=item &CreateLegend()
+
+This function returns a formatted string containing the legend for the
+chart.  The legend describes the symbols used to represent grades for
+problems.
+
+=cut
+
 sub CreateLegend {
     my $Str = "<p><pre>".
               "1..9: correct by student in 1..9 tries\n".
@@ -392,6 +628,15 @@ sub CreateLegend {
     return $Str;
 }
 
+=pod
+
+=item &StartDocument()
+
+Returns a string containing the header information for the chart: title,
+logo, and course title.
+
+=cut
+
 sub StartDocument {
     my $Str = '';
     $Str .= '<html>';
@@ -400,19 +645,62 @@ sub StartDocument {
     $Str .= '<body bgcolor="#FFFFFF">';
     $Str .= '<script>window.focus();</script>';
     $Str .= '<img align=right src=/adm/lonIcons/lonlogos.gif>';
-    $Str .= '<h1><pre>Assessment Chart'.(' 'x8).localtime();
-    $Str .= '</pre></h1>';
+    $Str .= '<h1>Assessment Chart</h1>';
     $Str .= '<h1>'.$ENV{'course.'.$ENV{'request.course.id'}.'.description'};
     $Str .= '</h1>';
-#    $Str .= '<h3>'.localtime().'</h3>';
 
     return $Str;
 }
 
 # ----- END FORMAT PRINT DATA ------------------------------------------
 
+=pod
+
+=head1 DOWNLOAD INFORMATION
+
+This section contains all the files that get data from other servers 
+and/or itself.  There is one function that has a call to get remote
+information but isn't included here which is ProcessTopLevelMap.  The
+usage was small enough to be ignored, but that portion may be moved
+here in the future.
+
+=cut
+
 # ----- DOWNLOAD INFORMATION -------------------------------------------
 
+=pod
+
+=item &DownloadPrerequisiteData()
+
+Collects lastname, generation, middlename, firstname, PID, and section for each
+student from their environment database.  The list of students is built from
+collecting a classlist for the course that is to be displayed.
+
+=over 4
+
+Input: $courseID, $c
+
+$courseID:  The id of the course
+
+$c: The connection class that can determine if the browser has aborted.  It
+is used to short circuit this function so that it doesn't continue to 
+get information when there is no need.
+
+Output: \%classlist
+
+\%classlist: A pointer to a hash containing the following data:
+
+-A list of student name:domain (as keys) (known below as $name)
+
+-A hash pointer for each student containing lastname, generation, firstname,
+middlename, and PID : Key is $name.'studentInformation'
+
+-A hash pointer to each students section data : Key is $name.section
+
+=back
+
+=cut
+
 sub DownloadPrerequisiteData {
     my ($courseID, $c)=@_;
     my ($courseDomain,$courseNumber)=split(/\_/,$courseID);
@@ -453,6 +741,30 @@ sub DownloadPrerequisiteData {
     return \%classlist;
 }
 
+=pod
+
+=item &DownloadStudentCourseInformation()
+
+Dump of all the course information for a single student.  There is no
+pruning of data, it is all stored in a hash and returned.
+
+=over 4
+
+Input: $name, $courseID
+
+$name: student name:domain
+
+$courseID:  The id of the course
+
+Output: \%courseData
+
+\%courseData:  A hash pointer to the raw data from the student's course
+database.
+
+=back
+
+=cut
+
 sub DownloadStudentCourseInformation {
     my ($name,$courseID)=@_;
     my ($studentName,$studentDomain) = split(/\:/,$name);
@@ -465,7 +777,45 @@ sub DownloadStudentCourseInformation {
 
 # ----- END DOWNLOAD INFORMATION ---------------------------------------
 
-# ----- END PROCESSING FUNCTIONS ---------------------------------------
+=pod
+
+=head1 PROCESSING FUNCTIONS
+
+These functions process all the data for all the students.  Also, they
+are the only functions that access the cache database for writing.  Thus
+they are the only functions that cache data.  The downloading and caching
+were separated to reduce problems with stopping downloading then can't
+tie hash to database later.
+
+=cut
+
+# ----- PROCESSING FUNCTIONS ---------------------------------------
+
+=pod
+
+=item &ProcessTopResourceMap()
+
+Trace through the "big hash" created in rat/lonuserstate.pm::loadmap.  
+Basically, this function organizes a subset of the data and stores it in
+cached data.  The data stored is the problems, sequences, sequence titles,
+parts of problems, and their ordering.  Column width information is also 
+partially handled here on a per sequence basis.
+
+=over 4
+
+Input: $ChartDB, $c
+
+$ChartDB:  The name of the cache database file
+
+$c:  The connection class used to determine if an abort has been sent to the 
+browser
+
+Output: A string that contains an error message or "OK" if everything went 
+smoothly.
+
+=back
+
+=cut
 
 sub ProcessTopResourceMap {
     my ($ChartDB,$c)=@_;
@@ -514,6 +864,17 @@ sub ProcessTopResourceMap {
 	    push(@finishResource, $lastResourceID);
 
 	    $currentSequence=$hash{'map_pc_'.$hash{'src_'.$currentResourceID}};
+
+            # Mark sequence as containing problems.  If it doesn't, then
+            # it will be removed when processing for this sequence is
+            # complete.  This allows the problems in a sequence
+            # to be outputed before problems in the subsequences
+            if(!defined($CacheData{'orderedSequences'})) {
+                $CacheData{'orderedSequences'}=$currentSequence;
+            } else {
+                $CacheData{'orderedSequences'}.=':'.$currentSequence;
+            }
+
 	    $lastResourceID=$hash{'map_finish_'.
 				  $hash{'src_'.$currentResourceID}};
 	    $currentResourceID=$hash{'map_start_'.
@@ -575,12 +936,6 @@ sub ProcessTopResourceMap {
 
 	    if(defined($CacheData{$currentSequence.':problems'})) {
 		# Capture sequence information here
-		if(!defined($CacheData{'orderedSequences'})) {
-		    $CacheData{'orderedSequences'}=$currentSequence;
-		} else {
-		    $CacheData{'orderedSequences'}.=':'.$currentSequence;
-		}
-
 		$CacheData{$currentSequence.':title'}=
 		    $hash{'title_'.$currentResourceID};
 
@@ -606,13 +961,16 @@ sub ProcessTopResourceMap {
 		    $CacheData{$currentSequence.':columnWidth'}=
                         (scalar @titleLength);
 		}
-	    }
+	    } else {
+                $CacheData{'orderedSequences'}=~s/$currentSequence//;
+                $CacheData{'orderedSequences'}=~s/::/:/g;
+                $CacheData{'orderedSequences'}=~s/^:|:$//g;
+            }
 
 	    $currentSequence=pop(@sequences);
 	    if($currentSequence eq $topLevelSequenceNumber) {
 		last;
 	    }
-	#else
 	}
 
 	# MOVE!!!
@@ -645,6 +1003,35 @@ sub ProcessTopResourceMap {
     return 'OK';
 }
 
+=pod
+
+=item &ProcessSection()
+
+Determine the section number for a student for the class.  A student can have 
+multiple sections for the same class.  The correct one is chosen.
+
+=over 4
+
+Input: $sectionData, $courseid, $ActiveFlag
+
+$sectionData:  A pointer to a hash containing all section data for this 
+student for the class
+
+$courseid:  The course ID.
+
+$ActiveFlag:  The student's active status (Active/Expired)
+
+Output: $oldsection, $cursection, or -1
+
+$oldsection and $cursection and sections number that will be displayed in the 
+chart.
+
+-1 is returned if an error occurs.
+
+=back
+
+=cut
+
 sub ProcessSection {
     my ($sectionData, $courseid,$ActiveFlag)=@_;
     $courseid=~s/\_/\//g;
@@ -699,8 +1086,44 @@ sub ProcessSection {
     return '-1';
 }
 
+=pod
+
+=item &ProcessStudentInformation()
+
+Takes data downloaded for a student and breaks it up into managable pieces and 
+stored in cache data.  The username, domain, class related date, PID, 
+full name, and section are all processed here.
+
+=over 4
+
+Input: $CacheData, $studentInformation, $section, $date, $name, $courseID
+
+$CacheData:  A hash pointer to the cached data
+
+$studentInformation:  Student information is what was requested in 
+&DownloadPrerequistedData().  See that function for what data is requested.
+
+$section: A hash pointer to class section related information.
+
+$date:  A composite of the start and end date for this class for this
+student.  Format:  end:start
+
+$name:  the username:domain information
+
+$courseID: The course ID
+
+Output: None
+
+*NOTE:  There is no return value, but if an error occurs a key is added to 
+the cache data with the value being the error message.  The key is 
+username:domain:error.  It will only exist if an error occurs.
+
+=back
+
+=cut
+
 sub ProcessStudentInformation {
-    my ($CacheData,$studentInformation,$section,$date,$name,$courseID,$c)=@_;
+    my ($CacheData,$studentInformation,$section,$date,$name,$courseID)=@_;
     my ($studentName,$studentDomain) = split(/\:/,$name);
 
     $CacheData->{$name.':username'}=$studentName;
@@ -723,16 +1146,50 @@ sub ProcessStudentInformation {
     }
 
     # Get student's section number
-    my $sec=&ProcessSection($section, $courseID, $ENV{'form.status'});
+    my $sec=&ProcessSection($section, $courseID, $CacheData->{'form.status'});
     if($sec != -1) {
 	$CacheData->{$name.':section'}=$sec;
     } else {
 	$CacheData->{$name.':section'}='';
     }
 
-    return 0;
+    return;
 }
 
+=pod
+
+=item &ProcessClassList()
+
+Taking the class list dumped from &DownloadPrerequisiteData(), all the 
+students and their non-class information is processed using the 
+&ProcessStudentInformation() function.  A date stamp is also recorded for
+when the data was processed.
+
+=over 4
+
+Input: $classlist, $courseID, $ChartDB, $c
+
+$classlist:  The hash of data collected about a student from 
+&DownloadPrerequisteData().  The hash contains a list of students, a pointer 
+to a hash of student information for each student, and each student's section 
+number.
+
+$courseID:  The course ID
+
+$ChartDB:  The name of the cache database file.
+
+$c:  The connection class used to determine if an abort has been sent to the 
+browser
+
+Output: @names
+
+@names:  An array of students whose information has been processed, and are to 
+be considered in an arbitrary order.
+
+=back
+
+=cut
+
 sub ProcessClassList {
     my ($classlist,$courseID,$ChartDB,$c)=@_;
     my @names=();
@@ -753,18 +1210,192 @@ sub ProcessClassList {
                                     $classlist->{$name.':studentInformation'},
                                     $classlist->{$name.':section'},
                                     $classlist->{$name},
-                                    $name,$courseID,$c);
+                                    $name,$courseID);
         }
 
+        # Time of download
+        $CacheData{'time'}=localtime();
 	untie(%CacheData);
     }
 
     return @names;
 }
 
-# ----- END PROCESSING FUNCTIONS ---------------------------------------
+=pod
 
-# ----- HELPER FUNCTIONS -----------------------------------------------
+=item &ProcessStudentData()
+
+Takes the course data downloaded for a student in 
+&DownloadStudentCourseInformation() and breaks it up into key value pairs
+to be stored in the cached data.  The keys are comprised of the 
+$username:$domain:$keyFromCourseDatabase.  The student username:domain is
+stored away signifying that the student's information has been downloaded and 
+can be reused from cached data.
+
+=over 4
+
+Input: $courseData, $name, $ChartDB
+
+$courseData:  A hash pointer that points to the course data downloaded for a 
+student.
+
+$name:  username:domain
+
+$ChartDB:  The name of the cache database file which will allow the data to
+be written to the cache.
+
+Output: None
+
+*NOTE:  There is no output, but an error message is stored away in the cache 
+data.  This is checked in &FormatStudentData().  The key username:domain:error 
+will only exist if an error occured.  The error is an error from 
+&DownloadStudentCourseInformation().
+
+=back
+
+=cut
+
+sub ProcessStudentData {
+    my ($courseData, $name, $ChartDB)=@_;
+
+    my %CacheData;
+    if(tie(%CacheData,'GDBM_File',$ChartDB,&GDBM_WRCREAT,0640)) {
+        my ($checkForError) = keys(%$courseData);
+        if($checkForError =~ /^(con_lost|error|no_such_host)/i) {
+            $CacheData{$name.':error'}='Could not download course data.';
+        } else {
+            foreach my $key (keys (%$courseData)) {
+                $CacheData{$name.':'.$key}=$courseData->{$key};
+            }
+            if(defined($CacheData{'NamesOfStudents'})) {
+                $CacheData{'NamesOfStudents'}.=':::'.$name;
+            } else {
+                $CacheData{'NamesOfStudents'}=$name;
+            }
+        }
+        untie(%CacheData);
+    }
+
+    return;
+}
+
+=pod
+
+=item &ProcessFormData()
+
+Cache form data and set default form data (sort, status, heading.$number,
+sequence.$number, reselect, reset, recalculate, and refresh)
+
+=over 4
+
+Input: $ChartDB, $isCached
+
+$ChartDB: The name of the database for cached data
+
+$isCached: Is there already data for this course cached.  This is used in 
+conjunction with the absence of all form data to know to display all selection 
+types.
+
+Output: None
+
+=back
+
+=cut
+
+sub ProcessFormData {
+    my ($ChartDB, $isCached)=@_;
+    my %CacheData;
+
+    if(tie(%CacheData,'GDBM_File',$ChartDB,&GDBM_WRCREAT,0640)) {
+        if(defined($ENV{'form.sort'})) {
+            $CacheData{'form.sort'}=$ENV{'form.sort'};
+        } elsif(!defined($CacheData{'form.sort'})) {
+            $CacheData{'form.sort'}='username';
+        }
+
+        # Ignore $ENV{'form.refresh'}
+        # Ignore $ENV{'form.recalculate'}
+
+        if(defined($ENV{'form.status'})) {
+            $CacheData{'form.status'}=$ENV{'form.status'};
+        } elsif(!defined($CacheData{'form.status'})) {
+            $CacheData{'form.status'}='Active';
+        }
+
+        my @headings=();
+        my @sequences=();
+        my $found=0;
+        foreach (keys(%ENV)) {
+            if(/form\.heading/) {
+                $found++;
+                push(@headings, $_);
+            } elsif(/form\.sequence/) {
+                $found++;
+                push(@sequences, $_);
+            } elsif(/form\./) {
+                $found++;
+            }
+        }
+
+        if($found) {
+            $CacheData{'form.headings'}=join(":::",@headings);
+            $CacheData{'form.sequences'}=join(":::",@sequences);
+        }
+
+        if(defined($ENV{'form.reselect'})) {
+            my @reselected = (ref($ENV{'form.reselect'}) ? 
+                              @{$ENV{'form.reselect'}}
+                              : ($ENV{'form.reselect'}));
+            foreach (@reselected) {
+                if(/heading/) {
+                    $CacheData{'form.headings'}.=":::".$_;
+                } elsif(/sequence/) {
+                    $CacheData{'form.sequences'}.=":::".$_;
+                }
+            }
+        }
+
+        if(defined($ENV{'form.reset'}) || (!$found && !$isCached)) {
+            $CacheData{'form.reset'}='true';
+            $CacheData{'form.status'}='Active';
+            $CacheData{'form.sort'}='username';
+            $CacheData{'form.headings'}='ALLHEADINGS';
+            $CacheData{'form.sequences'}='ALLSEQUENCES';
+        } else {
+            $CacheData{'form.reset'}='false';
+        }
+
+        untie(%CacheData);
+    }
+
+    return;
+}
+
+=pod
+
+=item &SpaceColumns()
+
+Determines the width of all the columns in the chart.  It is based on
+the max of the data for that column and its header.
+
+=over 4
+
+Input: $students, $studentInformation, $headings, $ChartDB
+
+$students: An array pointer to a list of students (username:domain)
+
+$studentInformatin: The type of data for the student information.  It is
+used as part of the key in $CacheData.
+
+$headings: The name of the student information columns.
+
+$ChartDB: The name of the cache database which is opened for read/write.
+
+Output: None - All data stored in cache.
+
+=back
+
+=cut
 
 sub SpaceColumns {
     my ($students,$studentInformation,$headings,$ChartDB)=@_;
@@ -793,6 +1424,28 @@ sub SpaceColumns {
     return;
 }
 
+# ----- END PROCESSING FUNCTIONS ---------------------------------------
+
+=pod
+
+=head1 HELPER FUNCTIONS
+
+These are just a couple of functions do various odd and end 
+jobs.
+
+=cut
+
+# ----- HELPER FUNCTIONS -----------------------------------------------
+
+=pod
+
+=item &ProcessFullName()
+
+Takes lastname, generation, firstname, and middlename (or some partial
+set of this data) and returns the full name version as a string.
+
+=cut
+
 sub ProcessFullName {
     my ($lastname, $generation, $firstname, $middlename)=@_;
     my $Str = '';
@@ -833,6 +1486,31 @@ sub ProcessFullName {
     return $Str;
 }
 
+=pod
+
+=item &SortStudents()
+
+Determines which students to display and in which order.  Which are 
+displayed are determined by their status(active/expired).  The order
+is determined by the sort button pressed (default to username).  The
+type of sorting is username, lastname, or section.
+
+=over 4
+
+Input: $students, $CacheData
+
+$students: A array pointer to a list of students (username:domain)
+
+$CacheData: A pointer to the hash tied to the cached data
+
+Output: @order
+
+@order: An ordered list of students (username:domain)
+
+=back
+
+=cut
+
 sub SortStudents {
     my ($students,$CacheData)=@_;
 
@@ -841,7 +1519,7 @@ sub SortStudents {
         my ($end,$start)=split(/\:/,$CacheData->{$_.':date'});
         my $active=1;
         my $now=time;
-        my $Status=$ENV{'form.status'};
+        my $Status=$CacheData->{'form.status'};
         $Status = ($Status) ? $Status : 'Active';
         if((($end) && $now > $end) && (($Status eq 'Active'))) { 
             $active=0; 
@@ -854,7 +1532,7 @@ sub SortStudents {
         }
     }
 
-    my $Pos = $ENV{'form.sort'};
+    my $Pos = $CacheData->{'form.sort'};
     my %sortData;
     if($Pos eq 'Last Name') {
 	for(my $index=0; $index<scalar @sorted1Students; $index++) {
@@ -881,19 +1559,45 @@ sub SortStudents {
     return @order;
 }
 
+=pod
+
+=item &TestCacheData()
+
+Determine if the cache database can be accessed with a tie.  It waits up to
+ten seconds before returning failure.  This function exists to help with
+the problems with stopping the data download.  When an abort occurs and the
+user quickly presses a form button and httpd child is created.  This
+child needs to wait for the other to finish (hopefully within ten seconds).
+
+=over 4
+
+Input: $ChartDB
+
+$ChartDB: The name of the cache database to be opened
+
+Output: -1, 0, 1
+
+-1: Couldn't tie database
+ 0: Use cached data
+ 1: New cache database created, use that.
+
+=back
+
+=cut
+
 sub TestCacheData {
     my ($ChartDB)=@_;
     my $isCached=-1;
     my %testData;
     my $tieTries=0;
 
-    if ((-e "$ChartDB") && ($ENV{'form.sort'} ne 'Recalculate Chart')) {
+    if ((-e "$ChartDB") && (!defined($ENV{'form.recalculate'}))) {
 	$isCached = 1;
     } else {
 	$isCached = 0;
     }
 
-    while($tieTries < 3) {
+    while($tieTries < 10) {
         my $result=0;
         if($isCached) {
             $result=tie(%testData,'GDBM_File',$ChartDB,&GDBM_READER,0640);
@@ -906,7 +1610,7 @@ sub TestCacheData {
         $tieTries++;
         sleep 1;
     }
-    if($tieTries >= 3) {
+    if($tieTries >= 10) {
         return -1;
     }
 
@@ -915,56 +1619,85 @@ sub TestCacheData {
     return $isCached;
 }
 
-sub ExtractStudentData {
-    my ($courseData, $name, $ChartDB)=@_;
+=pod
 
-    my %CacheData;
-    if(tie(%CacheData,'GDBM_File',$ChartDB,&GDBM_WRCREAT,0640)) {
-        my ($checkForError) = keys(%$courseData);
-        if($checkForError =~ /^(con_lost|error|no_such_host)/i) {
-            $CacheData{$name.':error'}='Could not download course data.';
-        } else {
-            foreach my $key (keys (%$courseData)) {
-                $CacheData{$name.':'.$key}=$courseData->{$key};
-            }
-            if(defined($CacheData{'NamesOfStudents'})) {
-                $CacheData{'NamesOfStudents'}.=':::'.$name;
-            } else {
-                $CacheData{'NamesOfStudents'}=$name;
-            }
-        }
-        untie(%CacheData);
-    }
+=item &ShouldShowColumn()
 
-    return;
-}
+Determine if a specified column should be shown on the chart.
+
+=over 4
+
+Input: $cache, $test
+
+$cache: A pointer to the hash tied to the cached data
+
+$test: The form name of the column (heading.$headingIndex) or 
+(sequence.$sequenceIndex)
+
+Output: 0 (false), 1 (true)
+
+=back
+
+=cut
 
 sub ShouldShowColumn {
-    my ($reselected,$type,$value)=@_;
+    my ($cache,$test)=@_;
 
-    if($ENV{'form.sort'} eq 'Recalculate Chart') {
+    if($cache->{'form.reset'} eq 'true') {
         return 1;
     }
 
-    if(defined($ENV{'form.'.$type.$value})) {
+    my $headings=$cache->{'form.headings'};
+    my $sequences=$cache->{'form.sequences'};
+    if($headings eq 'ALLHEADINGS' || $sequences eq 'ALLSEQUENCES' ||
+       $headings=~/$test/ || $sequences=~/$test/) {
         return 1;
     }
 
-    return &CheckForStringInArray($reselected, $type.$value);
-}
-
-sub CheckForStringInArray {
-    my ($inputArray,$checkString)=@_;
-    foreach (@$inputArray) {
-        if($_ eq $checkString) {
-            return 1;
-        }
-    }
     return 0;
 }
 
 # ----- END HELPER FUNCTIONS --------------------------------------------
 
+=pod
+
+=head1 Handler and main function(BuildChart)
+
+The handler does some initial error checking and then passes the torch to
+BuildChart.  BuildChart calls all the appropriate functions to get the
+job done.  These are the only two functions that use print ($r).  All other
+functions return strings to BuildChart to be printed.
+
+=cut
+
+=pod
+
+=item &BuildChart()
+
+ The following is the process that BuildChart goes through to 
+  create the html document.
+
+ -Start the lonchart document
+ -Test for access to the CacheData
+ -Download class list information if not using cached data 
+ -Sort students and print out table desciptive data
+ -Output student data
+ -If recalculating, store a list of students, but only if all 
+  their data was downloaded.  Leave off the others.
+ -End document
+
+=over 4
+
+Input: $r
+
+$r:  Used to print html
+
+Output: None
+
+=back
+
+=cut
+
 sub BuildChart {
     my ($r)=@_;
     my $c = $r->connection;
@@ -980,10 +1713,6 @@ sub BuildChart {
     my $cid=$ENV{'request.course.id'};
     my $ChartDB = "/home/httpd/perl/tmp/$ENV{'user.name'}".
                   "_$ENV{'user.domain'}_$cid\_chart.db";
-    # $ENV{'form.domains'} can be either a scalar or an array reference.
-    # We need an array.
-    my @reselected = (ref($ENV{'form.reselect'}) ? @{$ENV{'form.reselect'}}
-                      : ($ENV{'form.reselect'}));
 
     $isCached=&TestCacheData($ChartDB);
     if($isCached < 0) {
@@ -991,6 +1720,7 @@ sub BuildChart {
         $r->rflush();
         return;
     }
+    &ProcessFormData($ChartDB, $isCached);
 
     # Download class list information if not using cached data
     my %CacheData;
@@ -1025,31 +1755,36 @@ sub BuildChart {
     }
 
     # Sort students and print out table desciptive data
+    my $downloadTime=0;
     if(tie(%CacheData,'GDBM_File',$ChartDB,&GDBM_READER,0640)) {
         if(!$c->aborted()) { @students=&SortStudents(\@students,\%CacheData); }
+        if(defined($CacheData{'time'})) { $downloadTime=$CacheData{'time'}; }
+        else { $downloadTime=localtime(); }
+        if(!$c->aborted()) { $r->print('<h3>'.$downloadTime.'</h3>'); }
         if(!$c->aborted()) { $r->print('<h1>'.(scalar @students).
                                        ' students</h1>'); }
 	if(!$c->aborted()) { $r->rflush(); }
 	if(!$c->aborted()) { $r->print(&CreateLegend()); }
-	if(!$c->aborted()) { $r->print(&CreateForm()); }
+        if(!$c->aborted()) { $r->print('<table border="0"><tbody>'); }
+	if(!$c->aborted()) { $r->print(&CreateForm(\%CacheData)); }
 	if(!$c->aborted()) { $r->print(&CreateColumnSelectionBox(
                                                        \%CacheData,
-                                                       \@studentInformation, 
-						       \@headings, 
-                                                       \@reselected,
-                                                       $spacePadding)); }
+                                                       \@headings)); }
+        if(!$c->aborted()) { $r->print('</tbody></table>'); }
+        if(!$c->aborted()) { $r->print('<b>Note: Uncheck the boxes above a'); }
+        if(!$c->aborted()) { $r->print(' column to remove that column from'); }
+        if(!$c->aborted()) { $r->print(' the display.</b></pre>'); }
+        if(!$c->aborted()) { $r->print('<table border="0" cellpadding="0" '); }
+        if(!$c->aborted()) { $r->print('cellspacing="0"><tbody>'); }
 	if(!$c->aborted()) { $r->print(&CreateColumnSelectors(
                                                        \%CacheData,
-                                                       \@studentInformation, 
-						       \@headings, 
-                                                       \@reselected,
-                                                       $spacePadding)); }
+                                                       \@headings)); }
 	if(!$c->aborted()) { $r->print(&CreateTableHeadings(
                                                          \%CacheData,
                                                          \@studentInformation, 
 							 \@headings, 
-                                                         \@reselected,
 							 $spacePadding)); }
+        if(!$c->aborted()) { $r->print('</tbody></table>'); }
 	if(!$c->aborted()) { $r->rflush(); }
 	untie(%CacheData);
     } else {
@@ -1057,6 +1792,7 @@ sub BuildChart {
 	return;
     }
 
+    # Output student data
     my @updateStudentList = ();
     my $courseData;
     $r->print('<pre>');
@@ -1069,14 +1805,15 @@ sub BuildChart {
             $courseData=&DownloadStudentCourseInformation($_, $cid);
             if($c->aborted()) { last; }
             push(@updateStudentList, $_);
-            &ExtractStudentData($courseData, $_, $ChartDB);
+            &ProcessStudentData($courseData, $_, $ChartDB);
         }
-        $r->print(&FormatStudentData(\@reselected, $_, $cid, 
-                                     \@studentInformation,
+        $r->print(&FormatStudentData($_, \@studentInformation,
                                      $spacePadding, $ChartDB));
         $r->rflush();
     }
 
+    # If recalculating, store a list of students, but only if all their 
+    # data was downloaded.  Leave off the others.
     if(!$isCached && tie(%CacheData,'GDBM_File',$ChartDB,&GDBM_WRCREAT,0640)) {
         $CacheData{'NamesOfStudents'}=join(":::", @updateStudentList);
 #		    $CacheData{'NamesOfStudents'}=
@@ -1084,6 +1821,7 @@ sub BuildChart {
         untie(%CacheData);
     }
 
+    # End document
     $r->print('</pre></body></html>');
     $r->rflush();
 
@@ -1092,9 +1830,29 @@ sub BuildChart {
 
 # ================================================================ Main Handler
 
+=pod
+
+=item &handler()
+
+The handler checks for permission to access the course data and for 
+initial header problem.  Then it passes the torch to the work horse
+function BuildChart.
+
+=over 4
+
+Input: $r
+
+$r: This is the object that is used to print.
+
+Output: A Value (OK or HTTP_NOT_ACCEPTABLE)
+
+=back
+
+=cut
+
 sub handler {
     my $r=shift;
-    $jr=$r;
+#    $jr=$r;
     unless(&Apache::lonnet::allowed('vgr',$ENV{'request.course.id'})) {
 	$ENV{'user.error.msg'}=
         $r->uri.":vgr:0:0:Cannot view grades for complete course";