--- loncom/enrollment/localenroll.pm	2015/05/30 16:14:38	1.51
+++ loncom/enrollment/localenroll.pm	2015/05/30 18:01:12	1.52
@@ -1,6 +1,6 @@
 # functions to glue school database system into Lon-CAPA for 
 # automated enrollment
-# $Id: localenroll.pm,v 1.51 2015/05/30 16:14:38 raeburn Exp $
+# $Id: localenroll.pm,v 1.52 2015/05/30 18:01:12 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -369,21 +369,27 @@ validate_crsreq takes seven arguments -
  (f) a comma-separated list of institutional sections included in
      the course request (only applicable to official courses).
  (g) an optional reference to a hash of custom form data.
-     The custom form data will come from crsreq_updates().
+     The custom form data will come from crsreq_updates(), with one
+     additional item: $custominfo->{'_LC_clonefrom'}, provided internally
+     (the courseID of the LON-CAPA course being cloned).
 
 A valid courserequest is confirmed by returning 'process'.
 The following can be returned: process, rejected, pending, approval or 
 error (with error condition - no :), followed by a : and then an optional message. 
 
 (a) process  - the requestor is the recorded instructor - create the course
+
 (b) rejected - the requestor should never be requesting this course, reject the
     request permanently
+
 (c) pending - the requestor is not the recorded instructor, but could
     become so after administrative action at the institution. Put the
     request in a queue and, if an official course, check 
     localenroll:validate_instcode() periodically until the status changes to 
     "valid".
+
 (d) approval - the request will be held pending review by a Domain Coordinator.
+
 (e) error (followed by the error condition).
 
 =cut
@@ -444,6 +450,42 @@ sub crsreq_checks {
     return 'ok';
 }
 
+=pod
+
+=item crsreq_updates()
+
+This is used to customize the LON-CAPA course request process.
+There are two hash references: $incoming, and $outgoing; $incoming can
+contain additional information collected from the requester, whereas $outgoing
+can contain custom items to send back to lonrequestcourse.pm, which creates the
+HTML displayed to the user during a course request.
+
+Different key-value pairs may be returned to lonrequestcourse.pm in the $outgoing
+hashref depending on the current action.  The available actions are:
+review, prevalidate, process, created and queued.
+
+One scenario would be to return HTML markup in: $outgoing->{'reviewweb'},
+i.e., where the action is 'review', to prompt the user to provide additional
+information as part of the course request, at the request review stage, 
+(i.e,, the page which contains the button used to submit a completed course request).
+
+The HTML could contain form elements (e.g., radio buttons etc.). The value(s)
+selected by the requester in those form elements will be available in the incoming
+hashref, for a subsequent action, if the corresponding keys have been included
+in $outgoing->{'formitems'}, i.e., $outgoing will be hash of a hash.  If a
+particular form item will the single valued, the value set for the key in the 
+inner hash in $outgoing should be 1, otherwise, if it will be multi-valued,
+the value should be multiple.
+
+The $outgoing hashref can contain a 'formitems' key for both the prevalidate
+and process actions, as calls to localenroll::crsreq_update() can originate
+in lonrequestcourse::process_request() for both of those actions.
+
+The retrieved form values are passed to localenroll::validate_crsreq() as the
+optional seventh arg (a hashref) -- $custominfo.
+
+=cut
+
 sub crsreq_updates {
     my ($cdom,$cnum,$crstype,$action,$ownername,$ownerdomain,$fullname,$title,
         $code,$accessstart,$accessend,$incoming,$outgoing) = @_;