--- loncom/interface/loncommon.pm	2003/10/27 21:21:08	1.136
+++ loncom/interface/loncommon.pm	2003/10/30 13:57:06	1.140
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # a pile of common routines
 #
-# $Id: loncommon.pm,v 1.136 2003/10/27 21:21:08 matthew Exp $
+# $Id: loncommon.pm,v 1.140 2003/10/30 13:57:06 matthew Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -69,6 +69,7 @@ use Apache::Constants qw(:common :http :
 use Apache::lonmsg();
 use Apache::lonmenu();
 use Apache::lonlocal;
+use HTML::Entities;
 
 my $readit;
 
@@ -2678,6 +2679,28 @@ sub check_if_partid_hidden {
     return undef;
 }
 
+
+############################################################
+############################################################
+
+=pod
+
+=head1 cgi-bin script and graphing routines
+
+=item get_cgi_id
+
+Inputs: none
+
+Returns an id which can be used to pass environment variables
+to various cgi-bin scripts.  These environment variables will
+be removed from the users environment after a given time by
+the routine &Apache::lonnet::transfer_profile_to_env.
+
+=cut
+
+############################################################
+############################################################
+
 sub get_cgi_id {
     return (time.'_'.int(rand(1000)));
 }
@@ -2689,6 +2712,37 @@ sub get_cgi_id {
 
 =item DrawBarGraph
 
+Facilitates the plotting of data in a (stacked) bar graph.
+Puts plot definition data into the users environment in order for 
+graph.png to plot it.  Returns an <img> tag for the plot.
+The bars on the plot are labeled '1','2',...,'n'.
+
+Inputs:
+
+=over 4
+
+=item $Title: string, the title of the plot
+
+=item $xlabel: string, text describing the X-axis of the plot
+
+=item $ylabel: string, text describing the Y-axis of the plot
+
+=item $Max: scalar, the maximum Y value to use in the plot
+If $Max is < any data point, the graph will not be rendered.
+
+=item $colors: array ref holding the colors to be used for the data sets when
+they are plotted.  If undefined, default values will be used.
+
+=item @Values: An array of array references.  Each array reference holds data
+to be plotted in a stacked bar chart.
+
+=back
+
+Returns:
+
+An <img> tag which references graph.png and the appropriate identifying
+information for the plot.
+
 =cut
 
 ############################################################
@@ -2741,13 +2795,18 @@ sub DrawBarGraph {
         push (@Labels,$i+1);
     }
     #
+    $Max = 1 if ($Max < 1);
+    if ( int($Max) < $Max ) {
+        $Max++;
+        $Max = int($Max);
+    }
     $Title  = '' if (! defined($Title));
     $xlabel = '' if (! defined($xlabel));
     $ylabel = '' if (! defined($ylabel));
     $ValuesHash{$id.'.title'}    = &Apache::lonnet::escape($Title);
     $ValuesHash{$id.'.xlabel'}   = &Apache::lonnet::escape($xlabel);
     $ValuesHash{$id.'.ylabel'}   = &Apache::lonnet::escape($ylabel);
-    $ValuesHash{$id.'.Max'}      = $Max;
+    $ValuesHash{$id.'.y_max_value'} = $Max;
     $ValuesHash{$id.'.NumBars'}  = $NumBars;
     $ValuesHash{$id.'.NumSets'}  = $NumSets;
     $ValuesHash{$id.'.PlotType'} = 'bar';
@@ -2758,12 +2817,6 @@ sub DrawBarGraph {
     $ValuesHash{$id.'.bar_width'} = $bar_width;
     $ValuesHash{$id.'.labels'} = join(',',@Labels);
     #
-    $Max = 1 if ($Max < 1);
-    if ( int($Max) < $Max ) {
-        $Max++;
-        $Max = int($Max);
-    }
-    #
     &Apache::lonnet::appenv(%ValuesHash);
     return '<img src="/cgi-bin/graph.png?'.$identifier.'" border="1" />';
 }
@@ -2775,12 +2828,145 @@ sub DrawBarGraph {
 
 =item DrawXYGraph
 
+Facilitates the plotting of data in an XY graph.
+Puts plot definition data into the users environment in order for 
+graph.png to plot it.  Returns an <img> tag for the plot.
+
+Inputs:
+
+=over 4
+
+=item $Title: string, the title of the plot
+
+=item $xlabel: string, text describing the X-axis of the plot
+
+=item $ylabel: string, text describing the Y-axis of the plot
+
+=item $Max: scalar, the maximum Y value to use in the plot
+If $Max is < any data point, the graph will not be rendered.
+
+=item $colors: Array ref containing the hex color codes for the data to be 
+plotted in.  If undefined, default values will be used.
+
+=item $Xlabels: Array ref containing the labels to be used for the X-axis.
+
+=item $Ydata: Array ref containing Array refs.  
+Each of the contained arrays will be plotted as a seperate curve.
+
+=item %Values: hash indicating or overriding any default values which are 
+passed to graph.png.  
+Possible values are: width, xskip, x_ticks, x_tick_offset, among others.
+
+=back
+
+Returns:
+
+An <img> tag which references graph.png and the appropriate identifying
+information for the plot.
+
 =cut
 
 ############################################################
 ############################################################
 sub DrawXYGraph {
-    my ($Title,$xlabel,$ylabel,$Max,$Xlabels,$Ydata,%Values)=@_;
+    my ($Title,$xlabel,$ylabel,$Max,$colors,$Xlabels,$Ydata,%Values)=@_;
+    #
+    # Create the identifier for the graph
+    my $identifier = &get_cgi_id();
+    my $id = 'cgi.'.$identifier;
+    #
+    $Title  = '' if (! defined($Title));
+    $xlabel = '' if (! defined($xlabel));
+    $ylabel = '' if (! defined($ylabel));
+    my %ValuesHash = 
+        (
+         $id.'.title'  => &Apache::lonnet::escape($Title),
+         $id.'.xlabel' => &Apache::lonnet::escape($xlabel),
+         $id.'.ylabel' => &Apache::lonnet::escape($ylabel),
+         $id.'.y_max_value'=> $Max,
+         $id.'.labels'     => join(',',@$Xlabels),
+         $id.'.PlotType'   => 'XY',
+         );
+    #
+    if (defined($colors) && ref($colors) eq 'ARRAY') {
+        $ValuesHash{$id.'.Colors'}   = join(',',@{$colors});
+    }
+    #
+    if (! ref($Ydata) || ref($Ydata) ne 'ARRAY') {
+        return '';
+    }
+    my $NumSets=1;
+    foreach my $array (@{$Ydata}){
+        next if (! ref($array));
+        $ValuesHash{$id.'.data.'.$NumSets++} = join(',',@$array);
+    }
+    $ValuesHash{$id.'.NumSets'} = $NumSets-1;
+    #
+    # Deal with other parameters
+    while (my ($key,$value) = each(%Values)) {
+        $ValuesHash{$id.'.'.$key} = $value;
+    }
+    #
+    &Apache::lonnet::appenv(%ValuesHash);
+    return '<img src="/cgi-bin/graph.png?'.$identifier.'" border="1" />';
+}
+
+############################################################
+############################################################
+
+=pod
+
+=item DrawXYYGraph
+
+Facilitates the plotting of data in an XY graph with two Y axes.
+Puts plot definition data into the users environment in order for 
+graph.png to plot it.  Returns an <img> tag for the plot.
+
+Inputs:
+
+=over 4
+
+=item $Title: string, the title of the plot
+
+=item $xlabel: string, text describing the X-axis of the plot
+
+=item $ylabel: string, text describing the Y-axis of the plot
+
+=item $colors: Array ref containing the hex color codes for the data to be 
+plotted in.  If undefined, default values will be used.
+
+=item $Xlabels: Array ref containing the labels to be used for the X-axis.
+
+=item $Ydata1: The first data set
+
+=item $Min1: The minimum value of the left Y-axis
+
+=item $Max1: The maximum value of the left Y-axis
+
+=item $Ydata2: The second data set
+
+=item $Min2: The minimum value of the right Y-axis
+
+=item $Max2: The maximum value of the left Y-axis
+
+=item %Values: hash indicating or overriding any default values which are 
+passed to graph.png.  
+Possible values are: width, xskip, x_ticks, x_tick_offset, among others.
+
+=back
+
+Returns:
+
+An <img> tag which references graph.png and the appropriate identifying
+information for the plot.
+
+=cut
+
+############################################################
+############################################################
+sub DrawXYYGraph {
+    my ($Title,$xlabel,$ylabel,$colors,$Xlabels,$Ydata1,$Min1,$Max1,
+                                        $Ydata2,$Min2,$Max2,%Values)=@_;
     #
     # Create the identifier for the graph
     my $identifier = &get_cgi_id();
@@ -2794,26 +2980,77 @@ sub DrawXYGraph {
          $id.'.title'  => &Apache::lonnet::escape($Title),
          $id.'.xlabel' => &Apache::lonnet::escape($xlabel),
          $id.'.ylabel' => &Apache::lonnet::escape($ylabel),
-         $id.'.Max'    => $Max,
          $id.'.labels' => join(',',@$Xlabels),
          $id.'.PlotType' => 'XY',
          $id.'.NumSets' => 2,
+         $id.'.two_axes' => 1,
+         $id.'.y1_max_value' => $Max1,
+         $id.'.y1_min_value' => $Min1,
+         $id.'.y2_max_value' => $Max2,
+         $id.'.y2_min_value' => $Min2,
          );
     #
-    if (! ref($Ydata) || ref($Ydata) ne 'ARRAY') {
+    if (defined($colors) && ref($colors) eq 'ARRAY') {
+        $ValuesHash{$id.'.Colors'}   = join(',',@{$colors});
+    }
+    #
+    if (! ref($Ydata1) || ref($Ydata1) ne 'ARRAY' ||
+        ! ref($Ydata2) || ref($Ydata2) ne 'ARRAY'){
         return '';
     }
     my $NumSets=1;
-    foreach my $array ($Ydata){
+    foreach my $array ($Ydata1,$Ydata2){
         next if (! ref($array));
         $ValuesHash{$id.'.data.'.$NumSets++} = join(',',@$array);
     }
     #
+    # Deal with other parameters
+    while (my ($key,$value) = each(%Values)) {
+        $ValuesHash{$id.'.'.$key} = $value;
+    }
+    #
     &Apache::lonnet::appenv(%ValuesHash);
     return '<img src="/cgi-bin/graph.png?'.$identifier.'" border="1" />';
 }
 
 ############################################################
+############################################################
+
+=pod
+
+=head1 Statistics helper routines?  
+
+Bad place for them but what the hell.
+
+=item &chartlink
+
+Returns a link to the chart for a specific student.  
+
+Inputs:
+
+=over 4
+
+=item $linktext: The text of the link
+
+=item $sname: The students username
+
+=item $sdomain: The students domain
+
+=back
+
+=cut
+
+############################################################
+############################################################
+sub chartlink {
+    my ($linktext, $sname, $sdomain) = @_;
+    my $link = '<a href="/adm/statistics?reportSelected=student_assessment'.
+        '&SelectedStudent='.&Apache::lonnet::escape($sname.':'.$sdomain).
+        '&chartoutputmode='.HTML::Entities::encode('html, with all links').
+       '">'.$linktext.'</a>';
+}
+
+############################################################
 ############################################################
 
 =pod