--- loncom/interface/statistics/lonstudentassessment.pm	2003/01/13 01:34:11	1.27
+++ loncom/interface/statistics/lonstudentassessment.pm	2003/02/25 20:47:47	1.29
@@ -1,7 +1,6 @@
 # The LearningOnline Network with CAPA
-# (Publication Handler
 #
-# $Id: lonstudentassessment.pm,v 1.27 2003/01/13 01:34:11 minaeibi Exp $
+# $Id: lonstudentassessment.pm,v 1.29 2003/02/25 20:47:47 matthew Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -25,24 +24,75 @@
 # http://www.lon-capa.org/
 #
 # (Navigate problems for statistical reports
-# YEAR=2001
-# 5/5,7/9,7/25/1,8/11,9/13,9/26,10/5,10/9,10/22,10/26 Behrouz Minaei
-# 11/1,11/4,11/16,12/14,12/16,12/18,12/20,12/31 Behrouz Minaei
-# YEAR=2002
-# 1/22,2/1,2/6,2/25,3/2,3/6,3/17,3/21,3/22,3/26,4/7,5/6 Behrouz Minaei
-# 5/12,5/14,5/15,5/19,5/26,7/16,12/24  Behrouz Minaei
-# YEAR=2003  
-# 1/11  Behrouz Minaei
-###
+#
+#######################################################
+#######################################################
+
+=pod
+
+=head1 NAME
+
+lonstudentassessment
+
+=head1 SYNOPSIS
+
+Presents assessment data about a student or a group of students.
+
+=head1 Subroutines
+
+=over 4 
+
+=cut
+
+#######################################################
+#######################################################
 
 package Apache::lonstudentassessment;
 
 use strict;
+use Apache::lonstatistics;
 use Apache::lonhtmlcommon;
 use Apache::loncoursedata;
+use Apache::lonnet; # for logging porpoises
 use GDBM_File;
 
+#######################################################
+#######################################################
+
+=pod
+
+=item &BuildStudentAssessmentPage()
+
+Inputs: 
+
+=over 4
+
+=item $cacheDB The name of the cache file used to store student data
+
+=item $students Array ref containing the name(s) of the students 
+selected for display
+
+=item $courseID The ID of the course
+
+=item $formName The name of the html form - 'Statistics'
+
+=item $headings Array ref of headings to show
+
+=item $spacing A string of spaces
 
+=item $studentInformation Array ref of possible headings for student info
+('fullname','section',...)
+
+=item $r Apache Request
+
+=item $c Apache Connection 
+
+=back
+
+=cut
+
+#######################################################
+#######################################################
 sub BuildStudentAssessmentPage {
     my ($cacheDB,$students,$courseID,$formName,$headings,$spacing,
         $studentInformation,$r,$c)=@_;
@@ -185,10 +235,41 @@ sub BuildStudentAssessmentPage {
     }
     return;
 }
+#######################################################
+#######################################################
+
+=pod
 
+=item &CreateInterface()
 
-#---- Student Assessment Web Page --------------------------------------------
+Called by &BuildStudentAssessmentPage to create the top part of the
+page which displays the chart.
+
+Inputs:
+
+=over 4
 
+=item $cache The ubiquitous cache
+
+=item $selectedName The name of the currently selected student, or
+'All Students' or 'No Student Selected'.
+
+=item $students Array ref containing the name(s) of the students selected
+for display.
+
+=item $formName The name of the HTML form to use, 'Statistics'
+
+=item $doNotShow Array ref containing the names of columns to not show
+
+=back
+
+Returns:  A string containing the HTML for the headers and top table for 
+the chart page.
+
+=cut
+
+#######################################################
+#######################################################
 sub CreateInterface {
     my($cache,$selectedName,$students,$formName,$doNotShow)=@_;
 
@@ -215,9 +296,7 @@ sub CreateInterface {
     $Str .= '<tr><td align="center">'."\n";
     my @sections = split(':',$cache->{'sectionList'});
     my @selectedSections = split(':',$cache->{'sectionsSelected'});
-    $Str .= &Apache::lonhtmlcommon::MultipleSectionSelect(\@sections,
-                                                          \@selectedSections,
-                                                          'Statistics');
+    $Str .= &Apache::lonstatistics::SectionSelect('Section','multiple',5);
     $Str .= '</td><td align="center">';
     $Str .= &CreateColumnSelectionBox($doNotShow);
     $Str .= '</td><td>'."\n";
@@ -238,7 +317,43 @@ sub CreateInterface {
 
     return $Str;
 }
+#######################################################
+#######################################################
 
+=pod
+
+=item &CreateTableHeadings()
+
+Create HTML for the columns of student data to show.
+Called by &BuildStudentAssessmentPage().  Calls
+&Apache::lonhtmlcommon::CreateHeadings().
+
+Inputs:
+
+=over 4
+
+=item $cache The ubiquitous cache
+
+=item $spacing A string of spaces
+
+=item $infoKeys Array ref to names of keys to display from the cache 
+which describe students
+
+=item $infoHeadings Array ref to headings of columns for student info
+
+=item $sequenceKeys Array ref of names of keys to use to retrieve sequence
+data from the cache
+
+=item $sequenceHeadings Array ref of names of sequences used for output.
+
+=back
+
+Returns: A string containing the HTML of the table headings.
+
+=cut
+
+#######################################################
+#######################################################
 sub CreateTableHeadings {
     my($cache,$spacing,$infoKeys,$infoHeadings,$sequenceKeys,
        $sequenceHeadings)=@_;
@@ -278,38 +393,39 @@ sub CreateTableHeadings {
     return $Str;
 }
 
+#######################################################
+#######################################################
+
 =pod
 
-=item &FormatStudentData()
+=item &StudentReport()
 
-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.
+This is the workhorse subroutine - it handles formatting and display of a
+students performance data.  It processes one row of the chart.
+
+Input: 
 
 =over 4
 
-Input: $name, $studentInformation, $ChartDB
+=item $cache The ubiquitous cache
+
+=item $name The name and domain of the current student in name:domain format
 
-$name: The name and domain of the current student in name:domain format
+=item $spacing A string containing spaces.
 
-$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.
+=item $showSequences Array ref containing the sequences to display
 
-$ChartDB: The name of the cached data database which will be tied to that 
-database.
+=back
 
 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 StudentReport {
     my ($cache,$name,$spacing,$showSequences)=@_;
     my ($username,$domain)=split(':',$name);
@@ -405,7 +521,11 @@ sub StudentReport {
     return $Str;
 }
 
+#######################################################
+#######################################################
 
+#######################################################
+#######################################################
 sub StudentAverageTotal {
     my ($cache, $students, $sequenceKeys)=@_;
     my $Str = "\n<b>Summary Tables:</b>\n";
@@ -467,8 +587,11 @@ sub StudentAverageTotal {
     return $Str;
 }
 
+#######################################################
+#######################################################
 
-
+#######################################################
+#######################################################
 sub MaxSeqPr {
     my ($cache, $name, $sequence)=@_;
     my $prCount=0;
@@ -487,9 +610,8 @@ sub MaxSeqPr {
     return $prCount;
 }
 
-
-
-
+#######################################################
+#######################################################
 
 =pod
 
@@ -501,6 +623,8 @@ problems.
 
 =cut
 
+#######################################################
+#######################################################
 sub CreateLegend {
     my $Str = "<p><pre>".
               "   1  correct by student in 1 try\n".
@@ -516,6 +640,9 @@ sub CreateLegend {
     return $Str;
 }
 
+#######################################################
+#######################################################
+
 =pod
 
 =item &CreateColumnSelectionBox()
@@ -529,7 +656,6 @@ 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.
@@ -545,6 +671,8 @@ which has a size of four.
 
 =cut
 
+#######################################################
+#######################################################
 sub CreateColumnSelectionBox {
     my ($doNotShow)=@_;
 
@@ -564,6 +692,9 @@ sub CreateColumnSelectionBox {
     return $notThere;
 }
 
+#######################################################
+#######################################################
+
 =pod
 
 =item &CreateColumnSelectors()
@@ -590,6 +721,8 @@ for consistency of location over the col
 
 =cut
 
+#######################################################
+#######################################################
 sub CreateColumnSelectors {
     my ($infoHeadings, $sequenceHeadings, $sequenceKeys)=@_;
 
@@ -611,10 +744,21 @@ sub CreateColumnSelectors {
     return $present;
 }
 
-#---- END Student Assessment Web Page ----------------------------------------
+#######################################################
+#######################################################
+
+=pod
+
+=back
 
-#---- Student Assessment Worker Functions ------------------------------------
+=head1 HELPER FUNCTIONS
 
+=over 4
+
+=cut 
+
+#######################################################
+#######################################################
 sub FindSelectedStudent {
     my($cache, $selectedName, $students)=@_;
 
@@ -652,6 +796,8 @@ sub FindSelectedStudent {
 
     return 'No Student Selected';
 }
+#######################################################
+#######################################################
 
 =pod
 
@@ -668,12 +814,12 @@ $cache: A pointer to the hash tied to th
 $test: The form name of the column (heading.$headingIndex) or 
 (sequence.$sequenceIndex)
 
-Output: 0 (false), 1 (true)
-
 =back
 
 =cut
 
+#######################################################
+#######################################################
 sub ShouldShowColumns {
     my ($cache,$headings,$cacheKey)=@_;
 
@@ -718,8 +864,18 @@ sub ShouldShowColumns {
     return (\@infoHeadings, \@infoKeys, \@sequenceHeadings,
             \@sequenceKeys, \%doNotShow);
 }
+1;
 
-#---- END Student Assessment Worker Functions --------------------------------
+#######################################################
+#######################################################
+
+=pod 
+
+=back
+
+=cut
+
+#######################################################
+#######################################################
 
-1;
 __END__