--- loncom/interface/lonnavmaps.pm	2003/07/16 19:22:49	1.215
+++ loncom/interface/lonnavmaps.pm	2003/07/17 18:40:49	1.216
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Navigate Maps Handler
 #
-# $Id: lonnavmaps.pm,v 1.215 2003/07/16 19:22:49 bowersj2 Exp $
+# $Id: lonnavmaps.pm,v 1.216 2003/07/17 18:40:49 bowersj2 Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -73,7 +73,7 @@ my %statusIconMap =
       $resObj->INCORRECT          => 'navmap.wrong.gif',
       $resObj->OPEN               => 'navmap.open.gif',
       $resObj->ATTEMPTED          => 'navmap.ellipsis.gif',
-      $resObj->ANSWER_SUBMITTED   => '' );
+      $resObj->ANSWER_SUBMITTED   => 'navmap.ellipsis.gif' );
 
 my %iconAltTags = 
     ( 'navmap.correct.gif' => 'Correct',
@@ -560,18 +560,62 @@ The main handler generates the navigatio
 the other objects export this information in a usable fashion for
 other modules.
 
+=head1 OVERVIEW
+
+When a user enters a course, LON-CAPA examines the course structure
+and caches it in what is often referred to as the "big hash". You
+can see it if you are logged into LON-CAPA, in a course, by going
+to /adm/test. (You may need to tweak the /home/httpd/lonTabs/htpasswd
+file to view it.) The content of the hash will be under the heading
+"Big Hash".
+
+Big Hash contains, among other things, how resources are related
+to each other (next/previous), what resources are maps, which 
+resources are being chosen to not show to the student (for random
+selection), and a lot of other things that can take a lot of time
+to compute due to the amount of data that needs to be collected and
+processed.
+
+Apache::lonnavmaps provides an object model for manipulating this
+information in a higher-level fashion then directly manipulating 
+the hash. It also provides access to several auxilary functions 
+that aren't necessarily stored in the Big Hash, but are a per-
+resource sort of value, like whether there is any feedback on 
+a given resource.
+
+Apache::lonnavmaps also abstracts away branching, and someday, 
+conditions, for the times where you don't really care about those
+things.
+
+Apache::lonnavmaps also provides fairly powerful routines for
+rendering navmaps, and last but not least, provides the navmaps
+view for when the user clicks the NAV button.
+
+B<Note>: Apache::lonnavmaps I<only> works for the "currently
+logged in user"; if you want things like "due dates for another
+student" lonnavmaps can not directly retrieve information like
+that. You need the EXT function. This module can still help,
+because many things, such as the course structure, are constant
+between users, and Apache::lonnavmaps can help by providing
+symbs for the EXT call.
+
+The rest of this file will cover the provided rendering routines, 
+which can often be used without fiddling with the navmap object at
+all, then documents the Apache::lonnavmaps::navmap object, which
+is the key to accessing the Big Hash information, covers the use
+of the Iterator (which provides the logic for traversing the 
+somewhat-complicated Big Hash data structure), documents the
+Apache::lonnavmaps::Resource objects that are returned by 
+
 =head1 Subroutine: render
 
 The navmap renderer package provides a sophisticated rendering of the
 standard navigation maps interface into HTML. The provided nav map
 handler is actually just a glorified call to this.
 
-Because of the large number of parameters this function presents,
+Because of the large number of parameters this function accepts,
 instead of passing it arguments as is normal, pass it in an anonymous
-hash with the given options. This is because there is no obvious order
-you may wish to override these in and a hash is easier to read and
-understand then "undef, undef, undef, 1, undef, undef, renderButton,
-undef, 0" when you mostly want default behaviors.
+hash with the desired options.
 
 The package provides a function called 'render', called as
 Apache::lonnavmaps::render({}).
@@ -599,29 +643,33 @@ that takes a resource reference, a part
 argument hash passed to the renderer, and returns a string that will
 be inserted into the HTML representation as it.
 
+All other parameters are ways of either changing how the columns
+are printing, or which rows are shown.
+
 The pre-packaged column names are refered to by constants in the
 Apache::lonnavmaps namespace. The following currently exist:
 
 =over 4
 
-=item * B<resource>:
+=item * B<Apache::lonnavmaps::resource>:
 
 The general info about the resource: Link, icon for the type, etc. The
-first column in the standard nav map display. This column also accepts
+first column in the standard nav map display. This column provides the
+indentation effect seen in the B<NAV> screen. This column also accepts
 the following parameters in the renderer hash:
 
 =over 4
 
-=item * B<resource_nolink>:
+=item * B<resource_nolink>: default false
 
-If true, the resource will not be linked. Default: false, resource
-will have links.
+If true, the resource will not be linked. By default, all non-folder
+resources are linked.
 
-=item * B<resource_part_count>:
+=item * B<resource_part_count>: default true
 
-If true (default), the resource will show a part count if the full
-part list is not displayed. If false, the resource will never show a
-part count.
+If true, the resource will show a part count B<if> the full
+part list is not displayed. (See "condense_parts" later.) If false,
+the resource will never show a part count.
 
 =item * B<resource_no_folder_link>:
 
@@ -631,19 +679,21 @@ can't close or open folders when this is
 
 =back
 
-=item B<communication_status>:
+=item B<Apache::lonnavmaps::communication_status>:
 
 Whether there is discussion on the resource, email for the user, or
 (lumped in here) perl errors in the execution of the problem. This is
 the second column in the main nav map.
 
-=item B<quick_status>:
+=item B<Apache::lonnavmaps::quick_status>:
 
-An icon for the status of a problem, with four possible states:
-Correct, incorrect, open, or none (not open yet, not a problem). The
+An icon for the status of a problem, with five possible states:
+Correct, incorrect, open, awaiting grading (for a problem where the
+computer's grade is suppressed, or the computer can't grade, like
+essay problem), or none (not open yet, not a problem). The
 third column of the standard navmap.
 
-=item B<long_status>:
+=item B<Apache::lonnavmaps::long_status>:
 
 A text readout of the details of the current status of the problem,
 such as "Due in 22 hours". The fourth column of the standard navmap.
@@ -677,7 +727,7 @@ automatically.
 
 =over 4
 
-=item * B<iterator>:
+=item * B<iterator>: default: constructs one from %ENV
 
 A reference to a fresh ::iterator to use from the navmaps. The
 rendering will reflect the options passed to the iterator, so you can
@@ -686,106 +736,106 @@ one is not passed, the renderer will att
 ENV{'form.filter'} and ENV{'form.condition'} information, plus the
 'iterator_map' parameter if any.
 
-=item * B<iterator_map>:
+=item * B<iterator_map>: default: not used
 
 If you are letting the renderer do the iterator handling, you can
 instruct the renderer to render only a particular map by passing it
 the source of the map you want to process, like
 '/res/103/jerf/navmap.course.sequence'.
 
-=item * B<navmap>:
+=item * B<navmap>: default: constructs one from %ENV
 
 A reference to a navmap, used only if an iterator is not passed in. If
 this is necessary to make an iterator but it is not passed in, a new
 one will be constructed based on ENV info. This is useful to do basic
 error checking before passing it off to render.
 
-=item * B<r>:
+=item * B<r>: default: must be passed in
 
 The standard Apache response object. This must be passed to the
 renderer or the course hash will be locked.
 
-=item * B<cols>:
+=item * B<cols>: default: empty (useless)
 
 An array reference
 
-=item * B<showParts>:
+=item * B<showParts>:default true
 
-A flag. If yes (default), a line for the resource itself, and a line
+A flag. If true, a line for the resource itself, and a line
 for each part will be displayed. If not, only one line for each
 resource will be displayed.
 
-=item * B<condenseParts>:
+=item * B<condenseParts>: default true
 
-A flag. If yes (default), if all parts of the problem have the same
+A flag. If true, if all parts of the problem have the same
 status and that status is Nothing Set, Correct, or Network Failure,
 then only one line will be displayed for that resource anyhow. If no,
 all parts will always be displayed. If showParts is 0, this is
 ignored.
 
-=item * B<jumpCount>:
+=item * B<jumpCount>: default: determined from %ENV
 
-A string identifying the URL to place the anchor 'curloc' at. Default
-to no anchor at all. It is the responsibility of the renderer user to
+A string identifying the URL to place the anchor 'curloc' at.
+It is the responsibility of the renderer user to
 ensure that the #curloc is in the URL. By default, determined through
 the use of the ENV{} 'jump' information, and should normally "just
 work" correctly.
 
-=item * B<here>:
+=item * B<here>: default: empty string
 
-A Symb identifying where to place the 'here' marker. Default empty,
-which means no marker.
+A Symb identifying where to place the 'here' marker. The empty
+string means no marker.
 
-=item * B<indentString>:
+=item * B<indentString>: default: 25 pixel whitespace image
 
-A string identifying the indentation string to use. By default, this
-is a 25 pixel whitespace image with no alt text.
+A string identifying the indentation string to use. 
 
-=item * B<queryString>:
+=item * B<queryString>: default: empty
 
 A string which will be prepended to the query string used when the
-folders are opened or closed.
+folders are opened or closed. You can use this to pass
+application-specific values.
 
-=item * B<url>:
+=item * B<url>: default: none
 
 The url the folders will link to, which should be the current
-page. Required if the resource info column is shown.
+page. Required if the resource info column is shown, and you 
+are allowing the user to open and close folders.
 
-=item * B<currentJumpIndex>:
+=item * B<currentJumpIndex>: default: no jumping
 
 Describes the currently-open row number to cause the browser to jump
 to, because the user just opened that folder. By default, pulled from
 the Jump information in the ENV{'form.*'}.
 
-=item * B<printKey>:
+=item * B<printKey>: default: false
 
 If true, print the key that appears on the top of the standard
-navmaps. Default is false.
+navmaps.
 
-=item * B<printCloseAll>:
+=item * B<printCloseAll>: default: true
 
 If true, print the "Close all folders" or "open all folders"
-links. Default is true.
+links.
 
-=item * B<filterFunc>:
+=item * B<filterFunc>: default: sub {return 1;} (accept everything)
 
 A function that takes the resource object as its only parameter and
 returns a true or false value. If true, the resource is displayed. If
-false, it is simply skipped in the display. By default, all resources
-are shown.
+false, it is simply skipped in the display.
 
-=item * B<suppressEmptySequences>:
+=item * B<suppressEmptySequences>: default: false
 
 If you're using a filter function, and displaying sequences to orient
 the user, then frequently some sequences will be empty. Setting this to
 true will cause those sequences not to display, so as not to confuse the
 user into thinking that if the sequence is there there should be things
-under it.
+under it; for example, see the "Show Uncompleted Homework" view on the
+B<NAV> screen.
 
-=item * B<suppressNavmaps>:
+=item * B<suppressNavmaps>: default: false
 
-If true, will not display Navigate Content resources. Default to
-false.
+If true, will not display Navigate Content resources. 
 
 =back
 
@@ -796,13 +846,19 @@ be passed through unchange to the column
 generate the following information which your renderer may find
 useful:
 
-If you want to know how many rows were printed, the 'counter' element
-of the hash passed into the render function will contain the
-count. You may want to check whether any resources were printed at
-all.
-
 =over 4
 
+=item * B<counter>: 
+
+Contains the number of rows printed. Useful after calling the render 
+function, as you can detect whether anything was printed at all.
+
+=item * B<isNewBranch>:
+
+Useful for renderers: If this resource is currently the first resource
+of a new branch, this will be true. The Resource column (leftmost in the
+navmaps screen) uses this to display the "new branch" icon 
+
 =back
 
 =cut
@@ -1547,25 +1603,11 @@ package Apache::lonnavmaps::navmap;
 
 =pod
 
-lonnavmaps provides functions and objects for dealing with the
-compiled course hashes generated when a user enters the course, the
-Apache handler for the "Navigation Map" button, and a flexible
-prepared renderer for navigation maps that are easy to use anywhere.
-
-=head1 Object: navmap
-
-Encapsulating the compiled nav map
-
-navmap is an object that encapsulates a compiled course map and
-provides a reasonable interface to it.
-
-Most notably it provides a way to navigate the map sensibly and a
-flexible iterator that makes it easy to write various renderers based
-on nav maps.
+=head1 Object: Apache::lonnavmaps::navmap
 
 You must obtain resource objects through the navmap object.
 
-=head2 Methods
+=head2 Creation
 
 =over 4
 
@@ -1584,6 +1626,12 @@ B<undef> if not. You must check for unde
 try to use the other methods otherwise. getUserData, if true, will 
 retreive the user's performance data for various problems.
 
+=back
+
+=head2 Methods
+
+=over 4
+
 =item * B<getIterator>(first, finish, filter, condition):
 
 See iterator documentation below.
@@ -3853,15 +3901,18 @@ sub completable {
         # "If any of the parts are open, or have tries left (implies open),
         # and it is not "attempted" (manually graded problem), it is
         # not "complete"
-        if (!(($status == OPEN() || $status == TRIES_LEFT()) 
-              && $self->getCompletionStatus($part) != ATTEMPTED()
-              && $status != ANSWER_SUBMITTED())) {
-            return 0;
-        }
+	if ($self->getCompletionStatus($part) == ATTEMPTED() ||
+	    $status == ANSWER_SUBMITTED() ) {
+	    # did this part already, as well as we can
+	    next;
+	}
+	if ($status == OPEN() || $status == TRIES_LEFT()) {
+	    return 1;
+	}
     }
         
     # If all the parts were complete, so was this problem.
-    return 1;
+    return 0;
 }
 
 =pod