--- loncom/interface/lonhelper.pm	2010/01/12 10:40:01	1.177
+++ loncom/interface/lonhelper.pm	2010/01/26 11:34:47	1.178
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # .helper XML handler to implement the LON-CAPA helper
 #
-# $Id: lonhelper.pm,v 1.177 2010/01/12 10:40:01 foxr Exp $
+# $Id: lonhelper.pm,v 1.178 2010/01/26 11:34:47 foxr Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -2066,6 +2066,49 @@ the toplevel default.sequence in the res
   evaluated with "sub { my $helper = shift; my $state = shift;" and
   "}", with the return value used as the mapurl.
 
+=item * <option />: Allows you to add optional elements to the
+  resource chooser currently these can be a checkbox, or a text entry
+  or hidden (see the 'type' attribute below).
+  the following attributes are supported by this tag:
+
+=over 4
+
+=item * type=control-type : determines the type of control displayed.
+  This can be one of the following types: 'checkbox' provides a true/false
+  checkbox.  'text' provides a text entry control. 'hidden' provides a
+  hidden form element that returns the name of the resource for each
+  element of the text box.
+
+=item * text=header-text : provides column header text for the option.
+  
+=item * variable=helpervar : provides a helper variable to contain the
+  value of the input control for each resource.  In general, the result
+  will be a set of values separated by |||  for the checkbox the value between
+  the |||'s will either be empty, if the box is not checked, or the resource
+  name if checked.  For the text entry, the values will be the text in the
+  text box.  This could be empty.  Hidden elements unconditionally provide
+  the resource name for each row of the chooser and allow you to therefore
+  correlate text entries to their resources.
+  The helper variable can be initialized by the user code to pre-load values
+  into the controls:
+
+=over 4
+
+  
+=item * Preloading checkboxes : Set the helper variable to the value you
+   would have gotten from the control if it had been manually set as desired.
+
+=item * Preloading text entries : Set the helper variable to triple pipe
+   separated values where each value is of the form resource-name=value
+
+=item * Preloading hidden fields : These cannot be pre-loaded and will always
+  be pipe separated resource names.
+
+=back
+
+
+=back
+
 =back
 
 =cut
@@ -2395,6 +2438,8 @@ BUTTONS
 				last;
 			    }
 			}
+			# TODO: add an attribute to <option> that allows the
+			#       programmer to set the width of the tex entry box.
 
 			$col .=
 			    "<td align='center'><input type='text' name ='$option_var".