--- doc/homework/homework5.html	2001/12/07 15:05:03	1.12
+++ doc/homework/homework5.html	2002/07/17 18:08:38	1.19
@@ -57,6 +57,11 @@
 	    </ul>
 	  </li>
 	  <li>
+	    <b>&lt;parameter&gt;</b> exactly the same as
+	    &lt;responseparam&gt; currently, but should not appear
+	    inside of a &lt;*response&gt;
+	  </li>
+	  <li>
 	    <b>&lt;numericalresponse&gt;</b> implements a numerical
 	    answer, it needs an internal <b>&lt;textline&gt;</b> for
 	    the response to go in. It checks all styles of numerical
@@ -83,7 +88,7 @@
 	    </ul>
 	  <li>
 	    <b>&lt;essayresponse&gt;</b> implements a ungraded large
-	    text response, it need an internal <b>&lt;textarea&gt;</b>
+	    text response, it need an internal <b>&lt;textfield&gt;</b>
 	    for the response to go in.
 	  </li>
 	  <li>
@@ -142,7 +147,59 @@
 		the field when interfacing with humans
 	      </li>
 	    </ul>
+	  </li>
 	  <li>
+	    <p>
+	      <b>&lt;externalresponse&gt;</b> implements the ability to have
+	      an external program grade a response, expects either a
+	      &lt;textline&gt; or &lt;textfield&gt; inside the tag. <br />
+	    </p>
+	    Arguments:
+	    <ul>
+	      <li>
+		<i>url</i> the url to submit the answer and form to,
+		does not need to be a LON-CAPA machine.
+	      </li>
+	      <li>
+		<i>answer</i> a string or scalar variable that can
+		encode something that should encode the correct
+		answer, in some cases this may be nothing.
+	      </li>
+	      <li>
+		<i>form</i> a hash variable name that will be
+		submitted to the remote site as a HTTP form.
+	      </li>
+	    </ul>
+	    <p>
+	      The response of the remote server needs to be in XML as follows.
+	    </p>
+	    <pre>
+&lt;loncapagrade&gt;
+    &lt;awardetail&gt;
+CORRECT
+    &lt;/awardetail&gt;
+    &lt;message&gt;
+A message to be shown to the students
+    &lt;/message&gt;
+&lt;/loncapagrade&gt;
+	    </pre>
+	    <ul>
+	      <li>
+		<b>&lt;loncapagrade&gt;</b> no arguments but must
+		surround the response.
+	      </li>
+	      <li>
+		<b>&lt;awardetail&gt;</b> required inner tag, the
+		response inside must be one of the detailed responses
+		that appears in the data storage documentation
+		(CVS:loncapa/doce/homework/datastorage)
+	      </li>
+	      <li>
+		<b>&lt;message&gt;</b> optional message to have shown
+		to the student
+	      </li>
+	    </ul>
+	  </li>
 	</ul>
 	<li>
 	<a name="foil">Foil Structure Tags</a>
@@ -203,9 +260,9 @@
 	</p>
 	<ul>
 	  <li>
-	    <b>&lt;textarea&gt;</b> creates a Large text input box, If
+	    <b>&lt;textfield&gt;</b> creates a Large text input box, If
 	    data appears between the start and end tags, the data will
-	    appear i the textarea if the student has not yet made a
+	    appear in the textfield if the student has not yet made a
 	    submission. Additionally it takes two arguments <i>rows</i>
 	    and <i>cols</i> which control the height and width of the
 	    area respectively. It defaults to 10 and 80.
@@ -224,6 +281,11 @@
 	</p>
 	<ul>
 	  <li>
+	    <b>&lt;standalone&gt;</b> everything in between the start
+	    and end tag is shown only on the web, and only if the
+	    resource is not part of a course.
+	  </li>
+	  <li>
 	    <b>&lt;displayduedate&gt;</b> this will insert the current
 	    duedate if one is set into the document. It is generated
 	    to be inside a table of 1x1 elements
@@ -242,15 +304,123 @@
 	    <i>eval</i> is set to "on" the intervening text will have
 	    a perl var expansion done to it before being converted.
 	  </li>
+	  <li>
+	    <b>&lt;randomlabel&gt;</b> shows a specified image with
+	    images or text labels randomly assigned to a set of
+	    specific locations, those locations may also have values
+	    assigned to them. There is a hash generated conating the
+	    mapping of labels to locations, labels to values, and
+	    locations to values. Example:
+	    <pre>
+ &lt;randomlabel bgimg=&quot;URL&quot; width=&quot;12&quot; height=&quot;45&quot; texwidth=&quot;50&quot;&gt;
+    &lt;labelgroup name=&quot;GroupOne&quot; type=&quot;image&quot;&gt;
+      &lt;location x=&quot;123&quot; y=&quot;456&quot; value=&quot;10&quot; /&gt;
+      &lt;location x=&quot;321&quot; y=&quot;654&quot; value=&quot;20&quot; /&gt;
+      &lt;location x=&quot;213&quot; y=&quot;546&quot; value=&quot;13&quot; /&gt;
+      &lt;label description=&quot;TEXT-1&quot;&gt;IMG-URL&lt;/label&gt;
+      &lt;label description=&quot;TEXT-2&quot;&gt;IMG-URL&lt;/label&gt;
+      &lt;label description=&quot;TEXT-3&quot;&gt;IMG-URL&lt;/label&gt;
+    &lt;/labelgroup&gt;
+    &lt;labelgroup name=&quot;GroupTwo&quot; type=&quot;text&quot;&gt;
+      &lt;location x=&quot;12&quot; y=&quot;45&quot; /&gt;
+      &lt;location x=&quot;32&quot; y=&quot;65&quot; /&gt;
+      &lt;location x=&quot;21&quot; y=&quot;54&quot; /&gt;
+      &lt;label&gt;TEXT-1&lt;/label&gt;
+      &lt;label&gt;TEXT-2&lt;/label&gt;
+      &lt;label&gt;TEXT-3&lt;/label&gt;
+    &lt;/labelgroup&gt;
+   &lt;/randomlabel&gt;
+	    </pre>
+	    Arguments:
+	    <ul>
+	      <li>
+		<i>bgimg</i> either a fully qualified URL for an
+		external image, or a loncapa resource, it supports
+		relative references (../images/apicture.gif), the
+		image must either be a GIF or JPEG
+	      </li>
+	      <li>
+		<i>width</i> the width of the image in pixels
+	      </li>
+	      <li>
+		<i>height</i> the height of the image in pixels
+	      </li>
+	      <li>
+		<i>texwidth</i> the width of the image in millimeters
+	      </li>
+	    </ul>
+	    Internal tags:
+	    <ul>
+	      <li>
+		<b>&lt;labelgroup&gt;</b> 1 required, multiple
+		allowed. Declares a group of locations and labels
+		associated with them.  <br />Arguments:
+		<ul>
+		  <li>
+		    <i>name</i> this is the name of the group, a hash
+		    with this name will be generated holding the
+		    mappings for later use in the problem. For each
+		    location a value will be set for which label is
+		    there, (EX. $hash{'1'}="TEXT-2"). For locations
+		    with values the hash will contain 2 items, a
+		    location to value mapping ($hash{'value_1'}=10),
+		    and a label to value mapping
+		    ($hash{'labelvalue_2'}=10). For all image style of
+		    labels there will also be a label description to
+		    label URL mapping ($hash{'image_2'}=IMG-URL). Also
+		    the entry 'numlocations will be set to the total
+		    number of locations that exist.
+		    (Note that locations and labels start counting from 1.)
+		  </li>
+		  <li>
+		    <i>type</i> the type of labels in this group,
+		    either 'image' or 'text'
+		  </li>
+		</ul>
+	      </li>
+	      <li>
+		<b>&lt;location&gt;</b> declares a location on the
+		image that a label should appear at <br />Arguments:
+		<ul>
+		  <li>
+		    <i>x</i> the x value of the location in pixels 
+		  </li>
+		  <li>
+		    <i>y</i> the y value of the location in pixels 
+		  </li>
+		  <li>
+		    <i>value</i> a scalar value to associate at this
+		    location (optional)
+		  </li>
+		</ul>
+	      </li>
+	      <li>
+		<b>&lt;label&gt;</b> declaration of a label, if this
+		is a text type labelgroup the internal text should be
+		the text of the label (HTML is not currently
+		supported), if this is an image type of label the
+		internal text must be a LON-CAPA resource
+		specification, and the description filed must be set.
+		<br />Arguments:
+		<ul>
+		  <li>
+		    <i>description</i> a required field for image
+		    labels, it will be used when setting values in the
+		    hash.
+		  </li>
+		</ul>
+	      </li>
+	    </ul>
+	  </li>
 	</ul>
       </li>
       <li>
 	Scripting
-	<p>
-	  These tags allow the document to behave programatically
-	</p>
-	<ul>
-	  <li>
+      <p>
+	These tags allow the document to behave programatically
+      </p>
+      <ul>
+	<li>
 	    <b>&lt;display&gt;</b> the intervening perl script is
 	    evaluated in the safe space and the return value of the
 	    script replaces the entire tag
@@ -294,7 +464,9 @@
 	  </li>
 	  <li>
 	    <b>&lt;randomlist&gt;</b> the enclosed tags are parsed in
-	    a stable random order
+	    a stable random order, optional argument <i>show</i>
+	    restricts the number of tags indie that are actually
+	    parsed the no more than <i>show</i>.
 	  </li>
 	  <li>
 	    <b>&lt;solved&gt;</b> everything inside the tag is
@@ -335,6 +507,12 @@
 	    the web editor knows what sections should be edited in a
 	    plain text block on the web.
 	  </li>
+	  <li>
+	    <b>&lt;comment&gt;</b> Allows one to comment out sections
+	    of code in a balanced manner, or to provide a comment
+	    description of how a problem works. Only shows up for the
+	    edit target, stripped out for all other targets.
+	  </li>
 	</ul>
       </li>
     </ul>
@@ -371,7 +549,7 @@
       <li>open_date(), due_date(), answer_date()</li>
       <li>sub_string()</li>
       <li>array_moments(array)</li>
-      <li>format(x,y)</li>
+      <li>format(x,y),prettyprint(x,y)</li>
       <li>map(...)</li>
       <li>caparesponse_check</li>
       <li>caparesponse_check_list</li>
@@ -493,11 +671,24 @@
     <tr>
              <td valign="top">/DIS($x,"nn")</td>
              <td valign="top">&amp;format($x,"nn")</td>
-             <td valign="top">Display or format $x as nn where nn is nF or nE and n is an integer.</td>
+             <td valign="top">Display or format $x as nn where nn is nF or nE and n is an integer. Also supports the first character being a $, it thjen will format the result with a call to &dollarformat() described below.</td>
              <td valign="top">&nbsp;The difference is obvious.</td>
     </tr>
 
     <tr>
+             <td valign="top">Not in CAPA</td>
+             <td valign="top">&amp;prettyprint($x,"nn")</td>
+             <td valign="top">Display or format $x as nn where nn is nF or nE and n is an integer. Also supports the first character being a $, it then will format the result with a a call to &dollarformat() described below. In E mode it will attempt to generate a pretty x10^3 rather than a E3 following the number</td>
+             <td valign="top">&nbsp;</td>
+    </tr>
+
+    <tr>
+             <td valign="top">Not in CAPA</td>
+             <td valign="top">&amp;dollarformat($x</td>
+             <td valign="top">Reformats $x to have a $ (or \$ if in tex mode) and to have , grouping thousands.</td>
+             <td valign="top">&nbsp;</td>
+    </tr>
+    <tr>
              <td valign="top">roundto(x,n)</td>
              <td valign="top">&amp;roundto($x,$n)</td>
              <td valign="top">Rounds a real number to n decimal points. $x and
@@ -883,7 +1074,7 @@
       </li>
       <li>
 	$external::part - set to the <i>id</i> of the current problem
-	&lt;part&gt;; zero if there are now &lt;part&gt;
+	&lt;part&gt;; zero if there are no &lt;part&gt;
       </li>
       <li>
 	$external::gradestatus - set to the value of the current
@@ -891,7 +1082,7 @@
       </li>
       <li>
 	$external::datestatus - set to the current status of the clock
-	either CLOSED, CAN_ANSWER, CANNOT_ANSWER, or SHOW_ANSWER
+	either CLOSED, CAN_ANSWER, CANNOT_ANSWER, SHOW_ANSWER, or UNCHECKEDOUT
       </li>
       <li>
 	$external::randomseed - set to the number that was used to
@@ -901,12 +1092,74 @@
       <li>$rad2deg - converts radians to degrees </li>
       <li>$deg2rad - converts degrees to radians </li>
     </ul>
-    
+
+    <h2> Form internals </h2>
+    <p> Form elements used for homework editing/response </p>
+    <p> the form is named lonhomework </p>
+    <h3> Viewing a problem (either CSTR or RES space)</h3>
+    <ul>
+      <li>
+	grade_target, grade_username, grade_domain, grade_symb - the
+	vaules take precedence over the the normal ENV settings of
+	these, use &Apache::lonxml::whichuser() to get back the
+	correct vaues of the items
+      </li>
+      <li>
+	HWVAL_response:number - the name of the input elements for each response. The response is the response's ID, and the :number part exists only for response with multiple foils, and is a unique number in order of the submission
+      </li>
+      <li>
+	changerandseed - the 'Change' button, only exists right after
+	the Change button is clicked
+      </li>
+      <li>
+	problemmode - in CSTR, it is either 'View','Edit','EditXML' or
+	'Analyze' depending on the desired view
+      </li>
+      <li>
+	rndseed - the currently requested random seed
+      </li>
+      <li>
+	showallfoils - if it exists, and we are in CSTR space, the
+	problem should ignore &lt;conceptgroup&gt; and the response's
+	max setting and show all possible foils
+      </li>
+      <li>
+	submit - the name of the Submit button
+      </li>
+      <li>
+	submitted - a hidden form parameter that can be used to tell
+	if the student has submitted answers or not, if it is set,
+	there should be answers to grade.
+      </li>
+    </ul>
+    <h3> Editing a problem (Edit mode)</h3>
+    <p> tagdepth referes to the current value of the xmlparsers tagdepth couter ($Apache::lonxml::currentdepth)</p>
+<p> Note: the file edit.pm has many helper functions for creating the standard elements for editing a tag and it's attributes, all of those functions follow these conventions </p>
+    <ul>
+      <li>
+	tagdepth_argname - I.E. 1_3.max, a parameter editing value,
+	max is the name of the parameter and it is for the third tag
+	inside the first tag
+      </li>
+      <li>
+	delete_tagdepth - if set to yes, delete tag tagdepth and all
+	tags inside of it
+      </li>
+      <li>
+	homework_edit_tagdepth - used by both &Apache::edit::editline
+	and &Apache::edit::editfield for the &lt;textarea&gt; and
+	&lt;input&gt; form elements they create
+      </li>
+      <li>
+	insert_tagdepth - used to request an tag insert, it is set to
+	the id number of the requested tag in the
+	%Apache::lonxml::insertlist
+    </ul>
     <hr>
     <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
 <!-- Created: Thu May 17 15:05:35 EDT 2001 -->
 <!-- hhmts start -->
-Last modified: Fri Dec  7 10:03:55 EST 2001
+Last modified: Fri Jul 12 21:28:44 EDT 2002
 <!-- hhmts end -->
   </body>
 </html>