--- loncom/interface/loncommon.pm	2003/10/29 15:21:10	1.137
+++ loncom/interface/loncommon.pm	2003/10/29 15:47:52	1.138
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # a pile of common routines
 #
-# $Id: loncommon.pm,v 1.137 2003/10/29 15:21:10 matthew Exp $
+# $Id: loncommon.pm,v 1.138 2003/10/29 15:47:52 matthew Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -2678,6 +2678,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 +2711,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.
+
+=teim $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
 
 ############################################################
@@ -2774,6 +2827,42 @@ 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
 
 ############################################################
@@ -2796,7 +2885,6 @@ sub DrawXYGraph {
          $id.'.y_max_value'=> $Max,
          $id.'.labels'     => join(',',@$Xlabels),
          $id.'.PlotType'   => 'XY',
-         $id.'.NumSets'    => 1,
          );
     #
     if (defined($colors) && ref($colors) eq 'ARRAY') {
@@ -2807,10 +2895,11 @@ sub DrawXYGraph {
         return '';
     }
     my $NumSets=1;
-    foreach my $array ($Ydata){
+    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)) {
@@ -2821,13 +2910,54 @@ sub DrawXYGraph {
     return '<img src="/cgi-bin/graph.png?'.$identifier.'" border="1" />';
 }
 
-
 ############################################################
 ############################################################
 
 =pod
 
-=item DrawXYGraph
+=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