File:  [LON-CAPA] / loncom / interface / lonnavmaps.pm
Revision 1.256: download - view: text, annotated - select for diffs
Wed Mar 24 22:22:04 2004 UTC (20 years, 2 months ago) by albertel
Branches: MAIN
CVS tags: HEAD
- add the ability to have .pages summarized
- Make it so that you can choose to print a page or not print a page, don't allow people to pick and choose resources gfrom inside of a .page
- BUG#2851,

    1: # The LearningOnline Network with CAPA
    2: # Navigate Maps Handler
    3: #
    4: # $Id: lonnavmaps.pm,v 1.256 2004/03/24 22:22:04 albertel Exp $
    5: #
    6: # Copyright Michigan State University Board of Trustees
    7: #
    8: # This file is part of the LearningOnline Network with CAPA (LON-CAPA).
    9: #
   10: # LON-CAPA is free software; you can redistribute it and/or modify
   11: # it under the terms of the GNU General Public License as published by
   12: # the Free Software Foundation; either version 2 of the License, or
   13: # (at your option) any later version.
   14: #
   15: # LON-CAPA is distributed in the hope that it will be useful,
   16: # but WITHOUT ANY WARRANTY; without even the implied warranty of
   17: # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   18: # GNU General Public License for more details.
   19: #
   20: # You should have received a copy of the GNU General Public License
   21: # along with LON-CAPA; if not, write to the Free Software
   22: # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   23: #
   24: # /home/httpd/html/adm/gpl.txt
   25: #
   26: # http://www.lon-capa.org/
   27: #
   28: ###
   29: 
   30: package Apache::lonnavmaps;
   31: 
   32: use strict;
   33: use Apache::Constants qw(:common :http);
   34: use Apache::loncommon();
   35: use Apache::lonmenu();
   36: use Apache::lonlocal;
   37: use POSIX qw (floor strftime);
   38: use Data::Dumper; # for debugging, not always used
   39: 
   40: # symbolic constants
   41: sub SYMB { return 1; }
   42: sub URL { return 2; }
   43: sub NOTHING { return 3; }
   44: 
   45: # Some data
   46: 
   47: my $resObj = "Apache::lonnavmaps::resource";
   48: 
   49: # Keep these mappings in sync with lonquickgrades, which uses the colors
   50: # instead of the icons.
   51: my %statusIconMap = 
   52:     (
   53:      $resObj->CLOSED       => '',
   54:      $resObj->OPEN         => 'navmap.open.gif',
   55:      $resObj->CORRECT      => 'navmap.correct.gif',
   56:      $resObj->INCORRECT    => 'navmap.wrong.gif',
   57:      $resObj->ATTEMPTED    => 'navmap.ellipsis.gif',
   58:      $resObj->ERROR        => ''
   59:      );
   60: 
   61: my %iconAltTags = 
   62:     ( 'navmap.correct.gif' => 'Correct',
   63:       'navmap.wrong.gif'   => 'Incorrect',
   64:       'navmap.open.gif'    => 'Open' );
   65: 
   66: # Defines a status->color mapping, null string means don't color
   67: my %colormap = 
   68:     ( $resObj->NETWORK_FAILURE        => '',
   69:       $resObj->CORRECT                => '',
   70:       $resObj->EXCUSED                => '#3333FF',
   71:       $resObj->PAST_DUE_ANSWER_LATER  => '',
   72:       $resObj->PAST_DUE_NO_ANSWER     => '',
   73:       $resObj->ANSWER_OPEN            => '#006600',
   74:       $resObj->OPEN_LATER             => '',
   75:       $resObj->TRIES_LEFT             => '',
   76:       $resObj->INCORRECT              => '',
   77:       $resObj->OPEN                   => '',
   78:       $resObj->NOTHING_SET            => '',
   79:       $resObj->ATTEMPTED              => '',
   80:       $resObj->ANSWER_SUBMITTED       => ''
   81:       );
   82: # And a special case in the nav map; what to do when the assignment
   83: # is not yet done and due in less then 24 hours
   84: my $hurryUpColor = "#FF0000";
   85: 
   86: sub handler {
   87:     my $r = shift;
   88:     real_handler($r);
   89: }
   90: 
   91: sub real_handler {
   92:     my $r = shift;
   93: 
   94:     # Handle header-only request
   95:     if ($r->header_only) {
   96:         if ($ENV{'browser.mathml'}) {
   97:             &Apache::loncommon::content_type($r,'text/xml');
   98:         } else {
   99:             &Apache::loncommon::content_type($r,'text/html');
  100:         }
  101:         $r->send_http_header;
  102:         return OK;
  103:     }
  104: 
  105:     # Send header, don't cache this page
  106:     if ($ENV{'browser.mathml'}) {
  107:         &Apache::loncommon::content_type($r,'text/xml');
  108:     } else {
  109:         &Apache::loncommon::content_type($r,'text/html');
  110:     }
  111:     &Apache::loncommon::no_cache($r);
  112:     $r->send_http_header;
  113: 
  114:     # Create the nav map
  115:     my $navmap = Apache::lonnavmaps::navmap->new();
  116: 
  117:     if (!defined($navmap)) {
  118:         my $requrl = $r->uri;
  119:         $ENV{'user.error.msg'} = "$requrl:bre:0:0:Course not initialized";
  120:         return HTTP_NOT_ACCEPTABLE;
  121:     }
  122: 
  123:     $r->print("<html><head>\n");
  124:     $r->print("<title>".&mt('Navigate Course Contents')."</title>");
  125: # ------------------------------------------------------------ Get query string
  126:     &Apache::loncommon::get_unprocessed_cgi($ENV{'QUERY_STRING'},['register']);
  127:     
  128: # ----------------------------------------------------- Force menu registration
  129:     my $addentries='';
  130:     if ($ENV{'form.register'}) {
  131:        $addentries=' onLoad="'.&Apache::lonmenu::loadevents().
  132: 	   '" onUnload="'.&Apache::lonmenu::unloadevents().'"';
  133:        $r->print(&Apache::lonmenu::registerurl(1));
  134:     }
  135: 
  136:     # Header
  137:     $r->print('</head>'.
  138:               &Apache::loncommon::bodytag('Navigate Course Contents','',
  139:                                     $addentries,'','',$ENV{'form.register'}));
  140:     $r->print('<script>window.focus();</script>');
  141: 
  142:     $r->rflush();
  143: 
  144:     # Check that it's defined
  145:     if (!($navmap->courseMapDefined())) {
  146:         $r->print('<font size="+2" color="red">Coursemap undefined.</font>' .
  147:                   '</body></html>');
  148:         return OK;
  149:     }
  150: 
  151:     # See if there's only one map in the top-level, if we don't
  152:     # already have a filter... if so, automatically display it
  153:     # (older code; should use retrieveResources)
  154:     if ($ENV{QUERY_STRING} !~ /filter/) {
  155:         my $iterator = $navmap->getIterator(undef, undef, undef, 0);
  156:         my $curRes;
  157:         my $sequenceCount = 0;
  158:         my $sequenceId;
  159:         while ($curRes = $iterator->next()) {
  160:             if (ref($curRes) && $curRes->is_sequence()) {
  161:                 $sequenceCount++;
  162:                 $sequenceId = $curRes->map_pc();
  163:             }
  164:         }
  165:         
  166:         if ($sequenceCount == 1) {
  167:             # The automatic iterator creation in the render call 
  168:             # will pick this up. We know the condition because
  169:             # the defined($ENV{'form.filter'}) also ensures this
  170:             # is a fresh call.
  171:             $ENV{'form.filter'} = "$sequenceId";
  172:         }
  173:     }
  174: 
  175:     my $jumpToFirstHomework = 0;
  176:     # Check to see if the student is jumping to next open, do-able problem
  177:     if ($ENV{QUERY_STRING} eq 'jumpToFirstHomework') {
  178:         $jumpToFirstHomework = 1;
  179:         # Find the next homework problem that they can do.
  180:         my $iterator = $navmap->getIterator(undef, undef, undef, 1);
  181:         my $curRes;
  182:         my $foundDoableProblem = 0;
  183:         my $problemRes;
  184:         
  185:         while (($curRes = $iterator->next()) && !$foundDoableProblem) {
  186:             if (ref($curRes) && $curRes->is_problem()) {
  187:                 my $status = $curRes->status();
  188:                 if ($curRes->completable()) {
  189:                     $problemRes = $curRes;
  190:                     $foundDoableProblem = 1;
  191: 
  192:                     # Pop open all previous maps
  193:                     my $stack = $iterator->getStack();
  194:                     pop @$stack; # last resource in the stack is the problem
  195:                                  # itself, which we don't need in the map stack
  196:                     my @mapPcs = map {$_->map_pc()} @$stack;
  197:                     $ENV{'form.filter'} = join(',', @mapPcs);
  198: 
  199:                     # Mark as both "here" and "jump"
  200:                     $ENV{'form.postsymb'} = $curRes->symb();
  201:                 }
  202:             }
  203:         }
  204: 
  205:         # If we found no problems, print a note to that effect.
  206:         if (!$foundDoableProblem) {
  207:             $r->print("<font size='+2'>All homework assignments have been completed.</font><br /><br />");
  208:         }
  209:     } else {
  210:         $r->print("<a href='navmaps?jumpToFirstHomework'>" .
  211:        &mt("Go To My First Homework Problem")."</a>&nbsp;&nbsp;&nbsp;&nbsp;");
  212:     }
  213: 
  214:     my $suppressEmptySequences = 0;
  215:     my $filterFunc = undef;
  216:     my $resource_no_folder_link = 0;
  217: 
  218:     # Display only due homework.
  219:     my $showOnlyHomework = 0;
  220:     if ($ENV{QUERY_STRING} eq 'showOnlyHomework') {
  221:         $showOnlyHomework = 1;
  222:         $suppressEmptySequences = 1;
  223:         $filterFunc = sub { my $res = shift; 
  224:                             return $res->completable() || $res->is_map();
  225:                         };
  226:         $r->print("<p><font size='+2'>".&mt("Uncompleted Homework")."</font></p>");
  227:         $ENV{'form.filter'} = '';
  228:         $ENV{'form.condition'} = 1;
  229: 	$resource_no_folder_link = 1;
  230:     } else {
  231:         $r->print("<a href='navmaps?showOnlyHomework'>" .
  232:        &mt("Show Only Uncompleted Homework")."</a>&nbsp;&nbsp;&nbsp;&nbsp;");
  233:     }
  234: 
  235:     # renderer call
  236:     my $renderArgs = { 'cols' => [0,1,2,3],
  237:                        'url' => '/adm/navmaps',
  238:                        'navmap' => $navmap,
  239:                        'suppressNavmap' => 1,
  240:                        'suppressEmptySequences' => $suppressEmptySequences,
  241:                        'filterFunc' => $filterFunc,
  242: 		       'resource_no_folder_link' => $resource_no_folder_link,
  243:                        'r' => $r};
  244:     my $render = render($renderArgs);
  245:     $navmap->untieHashes();
  246: 
  247:     # If no resources were printed, print a reassuring message so the
  248:     # user knows there was no error.
  249:     if ($renderArgs->{'counter'} == 0) {
  250:         if ($showOnlyHomework) {
  251:             $r->print("<p><font size='+1'>".&mt("All homework is currently completed").".</font></p>");
  252:         } else { # both jumpToFirstHomework and normal use the same: course must be empty
  253:             $r->print("<p><font size='+1'>This course is empty.</font></p>");
  254:         }
  255:     }
  256: 
  257:     $r->print("</body></html>");
  258:     $r->rflush();
  259: 
  260:     return OK;
  261: }
  262: 
  263: # Convenience functions: Returns a string that adds or subtracts
  264: # the second argument from the first hash, appropriate for the 
  265: # query string that determines which folders to recurse on
  266: sub addToFilter {
  267:     my $hashIn = shift;
  268:     my $addition = shift;
  269:     my %hash = %$hashIn;
  270:     $hash{$addition} = 1;
  271: 
  272:     return join (",", keys(%hash));
  273: }
  274: 
  275: sub removeFromFilter {
  276:     my $hashIn = shift;
  277:     my $subtraction = shift;
  278:     my %hash = %$hashIn;
  279: 
  280:     delete $hash{$subtraction};
  281:     return join(",", keys(%hash));
  282: }
  283: 
  284: # Convenience function: Given a stack returned from getStack on the iterator,
  285: # return the correct src() value.
  286: # Later, this should add an anchor when we start putting anchors in pages.
  287: sub getLinkForResource {
  288:     my $stack = shift;
  289:     my $res;
  290: 
  291:     # Check to see if there are any pages in the stack
  292:     foreach $res (@$stack) {
  293:         if (defined($res)) {
  294: 	    if ($res->is_page()) {
  295: 		return $res->src();
  296: 	    }
  297:             # in case folder was skipped over as "only sequence"
  298: 	    my ($map,$id,$src)=&Apache::lonnet::decode_symb($res->symb());
  299: 	    if ($map=~/\.page$/) {
  300: 		return &Apache::lonnet::clutter($map).'#'.
  301: 		    &Apache::lonnet::escape(&Apache::lonnet::declutter($src));
  302: 	    }
  303:         }
  304:     }
  305: 
  306:     # Failing that, return the src of the last resource that is defined
  307:     # (when we first recurse on a map, it puts an undefined resource
  308:     # on the bottom because $self->{HERE} isn't defined yet, and we
  309:     # want the src for the map anyhow)
  310:     foreach (@$stack) {
  311:         if (defined($_)) { $res = $_; }
  312:     }
  313: 
  314:     return $res->src();
  315: }
  316: 
  317: # Convenience function: This separates the logic of how to create
  318: # the problem text strings ("Due: DATE", "Open: DATE", "Not yet assigned",
  319: # etc.) into a separate function. It takes a resource object as the
  320: # first parameter, and the part number of the resource as the second.
  321: # It's basically a big switch statement on the status of the resource.
  322: 
  323: sub getDescription {
  324:     my $res = shift;
  325:     my $part = shift;
  326:     my $status = $res->status($part);
  327: 
  328:     if ($status == $res->NETWORK_FAILURE) { 
  329:         return &mt("Having technical difficulties; please check status later"); 
  330:     }
  331:     if ($status == $res->NOTHING_SET) {
  332:         return &mt("Not currently assigned.");
  333:     }
  334:     if ($status == $res->OPEN_LATER) {
  335:         return "Open " . timeToHumanString($res->opendate($part));
  336:     }
  337:     if ($status == $res->OPEN) {
  338:         if ($res->duedate($part)) {
  339:             return &mt("Due")."  " .timeToHumanString($res->duedate($part));
  340:         } else {
  341:             return &mt("Open, no due date");
  342:         }
  343:     }
  344:     if ($status == $res->PAST_DUE_ANSWER_LATER) {
  345:         return &mt("Answer open")." " . timeToHumanString($res->answerdate($part));
  346:     }
  347:     if ($status == $res->PAST_DUE_NO_ANSWER) {
  348:         return &mt("Was due")." " . timeToHumanString($res->duedate($part));
  349:     }
  350:     if ($status == $res->ANSWER_OPEN) {
  351:         return &mt("Answer available");
  352:     }
  353:     if ($status == $res->EXCUSED) {
  354:         return &mt("Excused by instructor");
  355:     }
  356:     if ($status == $res->ATTEMPTED) {
  357:         return &mt("Answer submitted, not yet graded");
  358:     }
  359:     if ($status == $res->TRIES_LEFT) {
  360:         my $tries = $res->tries($part);
  361:         my $maxtries = $res->maxtries($part);
  362:         my $triesString = "";
  363:         if ($tries && $maxtries) {
  364:             $triesString = "<font size=\"-1\"><i>($tries of $maxtries tries used)</i></font>";
  365:             if ($maxtries > 1 && $maxtries - $tries == 1) {
  366:                 $triesString = "<b>$triesString</b>";
  367:             }
  368:         }
  369:         if ($res->duedate($part)) {
  370:             return &mt("Due")." " . timeToHumanString($res->duedate($part)) .
  371:                 " $triesString";
  372:         } else {
  373:             return &mt("No due date")." $triesString";
  374:         }
  375:     }
  376:     if ($status == $res->ANSWER_SUBMITTED) {
  377:         return &mt('Answer submitted');
  378:     }
  379: }
  380: 
  381: # Convenience function, so others can use it: Is the problem due in less then
  382: # 24 hours, and still can be done?
  383: 
  384: sub dueInLessThan24Hours {
  385:     my $res = shift;
  386:     my $part = shift;
  387:     my $status = $res->status($part);
  388: 
  389:     return ($status == $res->OPEN() ||
  390:             $status == $res->TRIES_LEFT()) &&
  391: 	    $res->duedate($part) && $res->duedate($part) < time()+(24*60*60) &&
  392: 	    $res->duedate($part) > time();
  393: }
  394: 
  395: # Convenience function, so others can use it: Is there only one try remaining for the
  396: # part, with more then one try to begin with, not due yet and still can be done?
  397: sub lastTry {
  398:     my $res = shift;
  399:     my $part = shift;
  400: 
  401:     my $tries = $res->tries($part);
  402:     my $maxtries = $res->maxtries($part);
  403:     return $tries && $maxtries && $maxtries > 1 &&
  404:         $maxtries - $tries == 1 && $res->duedate($part) &&
  405:         $res->duedate($part) > time();
  406: }
  407: 
  408: # This puts a human-readable name on the ENV variable.
  409: 
  410: sub advancedUser {
  411:     return $ENV{'request.role.adv'};
  412: }
  413: 
  414: 
  415: # timeToHumanString takes a time number and converts it to a
  416: # human-readable representation, meant to be used in the following
  417: # manner:
  418: # print "Due $timestring"
  419: # print "Open $timestring"
  420: # print "Answer available $timestring"
  421: # Very, very, very, VERY English-only... goodness help a localizer on
  422: # this func...
  423: sub timeToHumanString {
  424:     my ($time) = @_;
  425:     # zero, '0' and blank are bad times
  426:     if (!$time) {
  427:         return &mt('never');
  428:     }
  429:     unless (&Apache::lonlocal::current_language()=~/^en/) {
  430: 	return &Apache::lonlocal::locallocaltime($time);
  431:     } 
  432:     my $now = time();
  433: 
  434:     my @time = localtime($time);
  435:     my @now = localtime($now);
  436: 
  437:     # Positive = future
  438:     my $delta = $time - $now;
  439: 
  440:     my $minute = 60;
  441:     my $hour = 60 * $minute;
  442:     my $day = 24 * $hour;
  443:     my $week = 7 * $day;
  444:     my $inPast = 0;
  445: 
  446:     # Logic in comments:
  447:     # Is it now? (extremely unlikely)
  448:     if ( $delta == 0 ) {
  449:         return "this instant";
  450:     }
  451: 
  452:     if ($delta < 0) {
  453:         $inPast = 1;
  454:         $delta = -$delta;
  455:     }
  456: 
  457:     if ( $delta > 0 ) {
  458: 
  459:         my $tense = $inPast ? " ago" : "";
  460:         my $prefix = $inPast ? "" : "in ";
  461:         
  462:         # Less then a minute
  463:         if ( $delta < $minute ) {
  464:             if ($delta == 1) { return "${prefix}1 second$tense"; }
  465:             return "$prefix$delta seconds$tense";
  466:         }
  467: 
  468:         # Less then an hour
  469:         if ( $delta < $hour ) {
  470:             # If so, use minutes
  471:             my $minutes = floor($delta / 60);
  472:             if ($minutes == 1) { return "${prefix}1 minute$tense"; }
  473:             return "$prefix$minutes minutes$tense";
  474:         }
  475:         
  476:         # Is it less then 24 hours away? If so,
  477:         # display hours + minutes
  478:         if ( $delta < $hour * 24) {
  479:             my $hours = floor($delta / $hour);
  480:             my $minutes = floor(($delta % $hour) / $minute);
  481:             my $hourString = "$hours hours";
  482:             my $minuteString = ", $minutes minutes";
  483:             if ($hours == 1) {
  484:                 $hourString = "1 hour";
  485:             }
  486:             if ($minutes == 1) {
  487:                 $minuteString = ", 1 minute";
  488:             }
  489:             if ($minutes == 0) {
  490:                 $minuteString = "";
  491:             }
  492:             return "$prefix$hourString$minuteString$tense";
  493:         }
  494: 
  495:         # Less then 5 days away, display day of the week and
  496:         # HH:MM
  497:         if ( $delta < $day * 5 ) {
  498:             my $timeStr = strftime("%A, %b %e at %I:%M %P", localtime($time));
  499:             $timeStr =~ s/12:00 am/00:00/;
  500:             $timeStr =~ s/12:00 pm/noon/;
  501:             return ($inPast ? "last " : "next ") .
  502:                 $timeStr;
  503:         }
  504:         
  505:         # Is it this year?
  506:         if ( $time[5] == $now[5]) {
  507:             # Return on Month Day, HH:MM meridian
  508:             my $timeStr = strftime("on %A, %b %e at %I:%M %P", localtime($time));
  509:             $timeStr =~ s/12:00 am/00:00/;
  510:             $timeStr =~ s/12:00 pm/noon/;
  511:             return $timeStr;
  512:         }
  513: 
  514:         # Not this year, so show the year
  515:         my $timeStr = strftime("on %A, %b %e %G at %I:%M %P", localtime($time));
  516:         $timeStr =~ s/12:00 am/00:00/;
  517:         $timeStr =~ s/12:00 pm/noon/;
  518:         return $timeStr;
  519:     }
  520: }
  521: 
  522: 
  523: =pod
  524: 
  525: =head1 NAME
  526: 
  527: Apache::lonnavmap - Subroutines to handle and render the navigation
  528:     maps
  529: 
  530: =head1 SYNOPSIS
  531: 
  532: The main handler generates the navigational listing for the course,
  533: the other objects export this information in a usable fashion for
  534: other modules.
  535: 
  536: =head1 OVERVIEW
  537: 
  538: X<lonnavmaps, overview> When a user enters a course, LON-CAPA examines the
  539: course structure and caches it in what is often referred to as the
  540: "big hash" X<big hash>. You can see it if you are logged into
  541: LON-CAPA, in a course, by going to /adm/test. (You may need to
  542: tweak the /home/httpd/lonTabs/htpasswd file to view it.) The
  543: content of the hash will be under the heading "Big Hash".
  544: 
  545: Big Hash contains, among other things, how resources are related
  546: to each other (next/previous), what resources are maps, which 
  547: resources are being chosen to not show to the student (for random
  548: selection), and a lot of other things that can take a lot of time
  549: to compute due to the amount of data that needs to be collected and
  550: processed.
  551: 
  552: Apache::lonnavmaps provides an object model for manipulating this
  553: information in a higher-level fashion then directly manipulating 
  554: the hash. It also provides access to several auxilary functions 
  555: that aren't necessarily stored in the Big Hash, but are a per-
  556: resource sort of value, like whether there is any feedback on 
  557: a given resource.
  558: 
  559: Apache::lonnavmaps also abstracts away branching, and someday, 
  560: conditions, for the times where you don't really care about those
  561: things.
  562: 
  563: Apache::lonnavmaps also provides fairly powerful routines for
  564: rendering navmaps, and last but not least, provides the navmaps
  565: view for when the user clicks the NAV button.
  566: 
  567: B<Note>: Apache::lonnavmaps I<only> works for the "currently
  568: logged in user"; if you want things like "due dates for another
  569: student" lonnavmaps can not directly retrieve information like
  570: that. You need the EXT function. This module can still help,
  571: because many things, such as the course structure, are constant
  572: between users, and Apache::lonnavmaps can help by providing
  573: symbs for the EXT call.
  574: 
  575: The rest of this file will cover the provided rendering routines, 
  576: which can often be used without fiddling with the navmap object at
  577: all, then documents the Apache::lonnavmaps::navmap object, which
  578: is the key to accessing the Big Hash information, covers the use
  579: of the Iterator (which provides the logic for traversing the 
  580: somewhat-complicated Big Hash data structure), documents the
  581: Apache::lonnavmaps::Resource objects that are returned by 
  582: 
  583: =head1 Subroutine: render
  584: 
  585: The navmap renderer package provides a sophisticated rendering of the
  586: standard navigation maps interface into HTML. The provided nav map
  587: handler is actually just a glorified call to this.
  588: 
  589: Because of the large number of parameters this function accepts,
  590: instead of passing it arguments as is normal, pass it in an anonymous
  591: hash with the desired options.
  592: 
  593: The package provides a function called 'render', called as
  594: Apache::lonnavmaps::render({}).
  595: 
  596: =head2 Overview of Columns
  597: 
  598: The renderer will build an HTML table for the navmap and return
  599: it. The table is consists of several columns, and a row for each
  600: resource (or possibly each part). You tell the renderer how many
  601: columns to create and what to place in each column, optionally using
  602: one or more of the prepared columns, and the renderer will assemble
  603: the table.
  604: 
  605: Any additional generally useful column types should be placed in the
  606: renderer code here, so anybody can use it anywhere else. Any code
  607: specific to the current application (such as the addition of <input>
  608: elements in a column) should be placed in the code of the thing using
  609: the renderer.
  610: 
  611: At the core of the renderer is the array reference COLS (see Example
  612: section below for how to pass this correctly). The COLS array will
  613: consist of entries of one of two types of things: Either an integer
  614: representing one of the pre-packaged column types, or a sub reference
  615: that takes a resource reference, a part number, and a reference to the
  616: argument hash passed to the renderer, and returns a string that will
  617: be inserted into the HTML representation as it.
  618: 
  619: All other parameters are ways of either changing how the columns
  620: are printing, or which rows are shown.
  621: 
  622: The pre-packaged column names are refered to by constants in the
  623: Apache::lonnavmaps namespace. The following currently exist:
  624: 
  625: =over 4
  626: 
  627: =item * B<Apache::lonnavmaps::resource>:
  628: 
  629: The general info about the resource: Link, icon for the type, etc. The
  630: first column in the standard nav map display. This column provides the
  631: indentation effect seen in the B<NAV> screen. This column also accepts
  632: the following parameters in the renderer hash:
  633: 
  634: =over 4
  635: 
  636: =item * B<resource_nolink>: default false
  637: 
  638: If true, the resource will not be linked. By default, all non-folder
  639: resources are linked.
  640: 
  641: =item * B<resource_part_count>: default true
  642: 
  643: If true, the resource will show a part count B<if> the full
  644: part list is not displayed. (See "condense_parts" later.) If false,
  645: the resource will never show a part count.
  646: 
  647: =item * B<resource_no_folder_link>:
  648: 
  649: If true, the resource's folder will not be clickable to open or close
  650: it. Default is false. True implies printCloseAll is false, since you
  651: can't close or open folders when this is on anyhow.
  652: 
  653: =back
  654: 
  655: =item * B<Apache::lonnavmaps::communication_status>:
  656: 
  657: Whether there is discussion on the resource, email for the user, or
  658: (lumped in here) perl errors in the execution of the problem. This is
  659: the second column in the main nav map.
  660: 
  661: =item * B<Apache::lonnavmaps::quick_status>:
  662: 
  663: An icon for the status of a problem, with five possible states:
  664: Correct, incorrect, open, awaiting grading (for a problem where the
  665: computer's grade is suppressed, or the computer can't grade, like
  666: essay problem), or none (not open yet, not a problem). The
  667: third column of the standard navmap.
  668: 
  669: =item * B<Apache::lonnavmaps::long_status>:
  670: 
  671: A text readout of the details of the current status of the problem,
  672: such as "Due in 22 hours". The fourth column of the standard navmap.
  673: 
  674: =item * B<Apache::lonnavmaps::part_status_summary>:
  675: 
  676: A text readout summarizing the status of the problem. If it is a
  677: single part problem, will display "Correct", "Incorrect", 
  678: "Not yet open", "Open", "Attempted", or "Error". If there are
  679: multiple parts, this will output a string that in HTML will show a
  680: status of how many parts are in each status, in color coding, trying
  681: to match the colors of the icons within reason.
  682: 
  683: Note this only makes sense if you are I<not> showing parts. If 
  684: C<showParts> is true (see below), this column will not output
  685: anything. 
  686: 
  687: =back
  688: 
  689: If you add any others please be sure to document them here.
  690: 
  691: An example of a column renderer that will show the ID number of a
  692: resource, along with the part name if any:
  693: 
  694:  sub { 
  695:   my ($resource, $part, $params) = @_;   
  696:   if ($part) { return '<td>' . $resource->{ID} . ' ' . $part . '</td>'; }
  697:   return '<td>' . $resource->{ID} . '</td>';
  698:  }
  699: 
  700: Note these functions are responsible for the TD tags, which allow them
  701: to override vertical and horizontal alignment, etc.
  702: 
  703: =head2 Parameters
  704: 
  705: Minimally, you should be
  706: able to get away with just using 'cols' (to specify the columns
  707: shown), 'url' (necessary for the folders to link to the current screen
  708: correctly), and possibly 'queryString' if your app calls for it. In
  709: that case, maintaining the state of the folders will be done
  710: automatically.
  711: 
  712: =over 4
  713: 
  714: =item * B<iterator>: default: constructs one from %ENV
  715: 
  716: A reference to a fresh ::iterator to use from the navmaps. The
  717: rendering will reflect the options passed to the iterator, so you can
  718: use that to just render a certain part of the course, if you like. If
  719: one is not passed, the renderer will attempt to construct one from
  720: ENV{'form.filter'} and ENV{'form.condition'} information, plus the
  721: 'iterator_map' parameter if any.
  722: 
  723: =item * B<iterator_map>: default: not used
  724: 
  725: If you are letting the renderer do the iterator handling, you can
  726: instruct the renderer to render only a particular map by passing it
  727: the source of the map you want to process, like
  728: '/res/103/jerf/navmap.course.sequence'.
  729: 
  730: =item * B<navmap>: default: constructs one from %ENV
  731: 
  732: A reference to a navmap, used only if an iterator is not passed in. If
  733: this is necessary to make an iterator but it is not passed in, a new
  734: one will be constructed based on ENV info. This is useful to do basic
  735: error checking before passing it off to render.
  736: 
  737: =item * B<r>: default: must be passed in
  738: 
  739: The standard Apache response object. This must be passed to the
  740: renderer or the course hash will be locked.
  741: 
  742: =item * B<cols>: default: empty (useless)
  743: 
  744: An array reference
  745: 
  746: =item * B<showParts>:default true
  747: 
  748: A flag. If true, a line for the resource itself, and a line
  749: for each part will be displayed. If not, only one line for each
  750: resource will be displayed.
  751: 
  752: =item * B<condenseParts>: default true
  753: 
  754: A flag. If true, if all parts of the problem have the same
  755: status and that status is Nothing Set, Correct, or Network Failure,
  756: then only one line will be displayed for that resource anyhow. If no,
  757: all parts will always be displayed. If showParts is 0, this is
  758: ignored.
  759: 
  760: =item * B<jumpCount>: default: determined from %ENV
  761: 
  762: A string identifying the URL to place the anchor 'curloc' at.
  763: It is the responsibility of the renderer user to
  764: ensure that the #curloc is in the URL. By default, determined through
  765: the use of the ENV{} 'jump' information, and should normally "just
  766: work" correctly.
  767: 
  768: =item * B<here>: default: empty string
  769: 
  770: A Symb identifying where to place the 'here' marker. The empty
  771: string means no marker.
  772: 
  773: =item * B<indentString>: default: 25 pixel whitespace image
  774: 
  775: A string identifying the indentation string to use. 
  776: 
  777: =item * B<queryString>: default: empty
  778: 
  779: A string which will be prepended to the query string used when the
  780: folders are opened or closed. You can use this to pass
  781: application-specific values.
  782: 
  783: =item * B<url>: default: none
  784: 
  785: The url the folders will link to, which should be the current
  786: page. Required if the resource info column is shown, and you 
  787: are allowing the user to open and close folders.
  788: 
  789: =item * B<currentJumpIndex>: default: no jumping
  790: 
  791: Describes the currently-open row number to cause the browser to jump
  792: to, because the user just opened that folder. By default, pulled from
  793: the Jump information in the ENV{'form.*'}.
  794: 
  795: =item * B<printKey>: default: false
  796: 
  797: If true, print the key that appears on the top of the standard
  798: navmaps.
  799: 
  800: =item * B<printCloseAll>: default: true
  801: 
  802: If true, print the "Close all folders" or "open all folders"
  803: links.
  804: 
  805: =item * B<filterFunc>: default: sub {return 1;} (accept everything)
  806: 
  807: A function that takes the resource object as its only parameter and
  808: returns a true or false value. If true, the resource is displayed. If
  809: false, it is simply skipped in the display.
  810: 
  811: =item * B<suppressEmptySequences>: default: false
  812: 
  813: If you're using a filter function, and displaying sequences to orient
  814: the user, then frequently some sequences will be empty. Setting this to
  815: true will cause those sequences not to display, so as not to confuse the
  816: user into thinking that if the sequence is there there should be things
  817: under it; for example, see the "Show Uncompleted Homework" view on the
  818: B<NAV> screen.
  819: 
  820: =item * B<suppressNavmaps>: default: false
  821: 
  822: If true, will not display Navigate Content resources. 
  823: 
  824: =back
  825: 
  826: =head2 Additional Info
  827: 
  828: In addition to the parameters you can pass to the renderer, which will
  829: be passed through unchange to the column renderers, the renderer will
  830: generate the following information which your renderer may find
  831: useful:
  832: 
  833: =over 4
  834: 
  835: =item * B<counter>: 
  836: 
  837: Contains the number of rows printed. Useful after calling the render 
  838: function, as you can detect whether anything was printed at all.
  839: 
  840: =item * B<isNewBranch>:
  841: 
  842: Useful for renderers: If this resource is currently the first resource
  843: of a new branch, this will be true. The Resource column (leftmost in the
  844: navmaps screen) uses this to display the "new branch" icon 
  845: 
  846: =back
  847: 
  848: =cut
  849: 
  850: sub resource { return 0; }
  851: sub communication_status { return 1; }
  852: sub quick_status { return 2; }
  853: sub long_status { return 3; }
  854: sub part_status_summary { return 4; }
  855: 
  856: sub render_resource {
  857:     my ($resource, $part, $params) = @_;
  858: 
  859:     my $nonLinkedText = ''; # stuff after resource title not in link
  860: 
  861:     my $link = $params->{"resourceLink"};
  862:     my $src = $resource->src();
  863:     my $it = $params->{"iterator"};
  864:     my $filter = $it->{FILTER};
  865: 
  866:     my $title = $resource->compTitle();
  867:     if ($src =~ /^\/uploaded\//) {
  868:         $nonLinkedText=$title;
  869:         $title = '';
  870:     }
  871:     my $partLabel = "";
  872:     my $newBranchText = "";
  873:     
  874:     # If this is a new branch, label it so
  875:     if ($params->{'isNewBranch'}) {
  876:         $newBranchText = "<img src='/adm/lonIcons/branch.gif' border='0' />";
  877:     }
  878: 
  879:     # links to open and close the folder
  880:     my $linkopen = "<a href='$link'>";
  881:     my $linkclose = "</a>";
  882: 
  883:     # Default icon: unknown page
  884:     my $icon = "<img src='/adm/lonIcons/unknown.gif' alt='' border='0' />";
  885:     
  886:     if ($resource->is_problem()) {
  887:         if ($part eq '0' || $params->{'condensed'}) {
  888:             $icon = '<img src="/adm/lonIcons/problem.gif" alt="" border="0" />';
  889:         } else {
  890:             $icon = $params->{'indentString'};
  891:         }
  892:     } else {
  893: 	$icon = "<img src='".&Apache::loncommon::icon($resource->src).
  894: 	    "' alt='' border='0' />";
  895:     }
  896: 
  897:     # Display the correct map icon to open or shut map
  898:     if ($resource->is_map()) {
  899:         my $mapId = $resource->map_pc();
  900:         my $nowOpen = !defined($filter->{$mapId});
  901:         if ($it->{CONDITION}) {
  902:             $nowOpen = !$nowOpen;
  903:         }
  904: 
  905: 	my $folderType = $resource->is_sequence() ? 'folder' : 'page';
  906: 
  907:         if (!$params->{'resource_no_folder_link'}) {
  908:             $icon = "navmap.$folderType." . ($nowOpen ? 'closed' : 'open') . '.gif';
  909:             $icon = "<img src='/adm/lonIcons/$icon' alt='' border='0' />";
  910: 
  911:             $linkopen = "<a href='" . $params->{'url'} . '?' . 
  912:                 $params->{'queryString'} . '&filter=';
  913:             $linkopen .= ($nowOpen xor $it->{CONDITION}) ?
  914:                 addToFilter($filter, $mapId) :
  915:                 removeFromFilter($filter, $mapId);
  916:             $linkopen .= "&condition=" . $it->{CONDITION} . '&hereType='
  917:                 . $params->{'hereType'} . '&here=' .
  918:                 &Apache::lonnet::escape($params->{'here'}) . 
  919:                 '&jump=' .
  920:                 &Apache::lonnet::escape($resource->symb()) . 
  921:                 "&folderManip=1'>";
  922:         } else {
  923:             # Don't allow users to manipulate folder
  924:             $icon = "navmap.$folderType." . ($nowOpen ? 'closed' : 'open') .
  925:                 '.nomanip.gif';
  926:             $icon = "<img src='/adm/lonIcons/$icon' alt='' border='0' />";
  927: 
  928:             $linkopen = "";
  929:             $linkclose = "";
  930:         }
  931:     }
  932: 
  933:     if ($resource->randomout()) {
  934:         $nonLinkedText .= ' <i>(hidden)</i> ';
  935:     }
  936:     
  937:     # We're done preparing and finally ready to start the rendering
  938:     my $result = "<td align='left' valign='center'>";
  939: 
  940:     my $indentLevel = $params->{'indentLevel'};
  941:     if ($newBranchText) { $indentLevel--; }
  942: 
  943:     # print indentation
  944:     for (my $i = 0; $i < $indentLevel; $i++) {
  945:         $result .= $params->{'indentString'};
  946:     }
  947: 
  948:     # Decide what to display
  949:     $result .= "$newBranchText$linkopen$icon$linkclose";
  950:     
  951:     my $curMarkerBegin = '';
  952:     my $curMarkerEnd = '';
  953: 
  954:     # Is this the current resource?
  955:     if (!$params->{'displayedHereMarker'} && 
  956:         $resource->symb() eq $params->{'here'} ) {
  957:         $curMarkerBegin = '<font color="red" size="+2">&gt; </font>';
  958:         $curMarkerEnd = '<font color="red" size="+2">&lt;</font>';
  959:         $params->{'displayedHereMarker'} = 1;
  960:     }
  961: 
  962:     if ($resource->is_problem() && $part ne '0' && 
  963:         !$params->{'condensed'}) {
  964: 	my $displaypart=&Apache::lonnet::EXT('resource.'.$part.'.display',
  965: 					     $resource->symb());
  966: 	unless ($displaypart) { $displaypart=$part; }
  967:         $partLabel = " (Part: $displaypart)";
  968: 	$link.='#'.&Apache::lonnet::escape($part);
  969:         $title = "";
  970:     }
  971: 
  972:     if ($params->{'condensed'} && $resource->countParts() > 1) {
  973:         $nonLinkedText .= ' (' . $resource->countParts() . ' parts)';
  974:     }
  975: 
  976:     if (!$params->{'resource_nolink'} && $src !~ /^\/uploaded\// &&
  977: 	!$resource->is_sequence()) {
  978:         $result .= "  $curMarkerBegin<a href='$link'>$title$partLabel</a>$curMarkerEnd $nonLinkedText</td>";
  979:     } else {
  980:         $result .= "  $curMarkerBegin$title$partLabel$curMarkerEnd $nonLinkedText</td>";
  981:     }
  982: 
  983:     return $result;
  984: }
  985: 
  986: sub render_communication_status {
  987:     my ($resource, $part, $params) = @_;
  988:     my $discussionHTML = ""; my $feedbackHTML = ""; my $errorHTML = "";
  989: 
  990:     my $link = $params->{"resourceLink"};
  991:     my $linkopen = "<a href='$link'>";
  992:     my $linkclose = "</a>";
  993: 
  994:     if ($resource->hasDiscussion()) {
  995:         $discussionHTML = $linkopen .
  996:             '<img border="0" src="/adm/lonMisc/chat.gif" />' .
  997:             $linkclose;
  998:     }
  999:     
 1000:     if ($resource->getFeedback()) {
 1001:         my $feedback = $resource->getFeedback();
 1002:         foreach (split(/\,/, $feedback)) {
 1003:             if ($_) {
 1004:                 $feedbackHTML .= '&nbsp;<a href="/adm/email?display='
 1005:                     . &Apache::lonnet::escape($_) . '">'
 1006:                     . '<img src="/adm/lonMisc/feedback.gif" '
 1007:                     . 'border="0" /></a>';
 1008:             }
 1009:         }
 1010:     }
 1011:     
 1012:     if ($resource->getErrors()) {
 1013:         my $errors = $resource->getErrors();
 1014:         my $errorcount = 0;
 1015:         foreach (split(/,/, $errors)) {
 1016:             last if ($errorcount>=10); # Only output 10 bombs maximum
 1017:             if ($_) {
 1018:                 $errorcount++;
 1019:                 $errorHTML .= '&nbsp;<a href="/adm/email?display='
 1020:                     . &Apache::lonnet::escape($_) . '">'
 1021:                     . '<img src="/adm/lonMisc/bomb.gif" '
 1022:                     . 'border="0" /></a>';
 1023:             }
 1024:         }
 1025:     }
 1026: 
 1027:     if ($params->{'multipart'} && $part != '0') {
 1028: 	$discussionHTML = $feedbackHTML = $errorHTML = '';
 1029:     }
 1030: 
 1031:     return "<td width=\"75\" align=\"left\" valign=\"center\">$discussionHTML$feedbackHTML$errorHTML&nbsp;</td>";
 1032: 
 1033: }
 1034: sub render_quick_status {
 1035:     my ($resource, $part, $params) = @_;
 1036:     my $result = "";
 1037:     my $firstDisplayed = !$params->{'condensed'} && 
 1038:         $params->{'multipart'} && $part eq "0";
 1039: 
 1040:     my $link = $params->{"resourceLink"};
 1041:     my $linkopen = "<a href='$link'>";
 1042:     my $linkclose = "</a>";
 1043: 
 1044:     if ($resource->is_problem() &&
 1045:         !$firstDisplayed) {
 1046: 	
 1047:         my $icon = $statusIconMap{$resource->simpleStatus($part)};
 1048:         my $alt = $iconAltTags{$icon};
 1049:         if ($icon) {
 1050:             $result .= "<td width='30' valign='center' width='50' align='right'>$linkopen<img width='25' height='25' src='/adm/lonIcons/$icon' border='0' alt='$alt' />$linkclose</td>\n";
 1051:         } else {
 1052:             $result .= "<td width='30'>&nbsp;</td>\n";
 1053:         }
 1054:     } else { # not problem, no icon
 1055:         $result .= "<td width='30'>&nbsp;</td>\n";
 1056:     }
 1057: 
 1058:     return $result;
 1059: }
 1060: sub render_long_status {
 1061:     my ($resource, $part, $params) = @_;
 1062:     my $result = "<td align='right' valign='center'>\n";
 1063:     my $firstDisplayed = !$params->{'condensed'} && 
 1064:         $params->{'multipart'} && $part eq "0";
 1065:                 
 1066:     my $color;
 1067:     if ($resource->is_problem()) {
 1068:         $color = $colormap{$resource->status};
 1069:         
 1070:         if (dueInLessThan24Hours($resource, $part) ||
 1071:             lastTry($resource, $part)) {
 1072:             $color = $hurryUpColor;
 1073:         }
 1074:     }
 1075:     
 1076:     if ($resource->kind() eq "res" &&
 1077:         $resource->is_problem() &&
 1078:         !$firstDisplayed) {
 1079:         if ($color) {$result .= "<font color=\"$color\"><b>"; }
 1080:         $result .= getDescription($resource, $part);
 1081:         if ($color) {$result .= "</b></font>"; }
 1082:     }
 1083:     if ($resource->is_map() && advancedUser() && $resource->randompick()) {
 1084:         $result .= '(randomly select ' . $resource->randompick() .')';
 1085:     }
 1086: 
 1087:     # Debugging code
 1088:     #$result .= " " . $resource->awarded($part) . '/' . $resource->weight($part) .
 1089:     #	' - Part: ' . $part;
 1090: 
 1091:     $result .= "</td>\n";
 1092:     
 1093:     return $result;
 1094: }
 1095: 
 1096: # Colors obtained by taking the icons, matching the colors, and
 1097: # possibly reducing the Value (HSV) of the color, if it's too bright
 1098: # for text, generally by one third or so.
 1099: my %statusColors = 
 1100:     (
 1101:      $resObj->CLOSED => '#000000',
 1102:      $resObj->OPEN   => '#998b13',
 1103:      $resObj->CORRECT => '#26933f',
 1104:      $resObj->INCORRECT => '#c48207',
 1105:      $resObj->ATTEMPTED => '#a87510',
 1106:      $resObj->ERROR => '#000000'
 1107:      );
 1108: my %statusStrings = 
 1109:     (
 1110:      $resObj->CLOSED => 'Not yet open',
 1111:      $resObj->OPEN   => 'Open',
 1112:      $resObj->CORRECT => 'Correct',
 1113:      $resObj->INCORRECT => 'Incorrect',
 1114:      $resObj->ATTEMPTED => 'Attempted',
 1115:      $resObj->ERROR => 'Network Error'
 1116:      );
 1117: my @statuses = ($resObj->CORRECT, $resObj->ATTEMPTED, $resObj->INCORRECT, $resObj->OPEN, $resObj->CLOSED, $resObj->ERROR);
 1118: 
 1119: use Data::Dumper;
 1120: sub render_parts_summary_status {
 1121:     my ($resource, $part, $params) = @_;
 1122:     if (!$resource->is_problem() && !$resource->contains_problem) { return '<td></td>'; }
 1123:     if ($params->{showParts}) { 
 1124: 	return '<td></td>';
 1125:     }
 1126: 
 1127:     my $td = "<td align='right'>\n";
 1128:     my $endtd = "</td>\n";
 1129:     my @probs;
 1130: 
 1131:     if ($resource->contains_problem) {
 1132: 	@probs=$resource->retrieveResources($resource,sub { $_[0]->is_problem() },1,0);
 1133:     } else {
 1134: 	@probs=($resource);
 1135:     }
 1136:     my $return;
 1137:     my %overallstatus;
 1138:     my $totalParts;
 1139:     foreach my $resource (@probs) {
 1140: 	# If there is a single part, just show the simple status
 1141: 	if ($resource->singlepart()) {
 1142: 	    my $status = $resource->simpleStatus(${$resource->parts}[0]);
 1143: 	    $overallstatus{$status}++;
 1144: 	    $totalParts++;
 1145: 	    next;
 1146: 	}
 1147: 	# Now we can be sure the $part doesn't really matter.
 1148: 	my $statusCount = $resource->simpleStatusCount();
 1149: 	my @counts;
 1150: 	foreach my $status (@statuses) {
 1151: 	    # decouple display order from the simpleStatusCount order
 1152: 	    my $slot = Apache::lonnavmaps::resource::statusToSlot($status);
 1153: 	    if ($statusCount->[$slot]) {
 1154: 		$overallstatus{$status}+=$statusCount->[$slot];
 1155: 		$totalParts+=$statusCount->[$slot];
 1156: 	    }
 1157: 	}
 1158:     }
 1159:     $return.= $td . $totalParts . ' parts: ';
 1160:     foreach my $status (@statuses) {
 1161: 	if ($overallstatus{$status}) {
 1162: 	    $return.="<font color='" . $statusColors{$status} .
 1163: 		"'>" . $overallstatus{$status} . ' '
 1164: 		. $statusStrings{$status} . "</font>";
 1165: 	}
 1166:     }
 1167:     $return.= $endtd;
 1168:     return $return;
 1169: }
 1170: 
 1171: my @preparedColumns = (\&render_resource, \&render_communication_status,
 1172:                        \&render_quick_status, \&render_long_status,
 1173: 		       \&render_parts_summary_status);
 1174: 
 1175: sub setDefault {
 1176:     my ($val, $default) = @_;
 1177:     if (!defined($val)) { return $default; }
 1178:     return $val;
 1179: }
 1180: 
 1181: sub render {
 1182:     my $args = shift;
 1183:     &Apache::loncommon::get_unprocessed_cgi($ENV{QUERY_STRING});
 1184:     my $result = '';
 1185: 
 1186:     # Configure the renderer.
 1187:     my $cols = $args->{'cols'};
 1188:     if (!defined($cols)) {
 1189:         # no columns, no nav maps.
 1190:         return '';
 1191:     }
 1192:     my $mustCloseNavMap = 0;
 1193:     my $navmap;
 1194:     if (defined($args->{'navmap'})) {
 1195:         $navmap = $args->{'navmap'};
 1196:     }
 1197: 
 1198:     my $r = $args->{'r'};
 1199:     my $queryString = $args->{'queryString'};
 1200:     my $jump = $args->{'jump'};
 1201:     my $here = $args->{'here'};
 1202:     my $suppressNavmap = setDefault($args->{'suppressNavmap'}, 0);
 1203:     my $closeAllPages = setDefault($args->{'closeAllPages'}, 0);
 1204:     my $currentJumpDelta = 2; # change this to change how many resources are displayed
 1205:                              # before the current resource when using #current
 1206: 
 1207:     # If we were passed 'here' information, we are not rendering
 1208:     # after a folder manipulation, and we were not passed an
 1209:     # iterator, make sure we open the folders to show the "here"
 1210:     # marker
 1211:     my $filterHash = {};
 1212:     # Figure out what we're not displaying
 1213:     foreach (split(/\,/, $ENV{"form.filter"})) {
 1214:         if ($_) {
 1215:             $filterHash->{$_} = "1";
 1216:         }
 1217:     }
 1218: 
 1219:     # Filter: Remember filter function and add our own filter: Refuse
 1220:     # to show hidden resources unless the user can see them.
 1221:     my $userCanSeeHidden = advancedUser();
 1222:     my $filterFunc = setDefault($args->{'filterFunc'},
 1223:                                 sub {return 1;});
 1224:     if (!$userCanSeeHidden) {
 1225:         # Without renaming the filterfunc, the server seems to go into
 1226:         # an infinite loop
 1227:         my $oldFilterFunc = $filterFunc;
 1228:         $filterFunc = sub { my $res = shift; return !$res->randomout() && 
 1229:                                 &$oldFilterFunc($res);};
 1230:     }
 1231: 
 1232:     my $condition = 0;
 1233:     if ($ENV{'form.condition'}) {
 1234:         $condition = 1;
 1235:     }
 1236: 
 1237:     if (!$ENV{'form.folderManip'} && !defined($args->{'iterator'})) {
 1238:         # Step 1: Check to see if we have a navmap
 1239:         if (!defined($navmap)) {
 1240:             $navmap = Apache::lonnavmaps::navmap->new();
 1241:             $mustCloseNavMap = 1;
 1242:         }
 1243: 
 1244:         # Step two: Locate what kind of here marker is necessary
 1245:         # Determine where the "here" marker is and where the screen jumps to.
 1246: 
 1247:         if ($ENV{'form.postsymb'}) {
 1248:             $here = $jump = $ENV{'form.postsymb'};
 1249:         } elsif ($ENV{'form.postdata'}) {
 1250:             # couldn't find a symb, is there a URL?
 1251:             my $currenturl = $ENV{'form.postdata'};
 1252:             #$currenturl=~s/^http\:\/\///;
 1253:             #$currenturl=~s/^[^\/]+//;
 1254:             
 1255:             $here = $jump = &Apache::lonnet::symbread($currenturl);
 1256:         }
 1257: 
 1258:         # Step three: Ensure the folders are open
 1259:         my $mapIterator = $navmap->getIterator(undef, undef, undef, 1);
 1260:         my $curRes;
 1261:         my $found = 0;
 1262:         
 1263:         # We only need to do this if we need to open the maps to show the
 1264:         # current position. This will change the counter so we can't count
 1265:         # for the jump marker with this loop.
 1266:         while (($curRes = $mapIterator->next()) && !$found) {
 1267:             if (ref($curRes) && $curRes->symb() eq $here) {
 1268:                 my $mapStack = $mapIterator->getStack();
 1269:                 
 1270:                 # Ensure the parent maps are open
 1271:                 for my $map (@{$mapStack}) {
 1272:                     if ($condition) {
 1273:                         undef $filterHash->{$map->map_pc()};
 1274:                     } else {
 1275:                         $filterHash->{$map->map_pc()} = 1;
 1276:                     }
 1277:                 }
 1278:                 $found = 1;
 1279:             }
 1280:         }            
 1281:     }        
 1282: 
 1283:     if ( !defined($args->{'iterator'}) && $ENV{'form.folderManip'} ) { # we came from a user's manipulation of the nav page
 1284:         # If this is a click on a folder or something, we want to preserve the "here"
 1285:         # from the querystring, and get the new "jump" marker
 1286:         $here = $ENV{'form.here'};
 1287:         $jump = $ENV{'form.jump'};
 1288:     } 
 1289:     
 1290:     my $it = $args->{'iterator'};
 1291:     if (!defined($it)) {
 1292:         # Construct a default iterator based on $ENV{'form.'} information
 1293:         
 1294:         # Step 1: Check to see if we have a navmap
 1295:         if (!defined($navmap)) {
 1296:             $navmap = Apache::lonnavmaps::navmap->new();
 1297:             $mustCloseNavMap = 1;
 1298:         }
 1299: 
 1300:         # See if we're being passed a specific map
 1301:         if ($args->{'iterator_map'}) {
 1302:             my $map = $args->{'iterator_map'};
 1303:             $map = $navmap->getResourceByUrl($map);
 1304:             my $firstResource = $map->map_start();
 1305:             my $finishResource = $map->map_finish();
 1306: 
 1307:             $args->{'iterator'} = $it = $navmap->getIterator($firstResource, $finishResource, $filterHash, $condition);
 1308:         } else {
 1309:             $args->{'iterator'} = $it = $navmap->getIterator(undef, undef, $filterHash, $condition);
 1310:         }
 1311:     }
 1312: 
 1313:     # (re-)Locate the jump point, if any
 1314:     # Note this does not take filtering or hidden into account... need
 1315:     # to be fixed?
 1316:     my $mapIterator = $navmap->getIterator(undef, undef, $filterHash, 0);
 1317:     my $curRes;
 1318:     my $foundJump = 0;
 1319:     my $counter = 0;
 1320:     
 1321:     while (($curRes = $mapIterator->next()) && !$foundJump) {
 1322:         if (ref($curRes)) { $counter++; }
 1323:         
 1324:         if (ref($curRes) && $jump eq $curRes->symb()) {
 1325:             
 1326:             # This is why we have to use the main iterator instead of the
 1327:             # potentially faster DFS: The count has to be the same, so
 1328:             # the order has to be the same, which DFS won't give us.
 1329:             $args->{'currentJumpIndex'} = $counter;
 1330:             $foundJump = 1;
 1331:         }
 1332:     }
 1333: 
 1334:     my $showParts = setDefault($args->{'showParts'}, 1);
 1335:     my $condenseParts = setDefault($args->{'condenseParts'}, 1);
 1336:     # keeps track of when the current resource is found,
 1337:     # so we can back up a few and put the anchor above the
 1338:     # current resource
 1339:     my $printKey = $args->{'printKey'};
 1340:     my $printCloseAll = $args->{'printCloseAll'};
 1341:     if (!defined($printCloseAll)) { $printCloseAll = 1; }
 1342:     
 1343:     # Print key?
 1344:     if ($printKey) {
 1345:         $result .= '<table border="0" cellpadding="2" cellspacing="0">';
 1346:         my $date=localtime;
 1347:         $result.='<tr><td align="right" valign="bottom">Key:&nbsp;&nbsp;</td>';
 1348:         if ($navmap->{LAST_CHECK}) {
 1349:             $result .= 
 1350:                 '<img src="/adm/lonMisc/chat.gif"> '.&mt('New discussion since').' '.
 1351:                 strftime("%A, %b %e at %I:%M %P", localtime($navmap->{LAST_CHECK})).
 1352:                 '</td><td align="center" valign="bottom">&nbsp;&nbsp;'.
 1353:                 '<img src="/adm/lonMisc/feedback.gif"> '.&mt('New message (click to open)').'<p>'.
 1354:                 '</td>'; 
 1355:         } else {
 1356:             $result .= '<td align="center" valign="bottom">&nbsp;&nbsp;'.
 1357:                 '<img src="/adm/lonMisc/chat.gif"> '.&mt('Discussions').'</td><td align="center" valign="bottom">'.
 1358:                 '&nbsp;&nbsp;<img src="/adm/lonMisc/feedback.gif"> '.&mt('New message (click to open)').
 1359:                 '</td>'; 
 1360:         }
 1361: 
 1362:         $result .= '</tr></table>';
 1363:     }
 1364: 
 1365:     if ($printCloseAll && !$args->{'resource_no_folder_link'}) {
 1366:         if ($condition) {
 1367:             $result.="<a href=\"navmaps?condition=0&filter=&$queryString" .
 1368:                 "&here=" . Apache::lonnet::escape($here) .
 1369:                 "\">".&mt('Close All Folders')."</a>";
 1370:         } else {
 1371:             $result.="<a href=\"navmaps?condition=1&filter=&$queryString" .
 1372:                 "&here=" . Apache::lonnet::escape($here) . 
 1373:                 "\">".&mt('Open All Folders')."</a>";
 1374:         }
 1375:         $result .= "<br /><br />\n";
 1376:     }    
 1377: 
 1378:     if ($r) {
 1379:         $r->print($result);
 1380:         $r->rflush();
 1381:         $result = "";
 1382:     }
 1383:     # End parameter setting
 1384:             
 1385:     # Data
 1386:     $result .= '<table cellspacing="0" cellpadding="3" border="0" bgcolor="#FFFFFF">' ."\n";
 1387:     my $res = "Apache::lonnavmaps::resource";
 1388:     my %condenseStatuses =
 1389:         ( $res->NETWORK_FAILURE    => 1,
 1390:           $res->NOTHING_SET        => 1,
 1391:           $res->CORRECT            => 1 );
 1392:     my @backgroundColors = ("#FFFFFF", "#F6F6F6");
 1393: 
 1394:     # Shared variables
 1395:     $args->{'counter'} = 0; # counts the rows
 1396:     $args->{'indentLevel'} = 0;
 1397:     $args->{'isNewBranch'} = 0;
 1398:     $args->{'condensed'} = 0;    
 1399:     $args->{'indentString'} = setDefault($args->{'indentString'}, "<img src='/adm/lonIcons/whitespace1.gif' width='25' height='1' alt='' border='0' />");
 1400:     $args->{'displayedHereMarker'} = 0;
 1401: 
 1402:     # If we're suppressing empty sequences, look for them here. Use DFS for speed,
 1403:     # since structure actually doesn't matter, except what map has what resources.
 1404:     if ($args->{'suppressEmptySequences'}) {
 1405:         my $dfsit = Apache::lonnavmaps::DFSiterator->new($navmap,
 1406:                                                          $it->{FIRST_RESOURCE},
 1407:                                                          $it->{FINISH_RESOURCE},
 1408:                                                          {}, undef, 1);
 1409:         my $depth = 0;
 1410:         $dfsit->next();
 1411:         my $curRes = $dfsit->next();
 1412:         while ($depth > -1) {
 1413:             if ($curRes == $dfsit->BEGIN_MAP()) { $depth++; }
 1414:             if ($curRes == $dfsit->END_MAP()) { $depth--; }
 1415: 
 1416:             if (ref($curRes)) { 
 1417:                 # Parallel pre-processing: Do sequences have non-filtered-out children?
 1418:                 if ($curRes->is_map()) {
 1419:                     $curRes->{DATA}->{HAS_VISIBLE_CHILDREN} = 0;
 1420:                     # Sequences themselves do not count as visible children,
 1421:                     # unless those sequences also have visible children.
 1422:                     # This means if a sequence appears, there's a "promise"
 1423:                     # that there's something under it if you open it, somewhere.
 1424:                 } else {
 1425:                     # Not a sequence: if it's filtered, ignore it, otherwise
 1426:                     # rise up the stack and mark the sequences as having children
 1427:                     if (&$filterFunc($curRes)) {
 1428:                         for my $sequence (@{$dfsit->getStack()}) {
 1429:                             $sequence->{DATA}->{HAS_VISIBLE_CHILDREN} = 1;
 1430:                         }
 1431:                     }
 1432:                 }
 1433:             }
 1434:         } continue {
 1435:             $curRes = $dfsit->next();
 1436:         }
 1437:     }
 1438: 
 1439:     my $displayedJumpMarker = 0;
 1440:     # Set up iteration.
 1441:     my $now = time();
 1442:     my $in24Hours = $now + 24 * 60 * 60;
 1443:     my $rownum = 0;
 1444: 
 1445:     # export "here" marker information
 1446:     $args->{'here'} = $here;
 1447: 
 1448:     $args->{'indentLevel'} = -1; # first BEGIN_MAP takes this to 0
 1449:     while ($curRes = $it->next($closeAllPages)) {
 1450:         # Maintain indentation level.
 1451:         if ($curRes == $it->BEGIN_MAP() ||
 1452:             $curRes == $it->BEGIN_BRANCH() ) {
 1453:             $args->{'indentLevel'}++;
 1454:         }
 1455:         if ($curRes == $it->END_MAP() ||
 1456:             $curRes == $it->END_BRANCH() ) {
 1457:             $args->{'indentLevel'}--;
 1458:         }
 1459:         # Notice new branches
 1460:         if ($curRes == $it->BEGIN_BRANCH()) {
 1461:             $args->{'isNewBranch'} = 1;
 1462:         }
 1463: 
 1464:         # If this isn't an actual resource, continue on
 1465:         if (!ref($curRes)) {
 1466:             next;
 1467:         }
 1468: 
 1469:         # If this has been filtered out, continue on
 1470:         if (!(&$filterFunc($curRes))) {
 1471:             $args->{'isNewBranch'} = 0; # Don't falsely remember this
 1472:             next;
 1473:         } 
 1474: 
 1475:         # If this is an empty sequence and we're filtering them, continue on
 1476:         if ($curRes->is_map() && $args->{'suppressEmptySequences'} &&
 1477:             !$curRes->{DATA}->{HAS_VISIBLE_CHILDREN}) {
 1478:             next;
 1479:         }
 1480: 
 1481:         # If we're suppressing navmaps and this is a navmap, continue on
 1482:         if ($suppressNavmap && $curRes->src() =~ /^\/adm\/navmaps/) {
 1483:             next;
 1484:         }
 1485: 
 1486:         $args->{'counter'}++;
 1487: 
 1488:         # Does it have multiple parts?
 1489:         $args->{'multipart'} = 0;
 1490:         $args->{'condensed'} = 0;
 1491:         my @parts;
 1492:             
 1493:         # Decide what parts to show.
 1494:         if ($curRes->is_problem() && $showParts) {
 1495:             @parts = @{$curRes->parts()};
 1496:             $args->{'multipart'} = $curRes->multipart();
 1497:             
 1498:             if ($condenseParts) { # do the condensation
 1499:                 if (!$curRes->opendate("0")) {
 1500:                     @parts = ();
 1501:                     $args->{'condensed'} = 1;
 1502:                 }
 1503:                 if (!$args->{'condensed'}) {
 1504:                     # Decide whether to condense based on similarity
 1505:                     my $status = $curRes->status($parts[0]);
 1506:                     my $due = $curRes->duedate($parts[0]);
 1507:                     my $open = $curRes->opendate($parts[0]);
 1508:                     my $statusAllSame = 1;
 1509:                     my $dueAllSame = 1;
 1510:                     my $openAllSame = 1;
 1511:                     for (my $i = 1; $i < scalar(@parts); $i++) {
 1512:                         if ($curRes->status($parts[$i]) != $status){
 1513:                             $statusAllSame = 0;
 1514:                         }
 1515:                         if ($curRes->duedate($parts[$i]) != $due ) {
 1516:                             $dueAllSame = 0;
 1517:                         }
 1518:                         if ($curRes->opendate($parts[$i]) != $open) {
 1519:                             $openAllSame = 0;
 1520:                         }
 1521:                     }
 1522:                     # $*allSame is true if all the statuses were
 1523:                     # the same. Now, if they are all the same and
 1524:                     # match one of the statuses to condense, or they
 1525:                     # are all open with the same due date, or they are
 1526:                     # all OPEN_LATER with the same open date, display the
 1527:                     # status of the first non-zero part (to get the 'correct'
 1528:                     # status right, since 0 is never 'correct' or 'open').
 1529:                     if (($statusAllSame && defined($condenseStatuses{$status})) ||
 1530:                         ($dueAllSame && $status == $curRes->OPEN && $statusAllSame)||
 1531:                         ($openAllSame && $status == $curRes->OPEN_LATER && $statusAllSame) ){
 1532:                         @parts = ($parts[0]);
 1533:                         $args->{'condensed'} = 1;
 1534:                     }
 1535:                 }
 1536: 		# Multipart problem with one part: always "condense" (happens
 1537: 		#  to match the desirable behavior)
 1538: 		if ($curRes->countParts() == 1) {
 1539: 		    @parts = ($parts[0]);
 1540: 		    $args->{'condensed'} = 1;
 1541: 		}
 1542:             }
 1543:         } 
 1544:             
 1545:         # If the multipart problem was condensed, "forget" it was multipart
 1546:         if (scalar(@parts) == 1) {
 1547:             $args->{'multipart'} = 0;
 1548:         } else {
 1549:             # Add part 0 so we display it correctly.
 1550:             unshift @parts, '0';
 1551:         }
 1552: 
 1553:         # Now, we've decided what parts to show. Loop through them and
 1554:         # show them.
 1555:         foreach my $part (@parts) {
 1556:             $rownum ++;
 1557:             my $backgroundColor = $backgroundColors[$rownum % scalar(@backgroundColors)];
 1558:             
 1559:             $result .= "  <tr bgcolor='$backgroundColor'>\n";
 1560: 
 1561:             # Set up some data about the parts that the cols might want
 1562:             my $filter = $it->{FILTER};
 1563:             my $stack = $it->getStack();
 1564:             my $src = getLinkForResource($stack);
 1565:             my $anchor='';
 1566:             if ($src=~s/(\#.*$)//) {
 1567: 		$anchor=$1;
 1568: 	    }
 1569:             my $srcHasQuestion = $src =~ /\?/;
 1570:             $args->{"resourceLink"} = $src.
 1571:                 ($srcHasQuestion?'&':'?') .
 1572:                 'symb=' . &Apache::lonnet::escape($curRes->symb()).
 1573: 		$anchor;
 1574:             
 1575:             # Now, display each column.
 1576:             foreach my $col (@$cols) {
 1577:                 my $colHTML = '';
 1578:                 if (ref($col)) {
 1579:                     $colHTML .= &$col($curRes, $part, $args);
 1580:                 } else {
 1581:                     $colHTML .= &{$preparedColumns[$col]}($curRes, $part, $args);
 1582:                 }
 1583: 
 1584:                 # If this is the first column and it's time to print
 1585:                 # the anchor, do so
 1586:                 if ($col == $cols->[0] && 
 1587:                     $args->{'counter'} == $args->{'currentJumpIndex'} - 
 1588:                     $currentJumpDelta) {
 1589:                     # Jam the anchor after the <td> tag;
 1590:                     # necessary for valid HTML (which Mozilla requires)
 1591:                     $colHTML =~ s/\>/\>\<a name="curloc" \/\>/;
 1592:                     $displayedJumpMarker = 1;
 1593:                 }
 1594:                 $result .= $colHTML . "\n";
 1595:             }
 1596:             $result .= "    </tr>\n";
 1597:             $args->{'isNewBranch'} = 0;
 1598:         }
 1599: 
 1600:         if ($r && $rownum % 20 == 0) {
 1601:             $r->print($result);
 1602:             $result = "";
 1603:             $r->rflush();
 1604:         }
 1605:     } continue {
 1606: 	if ($r) {
 1607: 	    # If we have the connection, make sure the user is still connected
 1608: 	    my $c = $r->connection;
 1609: 	    if ($c->aborted()) {
 1610: 		# Who cares what we do, nobody will see it anyhow.
 1611: 		return '';
 1612: 	    }
 1613: 	}
 1614:     }
 1615:     
 1616:     # Print out the part that jumps to #curloc if it exists
 1617:     # delay needed because the browser is processing the jump before
 1618:     # it finishes rendering, so it goes to the wrong place!
 1619:     # onload might be better, but this routine has no access to that.
 1620:     # On mozilla, the 0-millisecond timeout seems to prevent this;
 1621:     # it's quite likely this might fix other browsers, too, and 
 1622:     # certainly won't hurt anything.
 1623:     if ($displayedJumpMarker) {
 1624:         $result .= "
 1625: <script>
 1626: if (location.href.indexOf('#curloc')==-1) {
 1627:     setTimeout(\"location += '#curloc';\", 0)
 1628: }
 1629: </script>";
 1630:     }
 1631: 
 1632:     $result .= "</table>";
 1633:     
 1634:     if ($r) {
 1635:         $r->print($result);
 1636:         $result = "";
 1637:         $r->rflush();
 1638:     }
 1639:         
 1640:     if ($mustCloseNavMap) { $navmap->untieHashes(); } 
 1641: 
 1642:     return $result;
 1643: }
 1644: 
 1645: 1;
 1646: 
 1647: package Apache::lonnavmaps::navmap;
 1648: 
 1649: =pod
 1650: 
 1651: =head1 Object: Apache::lonnavmaps::navmap
 1652: 
 1653: =head2 Overview
 1654: 
 1655: The navmap object's job is to provide access to the resources
 1656: in the course as Apache::lonnavmaps::resource objects, and to
 1657: query and manage the relationship between those resource objects.
 1658: 
 1659: Generally, you'll use the navmap object in one of three basic ways.
 1660: In order of increasing complexity and power:
 1661: 
 1662: =over 4
 1663: 
 1664: =item * C<$navmap-E<gt>getByX>, where X is B<Id>, B<Symb>, B<Url> or B<MapPc>. This provides
 1665:     various ways to obtain resource objects, based on various identifiers.
 1666:     Use this when you want to request information about one object or 
 1667:     a handful of resources you already know the identities of, from some
 1668:     other source. For more about Ids, Symbs, and MapPcs, see the
 1669:     Resource documentation. Note that Url should be a B<last resort>,
 1670:     not your first choice; it only works when there is only one
 1671:     instance of the resource in the course, which only applies to
 1672:     maps, and even that may change in the future.
 1673: 
 1674: =item * C<my @resources = $navmap-E<gt>retrieveResources(args)>. This
 1675:     retrieves resources matching some criterion and returns them
 1676:     in a flat array, with no structure information. Use this when
 1677:     you are manipulating a series of resources, based on what map
 1678:     the are in, but do not care about branching, or exactly how
 1679:     the maps and resources are related. This is the most common case.
 1680: 
 1681: =item * C<$it = $navmap-E<gt>getIterator(args)>. This allows you traverse
 1682:     the course's navmap in various ways without writing the traversal
 1683:     code yourself. See iterator documentation below. Use this when
 1684:     you need to know absolutely everything about the course, including
 1685:     branches and the precise relationship between maps and resources.
 1686: 
 1687: =back
 1688: 
 1689: =head2 Creation And Destruction
 1690: 
 1691: To create a navmap object, use the following function:
 1692: 
 1693: =over 4
 1694: 
 1695: =item * B<Apache::lonnavmaps::navmap-E<gt>new>():
 1696: 
 1697: Creates a new navmap object. Returns the navmap object if this is
 1698: successful, or B<undef> if not.
 1699: 
 1700: =back
 1701: 
 1702: When you are done with the $navmap object, you I<must> call 
 1703: $navmap->untieHashes(), or you'll prevent the current user from using that 
 1704: course until the web server is restarted. (!)
 1705: 
 1706: =head2 Methods
 1707: 
 1708: =over 4
 1709: 
 1710: =item * B<getIterator>(first, finish, filter, condition):
 1711: 
 1712: See iterator documentation below.
 1713: 
 1714: =cut
 1715: 
 1716: use strict;
 1717: use GDBM_File;
 1718: 
 1719: sub new {
 1720:     # magic invocation to create a class instance
 1721:     my $proto = shift;
 1722:     my $class = ref($proto) || $proto;
 1723:     my $self = {};
 1724: 
 1725:     # Resource cache stores navmap resources as we reference them. We generate
 1726:     # them on-demand so we don't pay for creating resources unless we use them.
 1727:     $self->{RESOURCE_CACHE} = {};
 1728: 
 1729:     # Network failure flag, if we accessed the course or user opt and
 1730:     # failed
 1731:     $self->{NETWORK_FAILURE} = 0;
 1732: 
 1733:     # tie the nav hash
 1734: 
 1735:     my %navmaphash;
 1736:     my %parmhash;
 1737:     my $courseFn = $ENV{"request.course.fn"};
 1738:     if (!(tie(%navmaphash, 'GDBM_File', "${courseFn}.db",
 1739:               &GDBM_READER(), 0640))) {
 1740:         return undef;
 1741:     }
 1742:     
 1743:     if (!(tie(%parmhash, 'GDBM_File', "${courseFn}_parms.db",
 1744:               &GDBM_READER(), 0640)))
 1745:     {
 1746:         untie %{$self->{PARM_HASH}};
 1747:         return undef;
 1748:     }
 1749: 
 1750:     $self->{NAV_HASH} = \%navmaphash;
 1751:     $self->{PARM_HASH} = \%parmhash;
 1752:     $self->{PARM_CACHE} = {};
 1753: 
 1754:     bless($self);
 1755:         
 1756:     return $self;
 1757: }
 1758: 
 1759: sub generate_course_user_opt {
 1760:     my $self = shift;
 1761:     if ($self->{COURSE_USER_OPT_GENERATED}) { return; }
 1762: 
 1763:     my $uname=$ENV{'user.name'};
 1764:     my $udom=$ENV{'user.domain'};
 1765:     my $uhome=$ENV{'user.home'};
 1766:     my $cid=$ENV{'request.course.id'};
 1767:     my $chome=$ENV{'course.'.$cid.'.home'};
 1768:     my ($cdom,$cnum)=split(/\_/,$cid);
 1769:     
 1770:     my $userprefix=$uname.'_'.$udom.'_';
 1771:     
 1772:     my %courserdatas; my %useropt; my %courseopt; my %userrdatas;
 1773:     unless ($uhome eq 'no_host') { 
 1774: # ------------------------------------------------- Get coursedata (if present)
 1775: 	unless ((time-$courserdatas{$cid.'.last_cache'})<240) {
 1776: 	    my $reply=&Apache::lonnet::reply('dump:'.$cdom.':'.$cnum.
 1777: 					     ':resourcedata',$chome);
 1778: 	    # Check for network failure
 1779: 	    if ( $reply =~ /no.such.host/i || $reply =~ /con_lost/i) {
 1780: 		$self->{NETWORK_FAILURE} = 1;
 1781: 	    } elsif ($reply!~/^error\:/) {
 1782: 		$courserdatas{$cid}=$reply;
 1783: 		$courserdatas{$cid.'.last_cache'}=time;
 1784: 	    }
 1785: 	}
 1786: 	foreach (split(/\&/,$courserdatas{$cid})) {
 1787: 	    my ($name,$value)=split(/\=/,$_);
 1788: 	    $courseopt{$userprefix.&Apache::lonnet::unescape($name)}=
 1789: 		&Apache::lonnet::unescape($value);
 1790: 	}
 1791: # --------------------------------------------------- Get userdata (if present)
 1792: 	unless ((time-$userrdatas{$uname.'___'.$udom.'.last_cache'})<240) {
 1793: 	    my $reply=&Apache::lonnet::reply('dump:'.$udom.':'.$uname.':resourcedata',$uhome);
 1794: 	    if ($reply!~/^error\:/) {
 1795: 		$userrdatas{$uname.'___'.$udom}=$reply;
 1796: 		$userrdatas{$uname.'___'.$udom.'.last_cache'}=time;
 1797: 	    }
 1798: 	    # check to see if network failed
 1799: 	    elsif ( $reply=~/no.such.host/i || $reply=~/con.*lost/i )
 1800: 	    {
 1801: 		$self->{NETWORK_FAILURE} = 1;
 1802: 	    }
 1803: 	}
 1804: 	foreach (split(/\&/,$userrdatas{$uname.'___'.$udom})) {
 1805: 	    my ($name,$value)=split(/\=/,$_);
 1806: 	    $useropt{$userprefix.&Apache::lonnet::unescape($name)}=
 1807: 		&Apache::lonnet::unescape($value);
 1808: 	}
 1809: 	$self->{COURSE_OPT} = \%courseopt;
 1810: 	$self->{USER_OPT} = \%useropt;
 1811:     }
 1812: 
 1813:     $self->{COURSE_USER_OPT_GENERATED} = 1;
 1814:     
 1815:     return;
 1816: }
 1817: 
 1818: sub generate_email_discuss_status {
 1819:     my $self = shift;
 1820:     if ($self->{EMAIL_DISCUSS_GENERATED}) { return; }
 1821: 
 1822:     my $cid=$ENV{'request.course.id'};
 1823:     my ($cdom,$cnum)=split(/\_/,$cid);
 1824:     
 1825:     my %emailstatus = &Apache::lonnet::dump('email_status');
 1826:     my $logoutTime = $emailstatus{'logout'};
 1827:     my $courseLeaveTime = $emailstatus{'logout_'.$ENV{'request.course.id'}};
 1828:     $self->{LAST_CHECK} = (($courseLeaveTime > $logoutTime) ?
 1829: 			   $courseLeaveTime : $logoutTime);
 1830:     my %discussiontime = &Apache::lonnet::dump('discussiontimes', 
 1831: 					       $cdom, $cnum);
 1832:     my %feedback=();
 1833:     my %error=();
 1834:     my $keys = &Apache::lonnet::reply('keys:'.
 1835: 				      $ENV{'user.domain'}.':'.
 1836: 				      $ENV{'user.name'}.':nohist_email',
 1837: 				      $ENV{'user.home'});
 1838:     
 1839:     foreach my $msgid (split(/\&/, $keys)) {
 1840: 	$msgid=&Apache::lonnet::unescape($msgid);
 1841: 	my $plain=&Apache::lonnet::unescape(&Apache::lonnet::unescape($msgid));
 1842: 	if ($plain=~/(Error|Feedback) \[([^\]]+)\]/) {
 1843: 	    my ($what,$url)=($1,$2);
 1844: 	    my %status=
 1845: 		&Apache::lonnet::get('email_status',[$msgid]);
 1846: 	    if ($status{$msgid}=~/^error\:/) { 
 1847: 		$status{$msgid}=''; 
 1848: 	    }
 1849: 	    
 1850: 	    if (($status{$msgid} eq 'new') || 
 1851: 		(!$status{$msgid})) { 
 1852: 		if ($what eq 'Error') {
 1853: 		    $error{$url}.=','.$msgid; 
 1854: 		} else {
 1855: 		    $feedback{$url}.=','.$msgid;
 1856: 		}
 1857: 	    }
 1858: 	}
 1859:     }
 1860:     
 1861:     $self->{FEEDBACK} = \%feedback;
 1862:     $self->{ERROR_MSG} = \%error; # what is this? JB
 1863:     $self->{DISCUSSION_TIME} = \%discussiontime;
 1864:     $self->{EMAIL_STATUS} = \%emailstatus;
 1865:     
 1866:     $self->{EMAIL_DISCUSS_GENERATED} = 1;
 1867: }
 1868: 
 1869: sub get_user_data {
 1870:     my $self = shift;
 1871:     if ($self->{RETRIEVED_USER_DATA}) { return; }
 1872: 
 1873:     # Retrieve performance data on problems
 1874:     my %student_data = Apache::lonnet::currentdump($ENV{'request.course.id'},
 1875: 						   $ENV{'user.domain'},
 1876: 						   $ENV{'user.name'});
 1877:     $self->{STUDENT_DATA} = \%student_data;
 1878: 
 1879:     $self->{RETRIEVED_USER_DATA} = 1;
 1880: }
 1881: 
 1882: # Internal function: Takes a key to look up in the nav hash and implements internal
 1883: # memory caching of that key.
 1884: sub navhash {
 1885:     my $self = shift; my $key = shift;
 1886:     return $self->{NAV_HASH}->{$key};
 1887: }
 1888: 
 1889: =pod
 1890: 
 1891: =item * B<courseMapDefined>(): Returns true if the course map is defined, 
 1892:     false otherwise. Undefined course maps indicate an error somewhere in
 1893:     LON-CAPA, and you will not be able to proceed with using the navmap.
 1894:     See the B<NAV> screen for an example of using this.
 1895: 
 1896: =cut
 1897: 
 1898: # Checks to see if coursemap is defined, matching test in old lonnavmaps
 1899: sub courseMapDefined {
 1900:     my $self = shift;
 1901:     my $uri = &Apache::lonnet::clutter($ENV{'request.course.uri'});
 1902: 
 1903:     my $firstres = $self->navhash("map_start_$uri");
 1904:     my $lastres = $self->navhash("map_finish_$uri");
 1905:     return $firstres && $lastres;
 1906: }
 1907: 
 1908: sub getIterator {
 1909:     my $self = shift;
 1910:     my $iterator = Apache::lonnavmaps::iterator->new($self, shift, shift,
 1911:                                                      shift, undef, shift);
 1912:     return $iterator;
 1913: }
 1914: 
 1915: # unties the hash when done
 1916: sub untieHashes {
 1917:     my $self = shift;
 1918:     untie %{$self->{NAV_HASH}};
 1919:     untie %{$self->{PARM_HASH}};
 1920: }
 1921: 
 1922: # Private method: Does the given resource (as a symb string) have
 1923: # current discussion? Returns 0 if chat/mail data not extracted.
 1924: sub hasDiscussion {
 1925:     my $self = shift;
 1926:     my $symb = shift;
 1927:     
 1928:     $self->generate_email_discuss_status();
 1929: 
 1930:     if (!defined($self->{DISCUSSION_TIME})) { return 0; }
 1931: 
 1932:     #return defined($self->{DISCUSSION_TIME}->{$symb});
 1933:     return $self->{DISCUSSION_TIME}->{$symb} >
 1934:            $self->{LAST_CHECK};
 1935: }
 1936: 
 1937: # Private method: Does the given resource (as a symb string) have
 1938: # current feedback? Returns the string in the feedback hash, which
 1939: # will be false if it does not exist.
 1940: sub getFeedback { 
 1941:     my $self = shift;
 1942:     my $symb = shift;
 1943: 
 1944:     $self->generate_email_discuss_status();
 1945: 
 1946:     if (!defined($self->{FEEDBACK})) { return ""; }
 1947:     
 1948:     return $self->{FEEDBACK}->{$symb};
 1949: }
 1950: 
 1951: # Private method: Get the errors for that resource (by source).
 1952: sub getErrors { 
 1953:     my $self = shift;
 1954:     my $src = shift;
 1955: 
 1956:     $self->generate_email_discuss_status();
 1957: 
 1958:     if (!defined($self->{ERROR_MSG})) { return ""; }
 1959:     return $self->{ERROR_MSG}->{$src};
 1960: }
 1961: 
 1962: =pod
 1963: 
 1964: =item * B<getById>(id):
 1965: 
 1966: Based on the ID of the resource (1.1, 3.2, etc.), get a resource
 1967: object for that resource. This method, or other methods that use it
 1968: (as in the resource object) is the only proper way to obtain a
 1969: resource object.
 1970: 
 1971: =item * B<getBySymb>(symb):
 1972: 
 1973: Based on the symb of the resource, get a resource object for that
 1974: resource. This is one of the proper ways to get a resource object.
 1975: 
 1976: =item * B<getMapByMapPc>(map_pc):
 1977: 
 1978: Based on the map_pc of the resource, get a resource object for
 1979: the given map. This is one of the proper ways to get a resource object.
 1980: 
 1981: =cut
 1982: 
 1983: # The strategy here is to cache the resource objects, and only construct them
 1984: # as we use them. The real point is to prevent reading any more from the tied
 1985: # hash then we have to, which should hopefully alleviate speed problems.
 1986: 
 1987: sub getById {
 1988:     my $self = shift;
 1989:     my $id = shift;
 1990: 
 1991:     if (defined ($self->{RESOURCE_CACHE}->{$id}))
 1992:     {
 1993:         return $self->{RESOURCE_CACHE}->{$id};
 1994:     }
 1995: 
 1996:     # resource handles inserting itself into cache.
 1997:     # Not clear why the quotes are necessary, but as of this
 1998:     # writing it doesn't work without them.
 1999:     return "Apache::lonnavmaps::resource"->new($self, $id);
 2000: }
 2001: 
 2002: sub getBySymb {
 2003:     my $self = shift;
 2004:     my $symb = shift;
 2005:     my ($mapUrl, $id, $filename) = &Apache::lonnet::decode_symb($symb);
 2006:     my $map = $self->getResourceByUrl($mapUrl);
 2007:     return $self->getById($map->map_pc() . '.' . $id);
 2008: }
 2009: 
 2010: sub getByMapPc {
 2011:     my $self = shift;
 2012:     my $map_pc = shift;
 2013:     my $map_id = $self->{NAV_HASH}->{'map_id_' . $map_pc};
 2014:     $map_id = $self->{NAV_HASH}->{'ids_' . $map_id};
 2015:     return $self->getById($map_id);
 2016: }
 2017: 
 2018: =pod
 2019: 
 2020: =item * B<firstResource>():
 2021: 
 2022: Returns a resource object reference corresponding to the first
 2023: resource in the navmap.
 2024: 
 2025: =cut
 2026: 
 2027: sub firstResource {
 2028:     my $self = shift;
 2029:     my $firstResource = $self->navhash('map_start_' .
 2030:                      &Apache::lonnet::clutter($ENV{'request.course.uri'}));
 2031:     return $self->getById($firstResource);
 2032: }
 2033: 
 2034: =pod
 2035: 
 2036: =item * B<finishResource>():
 2037: 
 2038: Returns a resource object reference corresponding to the last resource
 2039: in the navmap.
 2040: 
 2041: =cut
 2042: 
 2043: sub finishResource {
 2044:     my $self = shift;
 2045:     my $firstResource = $self->navhash('map_finish_' .
 2046:                      &Apache::lonnet::clutter($ENV{'request.course.uri'}));
 2047:     return $self->getById($firstResource);
 2048: }
 2049: 
 2050: # Parmval reads the parm hash and cascades the lookups. parmval_real does
 2051: # the actual lookup; parmval caches the results.
 2052: sub parmval {
 2053:     my $self = shift;
 2054:     my ($what,$symb)=@_;
 2055:     my $hashkey = $what."|||".$symb;
 2056: 
 2057:     if (defined($self->{PARM_CACHE}->{$hashkey})) {
 2058:         return $self->{PARM_CACHE}->{$hashkey};
 2059:     }
 2060: 
 2061:     my $result = $self->parmval_real($what, $symb);
 2062:     $self->{PARM_CACHE}->{$hashkey} = $result;
 2063:     return $result;
 2064: }
 2065: 
 2066: sub parmval_real {
 2067:     my $self = shift;
 2068:     my ($what,$symb,$recurse) = @_;
 2069: 
 2070:     # Make sure the {USER_OPT} and {COURSE_OPT} hashes are populated
 2071:     $self->generate_course_user_opt();
 2072: 
 2073:     my $cid=$ENV{'request.course.id'};
 2074:     my $csec=$ENV{'request.course.sec'};
 2075:     my $uname=$ENV{'user.name'};
 2076:     my $udom=$ENV{'user.domain'};
 2077: 
 2078:     unless ($symb) { return ''; }
 2079:     my $result='';
 2080: 
 2081:     my ($mapname,$id,$fn)=&Apache::lonnet::decode_symb($symb);
 2082: 
 2083: # ----------------------------------------------------- Cascading lookup scheme
 2084:     my $rwhat=$what;
 2085:     $what=~s/^parameter\_//;
 2086:     $what=~s/\_/\./;
 2087: 
 2088:     my $symbparm=$symb.'.'.$what;
 2089:     my $mapparm=$mapname.'___(all).'.$what;
 2090:     my $usercourseprefix=$uname.'_'.$udom.'_'.$cid;
 2091: 
 2092:     my $seclevel= $usercourseprefix.'.['.$csec.'].'.$what;
 2093:     my $seclevelr=$usercourseprefix.'.['.$csec.'].'.$symbparm;
 2094:     my $seclevelm=$usercourseprefix.'.['.$csec.'].'.$mapparm;
 2095: 
 2096:     my $courselevel= $usercourseprefix.'.'.$what;
 2097:     my $courselevelr=$usercourseprefix.'.'.$symbparm;
 2098:     my $courselevelm=$usercourseprefix.'.'.$mapparm;
 2099: 
 2100:     my $useropt = $self->{USER_OPT};
 2101:     my $courseopt = $self->{COURSE_OPT};
 2102:     my $parmhash = $self->{PARM_HASH};
 2103: 
 2104: # ---------------------------------------------------------- first, check user
 2105:     if ($uname and defined($useropt)) {
 2106:         if (defined($$useropt{$courselevelr})) { return $$useropt{$courselevelr}; }
 2107:         if (defined($$useropt{$courselevelm})) { return $$useropt{$courselevelm}; }
 2108:         if (defined($$useropt{$courselevel})) { return $$useropt{$courselevel}; }
 2109:     }
 2110: 
 2111: # ------------------------------------------------------- second, check course
 2112:     if ($csec and defined($courseopt)) {
 2113:         if (defined($$courseopt{$seclevelr})) { return $$courseopt{$seclevelr}; }
 2114:         if (defined($$courseopt{$seclevelm})) { return $$courseopt{$seclevelm}; }
 2115:         if (defined($$courseopt{$seclevel})) { return $$courseopt{$seclevel}; }
 2116:     }
 2117: 
 2118:     if (defined($courseopt)) {
 2119:         if (defined($$courseopt{$courselevelr})) { return $$courseopt{$courselevelr}; }
 2120:         if (defined($$courseopt{$courselevelm})) { return $$courseopt{$courselevelm}; }
 2121:         if (defined($$courseopt{$courselevel})) { return $$courseopt{$courselevel}; }
 2122:     }
 2123: 
 2124: # ----------------------------------------------------- third, check map parms
 2125: 
 2126:     my $thisparm=$$parmhash{$symbparm};
 2127:     if (defined($thisparm)) { return $thisparm; }
 2128: 
 2129: # ----------------------------------------------------- fourth , check default
 2130: 
 2131:     my $meta_rwhat=$rwhat;
 2132:     $meta_rwhat=~s/\./_/g;
 2133:     my $default=&Apache::lonnet::metadata($fn,$meta_rwhat);
 2134:     if (defined($default)) { return $default}
 2135:     $default=&Apache::lonnet::metadata($fn,'parameter_'.$meta_rwhat);
 2136:     if (defined($default)) { return $default}
 2137: 
 2138: # --------------------------------------------------- fifth , cascade up parts
 2139: 
 2140:     my ($space,@qualifier)=split(/\./,$rwhat);
 2141:     my $qualifier=join('.',@qualifier);
 2142:     unless ($space eq '0') {
 2143: 	my @parts=split(/_/,$space);
 2144: 	my $id=pop(@parts);
 2145: 	my $part=join('_',@parts);
 2146: 	if ($part eq '') { $part='0'; }
 2147: 	my $partgeneral=$self->parmval($part.".$qualifier",$symb,1);
 2148: 	if (defined($partgeneral)) { return $partgeneral; }
 2149:     }
 2150:     if ($recurse) { return undef; }
 2151:     my $pack_def=&Apache::lonnet::packages_tab_default($fn,'resource.'.$what);
 2152:     if (defined($pack_def)) { return $pack_def; }
 2153:     return '';
 2154: }
 2155: 
 2156: =pod
 2157: 
 2158: =item * B<getResourceByUrl>(url):
 2159: 
 2160: Retrieves a resource object by URL of the resource. If passed a
 2161: resource object, it will simply return it, so it is safe to use this
 2162: method in code like "$res = $navmap->getResourceByUrl($res)", if
 2163: you're not sure if $res is already an object, or just a URL. If the
 2164: resource appears multiple times in the course, only the first instance
 2165: will be returned. As a result, this is probably useful only for maps.
 2166: 
 2167: =item * B<retrieveResources>(map, filterFunc, recursive, bailout):
 2168: 
 2169: The map is a specification of a map to retreive the resources from,
 2170: either as a url or as an object. The filterFunc is a reference to a
 2171: function that takes a resource object as its one argument and returns
 2172: true if the resource should be included, or false if it should not
 2173: be. If recursive is true, the map will be recursively examined,
 2174: otherwise it will not be. If bailout is true, the function will return
 2175: as soon as it finds a resource, if false it will finish. By default,
 2176: the map is the top-level map of the course, filterFunc is a function
 2177: that always returns 1, recursive is true, bailout is false. The
 2178: resources will be returned in a list containing the resource objects
 2179: for the corresponding resources, with B<no structure information> in
 2180: the list; regardless of branching, recursion, etc., it will be a flat
 2181: list.
 2182: 
 2183: Thus, this is suitable for cases where you don't want the structure,
 2184: just a list of all resources. It is also suitable for finding out how
 2185: many resources match a given description; for this use, if all you
 2186: want to know is if I<any> resources match the description, the bailout
 2187: parameter will allow you to avoid potentially expensive enumeration of
 2188: all matching resources.
 2189: 
 2190: =item * B<hasResource>(map, filterFunc, recursive):
 2191: 
 2192: Convience method for
 2193: 
 2194:  scalar(retrieveResources($map, $filterFunc, $recursive, 1)) > 0
 2195: 
 2196: which will tell whether the map has resources matching the description
 2197: in the filter function.
 2198: 
 2199: =cut
 2200: 
 2201: sub getResourceByUrl {
 2202:     my $self = shift;
 2203:     my $resUrl = shift;
 2204: 
 2205:     if (ref($resUrl)) { return $resUrl; }
 2206: 
 2207:     $resUrl = &Apache::lonnet::clutter($resUrl);
 2208:     my $resId = $self->{NAV_HASH}->{'ids_' . $resUrl};
 2209:     if ($resId =~ /,/) {
 2210:         $resId = (split (/,/, $resId))[0];
 2211:     }
 2212:     if (!$resId) { return ''; }
 2213:     return $self->getById($resId);
 2214: }
 2215: 
 2216: sub retrieveResources {
 2217:     my $self = shift;
 2218:     my $map = shift;
 2219:     my $filterFunc = shift;
 2220:     if (!defined ($filterFunc)) {
 2221:         $filterFunc = sub {return 1;};
 2222:     }
 2223:     my $recursive = shift;
 2224:     if (!defined($recursive)) { $recursive = 1; }
 2225:     my $bailout = shift;
 2226:     if (!defined($bailout)) { $bailout = 0; }
 2227: 
 2228:     # Create the necessary iterator.
 2229:     if (!ref($map)) { # assume it's a url of a map.
 2230:         $map = $self->getResourceByUrl($map);
 2231:     }
 2232: 
 2233:     # If nothing was passed, assume top-level map
 2234:     if (!$map) {
 2235: 	$map = $self->getById('0.0');
 2236:     }
 2237: 
 2238:     # Check the map's validity.
 2239:     if (!$map->is_map()) {
 2240:         # Oh, to throw an exception.... how I'd love that!
 2241:         return ();
 2242:     }
 2243: 
 2244:     # Get an iterator.
 2245:     my $it = $self->getIterator($map->map_start(), $map->map_finish(),
 2246:                                 undef, $recursive);
 2247: 
 2248:     my @resources = ();
 2249: 
 2250:     # Run down the iterator and collect the resources.
 2251:     my $curRes;
 2252: 
 2253:     while ($curRes = $it->next()) {
 2254:         if (ref($curRes)) {
 2255:             if (!&$filterFunc($curRes)) {
 2256:                 next;
 2257:             }
 2258: 
 2259:             push @resources, $curRes;
 2260: 
 2261:             if ($bailout) {
 2262:                 return @resources;
 2263:             }
 2264:         }
 2265: 
 2266:     }
 2267: 
 2268:     return @resources;
 2269: }
 2270: 
 2271: sub hasResource {
 2272:     my $self = shift;
 2273:     my $map = shift;
 2274:     my $filterFunc = shift;
 2275:     my $recursive = shift;
 2276:     
 2277:     return scalar($self->retrieveResources($map, $filterFunc, $recursive, 1)) > 0;
 2278: }
 2279: 
 2280: 1;
 2281: 
 2282: package Apache::lonnavmaps::iterator;
 2283: 
 2284: =pod
 2285: 
 2286: =back
 2287: 
 2288: =head1 Object: navmap Iterator
 2289: 
 2290: An I<iterator> encapsulates the logic required to traverse a data
 2291: structure. navmap uses an iterator to traverse the course map
 2292: according to the criteria you wish to use.
 2293: 
 2294: To obtain an iterator, call the B<getIterator>() function of a
 2295: B<navmap> object. (Do not instantiate Apache::lonnavmaps::iterator
 2296: directly.) This will return a reference to the iterator:
 2297: 
 2298: C<my $resourceIterator = $navmap-E<gt>getIterator();>
 2299: 
 2300: To get the next thing from the iterator, call B<next>:
 2301: 
 2302: C<my $nextThing = $resourceIterator-E<gt>next()>
 2303: 
 2304: getIterator behaves as follows:
 2305: 
 2306: =over 4
 2307: 
 2308: =item * B<getIterator>(firstResource, finishResource, filterHash, condition, forceTop, returnTopMap):
 2309: 
 2310: All parameters are optional. firstResource is a resource reference
 2311: corresponding to where the iterator should start. It defaults to
 2312: navmap->firstResource() for the corresponding nav map. finishResource
 2313: corresponds to where you want the iterator to end, defaulting to
 2314: navmap->finishResource(). filterHash is a hash used as a set
 2315: containing strings representing the resource IDs, defaulting to
 2316: empty. Condition is a 1 or 0 that sets what to do with the filter
 2317: hash: If a 0, then only resources that exist IN the filterHash will be
 2318: recursed on. If it is a 1, only resources NOT in the filterHash will
 2319: be recursed on. Defaults to 0. forceTop is a boolean value. If it is
 2320: false (default), the iterator will only return the first level of map
 2321: that is not just a single, 'redirecting' map. If true, the iterator
 2322: will return all information, starting with the top-level map,
 2323: regardless of content. returnTopMap, if true (default false), will
 2324: cause the iterator to return the top-level map object (resource 0.0)
 2325: before anything else.
 2326: 
 2327: Thus, by default, only top-level resources will be shown. Change the
 2328: condition to a 1 without changing the hash, and all resources will be
 2329: shown. Changing the condition to 1 and including some values in the
 2330: hash will allow you to selectively suppress parts of the navmap, while
 2331: leaving it on 0 and adding things to the hash will allow you to
 2332: selectively add parts of the nav map. See the handler code for
 2333: examples.
 2334: 
 2335: The iterator will return either a reference to a resource object, or a
 2336: token representing something in the map, such as the beginning of a
 2337: new branch. The possible tokens are:
 2338: 
 2339: =over 4
 2340: 
 2341: =item * B<END_ITERATOR>:
 2342: 
 2343: The iterator has returned all that it's going to. Further calls to the
 2344: iterator will just produce more of these. This is a "false" value, and
 2345: is the only false value the iterator which will be returned, so it can
 2346: be used as a loop sentinel.
 2347: 
 2348: =item * B<BEGIN_MAP>:
 2349: 
 2350: A new map is being recursed into. This is returned I<after> the map
 2351: resource itself is returned.
 2352: 
 2353: =item * B<END_MAP>:
 2354: 
 2355: The map is now done.
 2356: 
 2357: =item * B<BEGIN_BRANCH>:
 2358: 
 2359: A branch is now starting. The next resource returned will be the first
 2360: in that branch.
 2361: 
 2362: =item * B<END_BRANCH>:
 2363: 
 2364: The branch is now done.
 2365: 
 2366: =back
 2367: 
 2368: The tokens are retreivable via methods on the iterator object, i.e.,
 2369: $iterator->END_MAP.
 2370: 
 2371: Maps can contain empty resources. The iterator will automatically skip
 2372: over such resources, but will still treat the structure
 2373: correctly. Thus, a complicated map with several branches, but
 2374: consisting entirely of empty resources except for one beginning or
 2375: ending resource, will cause a lot of BRANCH_STARTs and BRANCH_ENDs,
 2376: but only one resource will be returned.
 2377: 
 2378: =back
 2379: 
 2380: =head2 Normal Usage
 2381: 
 2382: Normal usage of the iterator object is to do the following:
 2383: 
 2384:  my $it = $navmap->getIterator([your params here]);
 2385:  my $curRes;
 2386:  while ($curRes = $it->next()) {
 2387:    [your logic here]
 2388:  }
 2389: 
 2390: Note that inside of the loop, it's frequently useful to check if
 2391: "$curRes" is a reference or not with the reference function; only
 2392: resource objects will be references, and any non-references will 
 2393: be the tokens described above.
 2394: 
 2395: Also note there is some old code floating around that trys to track
 2396: the depth of the iterator to see when it's done; do not copy that 
 2397: code. It is difficult to get right and harder to understand then
 2398: this. They should be migrated to this new style.
 2399: 
 2400: =cut
 2401: 
 2402: # Here are the tokens for the iterator:
 2403: 
 2404: sub END_ITERATOR { return 0; }
 2405: sub BEGIN_MAP { return 1; }    # begining of a new map
 2406: sub END_MAP { return 2; }      # end of the map
 2407: sub BEGIN_BRANCH { return 3; } # beginning of a branch
 2408: sub END_BRANCH { return 4; }   # end of a branch
 2409: sub FORWARD { return 1; }      # go forward
 2410: sub BACKWARD { return 2; }
 2411: 
 2412: sub min {
 2413:     (my $a, my $b) = @_;
 2414:     if ($a < $b) { return $a; } else { return $b; }
 2415: }
 2416: 
 2417: sub new {
 2418:     # magic invocation to create a class instance
 2419:     my $proto = shift;
 2420:     my $class = ref($proto) || $proto;
 2421:     my $self = {};
 2422: 
 2423:     $self->{NAV_MAP} = shift;
 2424:     return undef unless ($self->{NAV_MAP});
 2425: 
 2426:     # Handle the parameters
 2427:     $self->{FIRST_RESOURCE} = shift || $self->{NAV_MAP}->firstResource();
 2428:     $self->{FINISH_RESOURCE} = shift || $self->{NAV_MAP}->finishResource();
 2429: 
 2430:     # If the given resources are just the ID of the resource, get the
 2431:     # objects
 2432:     if (!ref($self->{FIRST_RESOURCE})) { $self->{FIRST_RESOURCE} = 
 2433:              $self->{NAV_MAP}->getById($self->{FIRST_RESOURCE}); }
 2434:     if (!ref($self->{FINISH_RESOURCE})) { $self->{FINISH_RESOURCE} = 
 2435:              $self->{NAV_MAP}->getById($self->{FINISH_RESOURCE}); }
 2436: 
 2437:     $self->{FILTER} = shift;
 2438: 
 2439:     # A hash, used as a set, of resource already seen
 2440:     $self->{ALREADY_SEEN} = shift;
 2441:     if (!defined($self->{ALREADY_SEEN})) { $self->{ALREADY_SEEN} = {} };
 2442:     $self->{CONDITION} = shift;
 2443: 
 2444:     # Do we want to automatically follow "redirection" maps?
 2445:     $self->{FORCE_TOP} = shift;
 2446: 
 2447:     # Do we want to return the top-level map object (resource 0.0)?
 2448:     $self->{RETURN_0} = shift;
 2449:     # have we done that yet?
 2450:     $self->{HAVE_RETURNED_0} = 0;
 2451: 
 2452:     # Now, we need to pre-process the map, by walking forward and backward
 2453:     # over the parts of the map we're going to look at.
 2454: 
 2455:     # The processing steps are exactly the same, except for a few small 
 2456:     # changes, so I bundle those up in the following list of two elements:
 2457:     # (direction_to_iterate, VAL_name, next_resource_method_to_call,
 2458:     # first_resource).
 2459:     # This prevents writing nearly-identical code twice.
 2460:     my @iterations = ( [FORWARD(), 'TOP_DOWN_VAL', 'getNext', 
 2461:                         'FIRST_RESOURCE'],
 2462:                        [BACKWARD(), 'BOT_UP_VAL', 'getPrevious', 
 2463:                         'FINISH_RESOURCE'] );
 2464: 
 2465:     my $maxDepth = 0; # tracks max depth
 2466: 
 2467:     # If there is only one resource in this map, and it's a map, we
 2468:     # want to remember that, so the user can ask for the first map
 2469:     # that isn't just a redirector.
 2470:     my $resource; my $resourceCount = 0;
 2471: 
 2472:     # Documentation on this algorithm can be found in the CVS repository at 
 2473:     # /docs/lonnavdocs; these "**#**" markers correspond to documentation
 2474:     # in that file.
 2475:     # **1**
 2476: 
 2477:     foreach my $pass (@iterations) {
 2478:         my $direction = $pass->[0];
 2479:         my $valName = $pass->[1];
 2480:         my $nextResourceMethod = $pass->[2];
 2481:         my $firstResourceName = $pass->[3];
 2482: 
 2483:         my $iterator = Apache::lonnavmaps::DFSiterator->new($self->{NAV_MAP}, 
 2484:                                                             $self->{FIRST_RESOURCE},
 2485:                                                             $self->{FINISH_RESOURCE},
 2486:                                                             {}, undef, 0, $direction);
 2487:     
 2488:         # prime the recursion
 2489:         $self->{$firstResourceName}->{DATA}->{$valName} = 0;
 2490: 	$iterator->next();
 2491:         my $curRes = $iterator->next();
 2492: 	my $depth = 1;
 2493:         while ($depth > 0) {
 2494: 	    if ($curRes == $iterator->BEGIN_MAP()) { $depth++; }
 2495: 	    if ($curRes == $iterator->END_MAP()) { $depth--; }
 2496: 
 2497:             if (ref($curRes)) {
 2498:                 # If there's only one resource, this will save it
 2499:                 # we have to filter empty resources from consideration here,
 2500:                 # or even "empty", redirecting maps have two (start & finish)
 2501:                 # or three (start, finish, plus redirector)
 2502:                 if($direction == FORWARD && $curRes->src()) { 
 2503:                     $resource = $curRes; $resourceCount++; 
 2504:                 }
 2505:                 my $resultingVal = $curRes->{DATA}->{$valName};
 2506:                 my $nextResources = $curRes->$nextResourceMethod();
 2507:                 my $nextCount = scalar(@{$nextResources});
 2508: 
 2509:                 if ($nextCount == 1) { # **3**
 2510:                     my $current = $nextResources->[0]->{DATA}->{$valName} || 999999999;
 2511:                     $nextResources->[0]->{DATA}->{$valName} = min($resultingVal, $current);
 2512:                 }
 2513:                 
 2514:                 if ($nextCount > 1) { # **4**
 2515:                     foreach my $res (@{$nextResources}) {
 2516:                         my $current = $res->{DATA}->{$valName} || 999999999;
 2517:                         $res->{DATA}->{$valName} = min($current, $resultingVal + 1);
 2518:                     }
 2519:                 }
 2520:             }
 2521:             
 2522:             # Assign the final val (**2**)
 2523:             if (ref($curRes) && $direction == BACKWARD()) {
 2524:                 my $finalDepth = min($curRes->{DATA}->{TOP_DOWN_VAL},
 2525:                                      $curRes->{DATA}->{BOT_UP_VAL});
 2526:                 
 2527:                 $curRes->{DATA}->{DISPLAY_DEPTH} = $finalDepth;
 2528:                 if ($finalDepth > $maxDepth) {$maxDepth = $finalDepth;}
 2529:             }
 2530: 
 2531: 	    $curRes = $iterator->next();
 2532:         }
 2533:     }
 2534: 
 2535:     # Check: Was this only one resource, a map?
 2536:     if ($resourceCount == 1 && $resource->is_sequence() && !$self->{FORCE_TOP}) { 
 2537:         my $firstResource = $resource->map_start();
 2538:         my $finishResource = $resource->map_finish();
 2539:         return 
 2540:             Apache::lonnavmaps::iterator->new($self->{NAV_MAP}, $firstResource,
 2541:                                               $finishResource, $self->{FILTER},
 2542:                                               $self->{ALREADY_SEEN}, 
 2543:                                               $self->{CONDITION}, 0);
 2544:         
 2545:     }
 2546: 
 2547:     # Set up some bookkeeping information.
 2548:     $self->{CURRENT_DEPTH} = 0;
 2549:     $self->{MAX_DEPTH} = $maxDepth;
 2550:     $self->{STACK} = [];
 2551:     $self->{RECURSIVE_ITERATOR_FLAG} = 0;
 2552:     $self->{FINISHED} = 0; # When true, the iterator has finished
 2553: 
 2554:     for (my $i = 0; $i <= $self->{MAX_DEPTH}; $i++) {
 2555:         push @{$self->{STACK}}, [];
 2556:     }
 2557: 
 2558:     # Prime the recursion w/ the first resource **5**
 2559:     push @{$self->{STACK}->[0]}, $self->{FIRST_RESOURCE};
 2560:     $self->{ALREADY_SEEN}->{$self->{FIRST_RESOURCE}->{ID}} = 1;
 2561: 
 2562:     bless ($self);
 2563: 
 2564:     return $self;
 2565: }
 2566: 
 2567: sub next {
 2568:     my $self = shift;
 2569:     my $closeAllPages=shift;
 2570:     if ($self->{FINISHED}) {
 2571: 	return END_ITERATOR();
 2572:     }
 2573: 
 2574:     # If we want to return the top-level map object, and haven't yet,
 2575:     # do so.
 2576:     if ($self->{RETURN_0} && !$self->{HAVE_RETURNED_0}) {
 2577:         $self->{HAVE_RETURNED_0} = 1;
 2578:         return $self->{NAV_MAP}->getById('0.0');
 2579:     }
 2580: 
 2581:     if ($self->{RECURSIVE_ITERATOR_FLAG}) {
 2582:         # grab the next from the recursive iterator 
 2583:         my $next = $self->{RECURSIVE_ITERATOR}->next($closeAllPages);
 2584: 
 2585:         # is it a begin or end map? If so, update the depth
 2586:         if ($next == BEGIN_MAP() ) { $self->{RECURSIVE_DEPTH}++; }
 2587:         if ($next == END_MAP() ) { $self->{RECURSIVE_DEPTH}--; }
 2588: 
 2589:         # Are we back at depth 0? If so, stop recursing
 2590:         if ($self->{RECURSIVE_DEPTH} == 0) {
 2591:             $self->{RECURSIVE_ITERATOR_FLAG} = 0;
 2592:         }
 2593: 
 2594:         return $next;
 2595:     }
 2596: 
 2597:     if (defined($self->{FORCE_NEXT})) {
 2598:         my $tmp = $self->{FORCE_NEXT};
 2599:         $self->{FORCE_NEXT} = undef;
 2600:         return $tmp;
 2601:     }
 2602: 
 2603:     # Have we not yet begun? If not, return BEGIN_MAP and
 2604:     # remember we've started.
 2605:     if ( !$self->{STARTED} ) { 
 2606:         $self->{STARTED} = 1;
 2607:         return $self->BEGIN_MAP();
 2608:     }
 2609: 
 2610:     # Here's the guts of the iterator.
 2611:     
 2612:     # Find the next resource, if any.
 2613:     my $found = 0;
 2614:     my $i = $self->{MAX_DEPTH};
 2615:     my $newDepth;
 2616:     my $here;
 2617:     while ( $i >= 0 && !$found ) {
 2618:         if ( scalar(@{$self->{STACK}->[$i]}) > 0 ) { # **6**
 2619:             $here = pop @{$self->{STACK}->[$i]}; # **7**
 2620:             $found = 1;
 2621:             $newDepth = $i;
 2622:         }
 2623:         $i--;
 2624:     }
 2625: 
 2626:     # If we still didn't find anything, we're done.
 2627:     if ( !$found ) {
 2628:         # We need to get back down to the correct branch depth
 2629:         if ( $self->{CURRENT_DEPTH} > 0 ) {
 2630:             $self->{CURRENT_DEPTH}--;
 2631:             return END_BRANCH();
 2632:         } else {
 2633: 	    $self->{FINISHED} = 1;
 2634:             return END_MAP();
 2635:         }
 2636:     }
 2637: 
 2638:     # If this is not a resource, it must be an END_BRANCH marker we want
 2639:     # to return directly.
 2640:     if (!ref($here)) { # **8**
 2641:         if ($here == END_BRANCH()) { # paranoia, in case of later extension
 2642:             $self->{CURRENT_DEPTH}--;
 2643:             return $here;
 2644:         }
 2645:     }
 2646: 
 2647:     # Otherwise, it is a resource and it's safe to store in $self->{HERE}
 2648:     $self->{HERE} = $here;
 2649: 
 2650:     # Get to the right level
 2651:     if ( $self->{CURRENT_DEPTH} > $newDepth ) {
 2652:         push @{$self->{STACK}->[$newDepth]}, $here;
 2653:         $self->{CURRENT_DEPTH}--;
 2654:         return END_BRANCH();
 2655:     }
 2656:     if ( $self->{CURRENT_DEPTH} < $newDepth) {
 2657:         push @{$self->{STACK}->[$newDepth]}, $here;
 2658:         $self->{CURRENT_DEPTH}++;
 2659:         return BEGIN_BRANCH();
 2660:     }
 2661: 
 2662:     # If we made it here, we have the next resource, and we're at the
 2663:     # right branch level. So let's examine the resource for where
 2664:     # we can get to from here.
 2665: 
 2666:     # So we need to look at all the resources we can get to from here,
 2667:     # categorize them if we haven't seen them, remember if we have a new
 2668:     my $nextUnfiltered = $here->getNext();
 2669:     my $maxDepthAdded = -1;
 2670:     
 2671:     for (@$nextUnfiltered) {
 2672:         if (!defined($self->{ALREADY_SEEN}->{$_->{ID}})) {
 2673:             my $depth = $_->{DATA}->{DISPLAY_DEPTH};
 2674:             push @{$self->{STACK}->[$depth]}, $_;
 2675:             $self->{ALREADY_SEEN}->{$_->{ID}} = 1;
 2676:             if ($maxDepthAdded < $depth) { $maxDepthAdded = $depth; }
 2677:         }
 2678:     }
 2679: 
 2680:     # Is this the end of a branch? If so, all of the resources examined above
 2681:     # led to lower levels then the one we are currently at, so we push a END_BRANCH
 2682:     # marker onto the stack so we don't forget.
 2683:     # Example: For the usual A(BC)(DE)F case, when the iterator goes down the
 2684:     # BC branch and gets to C, it will see F as the only next resource, but it's
 2685:     # one level lower. Thus, this is the end of the branch, since there are no
 2686:     # more resources added to this level or above.
 2687:     # We don't do this if the examined resource is the finish resource,
 2688:     # because the condition given above is true, but the "END_MAP" will
 2689:     # take care of things and we should already be at depth 0.
 2690:     my $isEndOfBranch = $maxDepthAdded < $self->{CURRENT_DEPTH};
 2691:     if ($isEndOfBranch && $here != $self->{FINISH_RESOURCE}) { # **9**
 2692:         push @{$self->{STACK}->[$self->{CURRENT_DEPTH}]}, END_BRANCH();
 2693:     }
 2694: 
 2695:     # That ends the main iterator logic. Now, do we want to recurse
 2696:     # down this map (if this resource is a map)?
 2697:     if ( ($self->{HERE}->is_sequence() || (!$closeAllPages && $self->{HERE}->is_page())) &&
 2698:         (defined($self->{FILTER}->{$self->{HERE}->map_pc()}) xor $self->{CONDITION})) {
 2699:         $self->{RECURSIVE_ITERATOR_FLAG} = 1;
 2700:         my $firstResource = $self->{HERE}->map_start();
 2701:         my $finishResource = $self->{HERE}->map_finish();
 2702: 
 2703:         $self->{RECURSIVE_ITERATOR} = 
 2704:             Apache::lonnavmaps::iterator->new($self->{NAV_MAP}, $firstResource,
 2705:                                               $finishResource, $self->{FILTER},
 2706:                                               $self->{ALREADY_SEEN}, $self->{CONDITION});
 2707:     }
 2708: 
 2709:     # If this is a blank resource, don't actually return it.
 2710:     # Should you ever find you need it, make sure to add an option to the code
 2711:     #  that you can use; other things depend on this behavior.
 2712:     my $browsePriv = $self->{HERE}->browsePriv();
 2713:     if (!$self->{HERE}->src() || 
 2714:         (!($browsePriv eq 'F') && !($browsePriv eq '2')) ) {
 2715:         return $self->next($closeAllPages);
 2716:     }
 2717: 
 2718:     return $self->{HERE};
 2719: 
 2720: }
 2721: 
 2722: =pod
 2723: 
 2724: The other method available on the iterator is B<getStack>, which
 2725: returns an array populated with the current 'stack' of maps, as
 2726: references to the resource objects. Example: This is useful when
 2727: making the navigation map, as we need to check whether we are under a
 2728: page map to see if we need to link directly to the resource, or to the
 2729: page. The first elements in the array will correspond to the top of
 2730: the stack (most inclusive map).
 2731: 
 2732: =cut
 2733: 
 2734: sub getStack {
 2735:     my $self=shift;
 2736: 
 2737:     my @stack;
 2738: 
 2739:     $self->populateStack(\@stack);
 2740: 
 2741:     return \@stack;
 2742: }
 2743: 
 2744: # Private method: Calls the iterators recursively to populate the stack.
 2745: sub populateStack {
 2746:     my $self=shift;
 2747:     my $stack = shift;
 2748: 
 2749:     push @$stack, $self->{HERE} if ($self->{HERE});
 2750: 
 2751:     if ($self->{RECURSIVE_ITERATOR_FLAG}) {
 2752:         $self->{RECURSIVE_ITERATOR}->populateStack($stack);
 2753:     }
 2754: }
 2755: 
 2756: 1;
 2757: 
 2758: package Apache::lonnavmaps::DFSiterator;
 2759: 
 2760: # Not documented in the perldoc: This is a simple iterator that just walks
 2761: #  through the nav map and presents the resources in a depth-first search
 2762: #  fashion, ignorant of conditionals, randomized resources, etc. It presents
 2763: #  BEGIN_MAP and END_MAP, but does not understand branches at all. It is
 2764: #  useful for pre-processing of some kind, and is in fact used by the main
 2765: #  iterator that way, but that's about it.
 2766: # One could imagine merging this into the init routine of the main iterator,
 2767: #  but this might as well be left separate, since it is possible some other
 2768: #  use might be found for it. - Jeremy
 2769: 
 2770: # Unlike the main iterator, this DOES return all resources, even blank ones.
 2771: #  The main iterator needs them to correctly preprocess the map.
 2772: 
 2773: sub BEGIN_MAP { return 1; }    # begining of a new map
 2774: sub END_MAP { return 2; }      # end of the map
 2775: sub FORWARD { return 1; }      # go forward
 2776: sub BACKWARD { return 2; }
 2777: 
 2778: # Params: Nav map ref, first resource id/ref, finish resource id/ref,
 2779: #         filter hash ref (or undef), already seen hash or undef, condition
 2780: #         (as in main iterator), direction FORWARD or BACKWARD (undef->forward).
 2781: sub new {
 2782:     # magic invocation to create a class instance
 2783:     my $proto = shift;
 2784:     my $class = ref($proto) || $proto;
 2785:     my $self = {};
 2786: 
 2787:     $self->{NAV_MAP} = shift;
 2788:     return undef unless ($self->{NAV_MAP});
 2789: 
 2790:     $self->{FIRST_RESOURCE} = shift || $self->{NAV_MAP}->firstResource();
 2791:     $self->{FINISH_RESOURCE} = shift || $self->{NAV_MAP}->finishResource();
 2792: 
 2793:     # If the given resources are just the ID of the resource, get the
 2794:     # objects
 2795:     if (!ref($self->{FIRST_RESOURCE})) { $self->{FIRST_RESOURCE} = 
 2796:              $self->{NAV_MAP}->getById($self->{FIRST_RESOURCE}); }
 2797:     if (!ref($self->{FINISH_RESOURCE})) { $self->{FINISH_RESOURCE} = 
 2798:              $self->{NAV_MAP}->getById($self->{FINISH_RESOURCE}); }
 2799: 
 2800:     $self->{FILTER} = shift;
 2801: 
 2802:     # A hash, used as a set, of resource already seen
 2803:     $self->{ALREADY_SEEN} = shift;
 2804:      if (!defined($self->{ALREADY_SEEN})) { $self->{ALREADY_SEEN} = {} };
 2805:     $self->{CONDITION} = shift;
 2806:     $self->{DIRECTION} = shift || FORWARD();
 2807: 
 2808:     # Flag: Have we started yet?
 2809:     $self->{STARTED} = 0;
 2810: 
 2811:     # Should we continue calling the recursive iterator, if any?
 2812:     $self->{RECURSIVE_ITERATOR_FLAG} = 0;
 2813:     # The recursive iterator, if any
 2814:     $self->{RECURSIVE_ITERATOR} = undef;
 2815:     # Are we recursing on a map, or a branch?
 2816:     $self->{RECURSIVE_MAP} = 1; # we'll manually unset this when recursing on branches
 2817:     # And the count of how deep it is, so that this iterator can keep track of
 2818:     # when to pick back up again.
 2819:     $self->{RECURSIVE_DEPTH} = 0;
 2820: 
 2821:     # For keeping track of our branches, we maintain our own stack
 2822:     $self->{STACK} = [];
 2823: 
 2824:     # Start with the first resource
 2825:     if ($self->{DIRECTION} == FORWARD) {
 2826:         push @{$self->{STACK}}, $self->{FIRST_RESOURCE};
 2827:     } else {
 2828:         push @{$self->{STACK}}, $self->{FINISH_RESOURCE};
 2829:     }
 2830: 
 2831:     bless($self);
 2832:     return $self;
 2833: }
 2834: 
 2835: sub next {
 2836:     my $self = shift;
 2837:     
 2838:     # Are we using a recursive iterator? If so, pull from that and
 2839:     # watch the depth; we want to resume our level at the correct time.
 2840:     if ($self->{RECURSIVE_ITERATOR_FLAG}) {
 2841:         # grab the next from the recursive iterator
 2842:         my $next = $self->{RECURSIVE_ITERATOR}->next();
 2843:         
 2844:         # is it a begin or end map? Update depth if so
 2845:         if ($next == BEGIN_MAP() ) { $self->{RECURSIVE_DEPTH}++; }
 2846:         if ($next == END_MAP() ) { $self->{RECURSIVE_DEPTH}--; }
 2847: 
 2848:         # Are we back at depth 0? If so, stop recursing.
 2849:         if ($self->{RECURSIVE_DEPTH} == 0) {
 2850:             $self->{RECURSIVE_ITERATOR_FLAG} = 0;
 2851:         }
 2852:         
 2853:         return $next;
 2854:     }
 2855: 
 2856:     # Is there a current resource to grab? If not, then return
 2857:     # END_MAP, which will end the iterator.
 2858:     if (scalar(@{$self->{STACK}}) == 0) {
 2859:         return $self->END_MAP();
 2860:     }
 2861: 
 2862:     # Have we not yet begun? If not, return BEGIN_MAP and 
 2863:     # remember that we've started.
 2864:     if ( !$self->{STARTED} ) {
 2865:         $self->{STARTED} = 1;
 2866:         return $self->BEGIN_MAP;
 2867:     }
 2868: 
 2869:     # Get the next resource in the branch
 2870:     $self->{HERE} = pop @{$self->{STACK}};
 2871: 
 2872:     # remember that we've seen this, so we don't return it again later
 2873:     $self->{ALREADY_SEEN}->{$self->{HERE}->{ID}} = 1;
 2874:     
 2875:     # Get the next possible resources
 2876:     my $nextUnfiltered;
 2877:     if ($self->{DIRECTION} == FORWARD()) {
 2878:         $nextUnfiltered = $self->{HERE}->getNext();
 2879:     } else {
 2880:         $nextUnfiltered = $self->{HERE}->getPrevious();
 2881:     }
 2882:     my $next = [];
 2883: 
 2884:     # filter the next possibilities to remove things we've 
 2885:     # already seen.
 2886:     foreach (@$nextUnfiltered) {
 2887:         if (!defined($self->{ALREADY_SEEN}->{$_->{ID}})) {
 2888:             push @$next, $_;
 2889:         }
 2890:     }
 2891: 
 2892:     while (@$next) {
 2893:         # copy the next possibilities over to the stack
 2894:         push @{$self->{STACK}}, shift @$next;
 2895:     }
 2896: 
 2897:     # If this is a map and we want to recurse down it... (not filtered out)
 2898:     if ($self->{HERE}->is_map() && 
 2899:          (defined($self->{FILTER}->{$self->{HERE}->map_pc()}) xor $self->{CONDITION})) { 
 2900:         $self->{RECURSIVE_ITERATOR_FLAG} = 1;
 2901:         my $firstResource = $self->{HERE}->map_start();
 2902:         my $finishResource = $self->{HERE}->map_finish();
 2903: 
 2904:         $self->{RECURSIVE_ITERATOR} =
 2905:           Apache::lonnavmaps::DFSiterator->new ($self->{NAV_MAP}, $firstResource, 
 2906:                      $finishResource, $self->{FILTER}, $self->{ALREADY_SEEN},
 2907:                                              $self->{CONDITION}, $self->{DIRECTION});
 2908:     }
 2909: 
 2910:     return $self->{HERE};
 2911: }
 2912: 
 2913: # Identical to the full iterator methods of the same name. Hate to copy/paste
 2914: # but I also hate to "inherit" either iterator from the other.
 2915: 
 2916: sub getStack {
 2917:     my $self=shift;
 2918: 
 2919:     my @stack;
 2920: 
 2921:     $self->populateStack(\@stack);
 2922: 
 2923:     return \@stack;
 2924: }
 2925: 
 2926: # Private method: Calls the iterators recursively to populate the stack.
 2927: sub populateStack {
 2928:     my $self=shift;
 2929:     my $stack = shift;
 2930: 
 2931:     push @$stack, $self->{HERE} if ($self->{HERE});
 2932: 
 2933:     if ($self->{RECURSIVE_ITERATOR_FLAG}) {
 2934:         $self->{RECURSIVE_ITERATOR}->populateStack($stack);
 2935:     }
 2936: }
 2937: 
 2938: 1;
 2939: 
 2940: package Apache::lonnavmaps::resource;
 2941: 
 2942: use Apache::lonnet;
 2943: 
 2944: =pod
 2945: 
 2946: =head1 Object: resource 
 2947: 
 2948: X<resource, navmap object>
 2949: A resource object encapsulates a resource in a resource map, allowing
 2950: easy manipulation of the resource, querying the properties of the
 2951: resource (including user properties), and represents a reference that
 2952: can be used as the canonical representation of the resource by
 2953: lonnavmap clients like renderers.
 2954: 
 2955: A resource only makes sense in the context of a navmap, as some of the
 2956: data is stored in the navmap object.
 2957: 
 2958: You will probably never need to instantiate this object directly. Use
 2959: Apache::lonnavmaps::navmap, and use the "start" method to obtain the
 2960: starting resource.
 2961: 
 2962: Resource objects respect the parameter_hiddenparts, which suppresses 
 2963: various parts according to the wishes of the map author. As of this
 2964: writing, there is no way to override this parameter, and suppressed
 2965: parts will never be returned, nor will their response types or ids be
 2966: stored.
 2967: 
 2968: =head2 Overview
 2969: 
 2970: A B<Resource> is the most granular type of object in LON-CAPA that can
 2971: be included in a course. It can either be a particular resource, like
 2972: an HTML page, external resource, problem, etc., or it can be a
 2973: container sequence, such as a "page" or a "map".
 2974: 
 2975: To see a sequence from the user's point of view, please see the
 2976: B<Creating a Course: Maps and Sequences> chapter of the Author's
 2977: Manual.
 2978: 
 2979: A Resource Object, once obtained from a navmap object via a B<getBy*>
 2980: method of the navmap, or from an iterator, allows you to query
 2981: information about that resource.
 2982: 
 2983: Generally, you do not ever want to create a resource object yourself,
 2984: so creation has been left undocumented. Always retrieve resources
 2985: from navmap objects.
 2986: 
 2987: =head3 Identifying Resources
 2988: 
 2989: X<big hash>Every resource is identified by a Resource ID in the big hash that is
 2990: unique to that resource for a given course. X<resource ID, in big hash>
 2991: The Resource ID has the form #.#, where the first number is the same
 2992: for every resource in a map, and the second is unique. For instance,
 2993: for a course laid out like this:
 2994: 
 2995:  * Problem 1
 2996:  * Map
 2997:    * Resource 2
 2998:    * Resource 3
 2999: 
 3000: C<Problem 1> and C<Map> will share a first number, and C<Resource 2>
 3001: C<Resource 3> will share a first number. The second number may end up
 3002: re-used between the two groups.
 3003: 
 3004: The resource ID is only used in the big hash, but can be used in the
 3005: context of a course to identify a resource easily. (For instance, the
 3006: printing system uses it to record which resources from a sequence you 
 3007: wish to print.)
 3008: 
 3009: X<symb> X<resource, symb>
 3010: All resources also have B<symb>s, which uniquely identify a resource
 3011: in a course. Many internal LON-CAPA functions expect a symb. A symb
 3012: carries along with it the URL of the resource, and the map it appears
 3013: in. Symbs are much larger then resource IDs.
 3014: 
 3015: =cut
 3016: 
 3017: sub new {
 3018:     # magic invocation to create a class instance
 3019:     my $proto = shift;
 3020:     my $class = ref($proto) || $proto;
 3021:     my $self = {};
 3022: 
 3023:     $self->{NAV_MAP} = shift;
 3024:     $self->{ID} = shift;
 3025: 
 3026:     # Store this new resource in the parent nav map's cache.
 3027:     $self->{NAV_MAP}->{RESOURCE_CACHE}->{$self->{ID}} = $self;
 3028:     $self->{RESOURCE_ERROR} = 0;
 3029: 
 3030:     # A hash that can be used by two-pass algorithms to store data
 3031:     # about this resource in. Not used by the resource object
 3032:     # directly.
 3033:     $self->{DATA} = {};
 3034:    
 3035:     bless($self);
 3036:     
 3037:     return $self;
 3038: }
 3039: 
 3040: # private function: simplify the NAV_HASH lookups we keep doing
 3041: # pass the name, and to automatically append my ID, pass a true val on the
 3042: # second param
 3043: sub navHash {
 3044:     my $self = shift;
 3045:     my $param = shift;
 3046:     my $id = shift;
 3047:     return $self->{NAV_MAP}->navhash($param . ($id?$self->{ID}:""));
 3048: }
 3049: 
 3050: =pod
 3051: 
 3052: =head2 Methods
 3053: 
 3054: Once you have a resource object, here's what you can do with it:
 3055: 
 3056: =head3 Attribute Retrieval
 3057: 
 3058: Every resource has certain attributes that can be retrieved and used:
 3059: 
 3060: =over 4
 3061: 
 3062: =item * B<ID>: Every resource has an ID that is unique for that
 3063:     resource in the course it is in. The ID is actually in the hash
 3064:     representing the resource, so for a resource object $res, obtain
 3065:     it via C<$res->{ID}).
 3066: 
 3067: =item * B<compTitle>:
 3068: 
 3069: Returns a "composite title", that is equal to $res->title() if the
 3070: resource has a title, and is otherwise the last part of the URL (e.g.,
 3071: "problem.problem").
 3072: 
 3073: =item * B<ext>:
 3074: 
 3075: Returns true if the resource is external.
 3076: 
 3077: =item * B<kind>:
 3078: 
 3079: Returns the kind of the resource from the compiled nav map.
 3080: 
 3081: =item * B<randomout>:
 3082: 
 3083: Returns true if this resource was chosen to NOT be shown to the user
 3084: by the random map selection feature. In other words, this is usually
 3085: false.
 3086: 
 3087: =item * B<randompick>:
 3088: 
 3089: Returns true for a map if the randompick feature is being used on the
 3090: map. (?)
 3091: 
 3092: =item * B<src>:
 3093: 
 3094: Returns the source for the resource.
 3095: 
 3096: =item * B<symb>:
 3097: 
 3098: Returns the symb for the resource.
 3099: 
 3100: =item * B<title>:
 3101: 
 3102: Returns the title of the resource.
 3103: 
 3104: =back
 3105: 
 3106: =cut
 3107: 
 3108: # These info functions can be used directly, as they don't return
 3109: # resource information.
 3110: sub comesfrom { my $self=shift; return $self->navHash("comesfrom_", 1); }
 3111: sub ext { my $self=shift; return $self->navHash("ext_", 1) eq 'true:'; }
 3112: sub from { my $self=shift; return $self->navHash("from_", 1); }
 3113: # considered private and undocumented
 3114: sub goesto { my $self=shift; return $self->navHash("goesto_", 1); }
 3115: sub kind { my $self=shift; return $self->navHash("kind_", 1); }
 3116: sub randomout { my $self=shift; return $self->navHash("randomout_", 1); }
 3117: sub randompick { 
 3118:     my $self = shift;
 3119:     return $self->{NAV_MAP}->{PARM_HASH}->{$self->symb .
 3120:                                                '.0.parameter_randompick'};
 3121: }
 3122: sub src { 
 3123:     my $self=shift;
 3124:     return $self->navHash("src_", 1);
 3125: }
 3126: sub symb {
 3127:     my $self=shift;
 3128:     (my $first, my $second) = $self->{ID} =~ /(\d+).(\d+)/;
 3129:     my $symbSrc = &Apache::lonnet::declutter($self->src());
 3130:     my $symb = &Apache::lonnet::declutter($self->navHash('map_id_'.$first)) 
 3131:         . '___' . $second . '___' . $symbSrc;
 3132:     return &Apache::lonnet::symbclean($symb);
 3133: }
 3134: sub title { 
 3135:     my $self=shift; 
 3136:     if ($self->{ID} eq '0.0') {
 3137: 	# If this is the top-level map, return the title of the course
 3138: 	# since this map can not be titled otherwise.
 3139: 	return $ENV{'course.'.$ENV{'request.course.id'}.'.description'};
 3140:     }
 3141:     return $self->navHash("title_", 1); }
 3142: # considered private and undocumented
 3143: sub to { my $self=shift; return $self->navHash("to_", 1); }
 3144: sub compTitle {
 3145:     my $self = shift;
 3146:     my $title = $self->title();
 3147:     $title=~s/\&colon\;/\:/gs;
 3148:     if (!$title) {
 3149:         $title = $self->src();
 3150:         $title = substr($title, rindex($title, '/') + 1);
 3151:     }
 3152:     return $title;
 3153: }
 3154: =pod
 3155: 
 3156: B<Predicate Testing the Resource>
 3157: 
 3158: These methods are shortcuts to deciding if a given resource has a given property.
 3159: 
 3160: =over 4
 3161: 
 3162: =item * B<is_map>:
 3163: 
 3164: Returns true if the resource is a map type.
 3165: 
 3166: =item * B<is_problem>:
 3167: 
 3168: Returns true if the resource is a problem type, false
 3169: otherwise. (Looks at the extension on the src field; might need more
 3170: to work correctly.)
 3171: 
 3172: =item * B<is_page>:
 3173: 
 3174: Returns true if the resource is a page.
 3175: 
 3176: =item * B<is_sequence>:
 3177: 
 3178: Returns true if the resource is a sequence.
 3179: 
 3180: =back
 3181: 
 3182: =cut
 3183: 
 3184: sub hasResource {
 3185:    my $self = shift;
 3186:    return $self->{NAV_MAP}->hasResource(@_);
 3187: }
 3188: 
 3189: sub retrieveResources {
 3190:    my $self = shift;
 3191:    return $self->{NAV_MAP}->retrieveResources(@_);
 3192: }
 3193: 
 3194: sub is_html {
 3195:     my $self=shift;
 3196:     my $src = $self->src();
 3197:     return ($src =~ /html$/);
 3198: }
 3199: sub is_map { my $self=shift; return defined($self->navHash("is_map_", 1)); }
 3200: sub is_page {
 3201:     my $self=shift;
 3202:     my $src = $self->src();
 3203:     return $self->navHash("is_map_", 1) && 
 3204: 	$self->navHash("map_type_" . $self->map_pc()) eq 'page';
 3205: }
 3206: sub is_problem {
 3207:     my $self=shift;
 3208:     my $src = $self->src();
 3209:     return ($src =~ /\.(problem|exam|quiz|assess|survey|form|library)$/)
 3210: }
 3211: sub contains_problem {
 3212:     my $self=shift;
 3213:     if ($self->is_page()) {
 3214: 	my $hasProblem=$self->hasResource($self,sub { $_[0]->is_problem() },1);
 3215: 	return $hasProblem;
 3216:     }
 3217:     return 0;
 3218: }
 3219: sub is_sequence {
 3220:     my $self=shift;
 3221:     my $src = $self->src();
 3222:     return $self->navHash("is_map_", 1) && 
 3223: 	$self->navHash("map_type_" . $self->map_pc()) eq 'sequence';
 3224: }
 3225: 
 3226: # Private method: Shells out to the parmval in the nav map, handler parts.
 3227: sub parmval {
 3228:     my $self = shift;
 3229:     my $what = shift;
 3230:     my $part = shift;
 3231:     if (!defined($part)) { 
 3232:         $part = '0'; 
 3233:     }
 3234:     return $self->{NAV_MAP}->parmval($part.'.'.$what, $self->symb());
 3235: }
 3236: 
 3237: =pod
 3238: 
 3239: B<Map Methods>
 3240: 
 3241: These methods are useful for getting information about the map
 3242: properties of the resource, if the resource is a map (B<is_map>).
 3243: 
 3244: =over 4
 3245: 
 3246: =item * B<map_finish>:
 3247: 
 3248: Returns a reference to a resource object corresponding to the finish
 3249: resource of the map.
 3250: 
 3251: =item * B<map_pc>:
 3252: 
 3253: Returns the pc value of the map, which is the first number that
 3254: appears in the resource ID of the resources in the map, and is the
 3255: number that appears around the middle of the symbs of the resources in
 3256: that map.
 3257: 
 3258: =item * B<map_start>:
 3259: 
 3260: Returns a reference to a resource object corresponding to the start
 3261: resource of the map.
 3262: 
 3263: =item * B<map_type>:
 3264: 
 3265: Returns a string with the type of the map in it.
 3266: 
 3267: =back
 3268: 
 3269: =cut
 3270: 
 3271: sub map_finish {
 3272:     my $self = shift;
 3273:     my $src = $self->src();
 3274:     $src = Apache::lonnet::clutter($src);
 3275:     my $res = $self->navHash("map_finish_$src", 0);
 3276:     $res = $self->{NAV_MAP}->getById($res);
 3277:     return $res;
 3278: }
 3279: sub map_pc {
 3280:     my $self = shift;
 3281:     my $src = $self->src();
 3282:     return $self->navHash("map_pc_$src", 0);
 3283: }
 3284: sub map_start {
 3285:     my $self = shift;
 3286:     my $src = $self->src();
 3287:     $src = Apache::lonnet::clutter($src);
 3288:     my $res = $self->navHash("map_start_$src", 0);
 3289:     $res = $self->{NAV_MAP}->getById($res);
 3290:     return $res;
 3291: }
 3292: sub map_type {
 3293:     my $self = shift;
 3294:     my $pc = $self->map_pc();
 3295:     return $self->navHash("map_type_$pc", 0);
 3296: }
 3297: 
 3298: #####
 3299: # Property queries
 3300: #####
 3301: 
 3302: # These functions will be responsible for returning the CORRECT
 3303: # VALUE for the parameter, no matter what. So while they may look
 3304: # like direct calls to parmval, they can be more then that.
 3305: # So, for instance, the duedate function should use the "duedatetype"
 3306: # information, rather then the resource object user.
 3307: 
 3308: =pod
 3309: 
 3310: =head2 Resource Parameters
 3311: 
 3312: In order to use the resource parameters correctly, the nav map must
 3313: have been instantiated with genCourseAndUserOptions set to true, so
 3314: the courseopt and useropt is read correctly. Then, you can call these
 3315: functions to get the relevant parameters for the resource. Each
 3316: function defaults to part "0", but can be directed to another part by
 3317: passing the part as the parameter.
 3318: 
 3319: These methods are responsible for getting the parameter correct, not
 3320: merely reflecting the contents of the GDBM hashes. As we move towards
 3321: dates relative to other dates, these methods should be updated to
 3322: reflect that. (Then, anybody using these methods will not have to update
 3323: their code.)
 3324: 
 3325: =over 4
 3326: 
 3327: =item * B<acc>:
 3328: 
 3329: Get the Client IP/Name Access Control information.
 3330: 
 3331: =item * B<answerdate>:
 3332: 
 3333: Get the answer-reveal date for the problem.
 3334: 
 3335: =item * B<awarded>: 
 3336: 
 3337: Gets the awarded value for the problem part. Requires genUserData set to
 3338: true when the navmap object was created.
 3339: 
 3340: =item * B<duedate>:
 3341: 
 3342: Get the due date for the problem.
 3343: 
 3344: =item * B<tries>:
 3345: 
 3346: Get the number of tries the student has used on the problem.
 3347: 
 3348: =item * B<maxtries>:
 3349: 
 3350: Get the number of max tries allowed.
 3351: 
 3352: =item * B<opendate>:
 3353: 
 3354: Get the open date for the problem.
 3355: 
 3356: =item * B<sig>:
 3357: 
 3358: Get the significant figures setting.
 3359: 
 3360: =item * B<tol>:
 3361: 
 3362: Get the tolerance for the problem.
 3363: 
 3364: =item * B<tries>:
 3365: 
 3366: Get the number of tries the user has already used on the problem.
 3367: 
 3368: =item * B<type>:
 3369: 
 3370: Get the question type for the problem.
 3371: 
 3372: =item * B<weight>:
 3373: 
 3374: Get the weight for the problem.
 3375: 
 3376: =back
 3377: 
 3378: =cut
 3379: 
 3380: sub acc {
 3381:     (my $self, my $part) = @_;
 3382:     return $self->parmval("acc", $part);
 3383: }
 3384: sub answerdate {
 3385:     (my $self, my $part) = @_;
 3386:     # Handle intervals
 3387:     if ($self->parmval("answerdate.type", $part) eq 'date_interval') {
 3388:         return $self->duedate($part) + 
 3389:             $self->parmval("answerdate", $part);
 3390:     }
 3391:     return $self->parmval("answerdate", $part);
 3392: }
 3393: sub awarded { 
 3394:     my $self = shift; my $part = shift;
 3395:     $self->{NAV_MAP}->get_user_data();
 3396:     if (!defined($part)) { $part = '0'; }
 3397:     return $self->{NAV_MAP}->{STUDENT_DATA}->{$self->symb()}->{'resource.'.$part.'.awarded'};
 3398: }
 3399: sub duedate {
 3400:     (my $self, my $part) = @_;
 3401:     return $self->parmval("duedate", $part);
 3402: }
 3403: sub maxtries {
 3404:     (my $self, my $part) = @_;
 3405:     return $self->parmval("maxtries", $part);
 3406: }
 3407: sub opendate {
 3408:     (my $self, my $part) = @_;
 3409:     if ($self->parmval("opendate.type", $part) eq 'date_interval') {
 3410:         return $self->duedate($part) -
 3411:             $self->parmval("opendate", $part);
 3412:     }
 3413:     return $self->parmval("opendate");
 3414: }
 3415: sub problemstatus {
 3416:     (my $self, my $part) = @_;
 3417:     return lc $self->parmval("problemstatus", $part);
 3418: }
 3419: sub sig {
 3420:     (my $self, my $part) = @_;
 3421:     return $self->parmval("sig", $part);
 3422: }
 3423: sub tol {
 3424:     (my $self, my $part) = @_;
 3425:     return $self->parmval("tol", $part);
 3426: }
 3427: sub tries { 
 3428:     my $self = shift; 
 3429:     my $tries = $self->queryRestoreHash('tries', shift);
 3430:     if (!defined($tries)) { return '0';}
 3431:     return $tries;
 3432: }
 3433: sub type {
 3434:     (my $self, my $part) = @_;
 3435:     return $self->parmval("type", $part);
 3436: }
 3437: sub weight { 
 3438:     my $self = shift; my $part = shift;
 3439:     if (!defined($part)) { $part = '0'; }
 3440:     return &Apache::lonnet::EXT('resource.'.$part.'.weight',
 3441: 				$self->symb(), $ENV{'user.domain'},
 3442: 				$ENV{'user.name'}, 
 3443: 				$ENV{'request.course.sec'});
 3444: 
 3445: }
 3446: 
 3447: # Multiple things need this
 3448: sub getReturnHash {
 3449:     my $self = shift;
 3450:     
 3451:     if (!defined($self->{RETURN_HASH})) {
 3452:         my %tmpHash  = &Apache::lonnet::restore($self->symb());
 3453:         $self->{RETURN_HASH} = \%tmpHash;
 3454:     }
 3455: }       
 3456: 
 3457: ######
 3458: # Status queries
 3459: ######
 3460: 
 3461: # These methods query the status of problems.
 3462: 
 3463: # If we need to count parts, this function determines the number of
 3464: # parts from the metadata. When called, it returns a reference to a list
 3465: # of strings corresponding to the parts. (Thus, using it in a scalar context
 3466: # tells you how many parts you have in the problem:
 3467: # $partcount = scalar($resource->countParts());
 3468: # Don't use $self->{PARTS} directly because you don't know if it's been
 3469: # computed yet.
 3470: 
 3471: =pod
 3472: 
 3473: =head2 Resource misc
 3474: 
 3475: Misc. functions for the resource.
 3476: 
 3477: =over 4
 3478: 
 3479: =item * B<hasDiscussion>:
 3480: 
 3481: Returns a false value if there has been discussion since the user last
 3482: logged in, true if there has. Always returns false if the discussion
 3483: data was not extracted when the nav map was constructed.
 3484: 
 3485: =item * B<getFeedback>:
 3486: 
 3487: Gets the feedback for the resource and returns the raw feedback string
 3488: for the resource, or the null string if there is no feedback or the
 3489: email data was not extracted when the nav map was constructed. Usually
 3490: used like this:
 3491: 
 3492:  for (split(/\,/, $res->getFeedback())) {
 3493:     my $link = &Apache::lonnet::escape($_);
 3494:     ...
 3495: 
 3496: and use the link as appropriate.
 3497: 
 3498: =cut
 3499: 
 3500: sub hasDiscussion {
 3501:     my $self = shift;
 3502:     return $self->{NAV_MAP}->hasDiscussion($self->symb());
 3503: }
 3504: 
 3505: sub getFeedback {
 3506:     my $self = shift;
 3507:     my $source = $self->src();
 3508:     if ($source =~ /^\/res\//) { $source = substr $source, 5; }
 3509:     return $self->{NAV_MAP}->getFeedback($source);
 3510: }
 3511: 
 3512: sub getErrors {
 3513:     my $self = shift;
 3514:     my $source = $self->src();
 3515:     if ($source =~ /^\/res\//) { $source = substr $source, 5; }
 3516:     return $self->{NAV_MAP}->getErrors($source);
 3517: }
 3518: 
 3519: =pod
 3520: 
 3521: =item * B<parts>():
 3522: 
 3523: Returns a list reference containing sorted strings corresponding to
 3524: each part of the problem. Single part problems have only a part '0'.
 3525: Multipart problems do not return their part '0', since they typically
 3526: do not really matter. 
 3527: 
 3528: =item * B<countParts>():
 3529: 
 3530: Returns the number of parts of the problem a student can answer. Thus,
 3531: for single part problems, returns 1. For multipart, it returns the
 3532: number of parts in the problem, not including psuedo-part 0. 
 3533: 
 3534: =item * B<multipart>():
 3535: 
 3536: Returns true if the problem is multipart, false otherwise. Use this instead
 3537: of countParts if all you want is multipart/not multipart.
 3538: 
 3539: =item * B<responseType>($part):
 3540: 
 3541: Returns the response type of the part, without the word "response" on the
 3542: end. Example return values: 'string', 'essay', 'numeric', etc.
 3543: 
 3544: =item * B<responseIds>($part):
 3545: 
 3546: Retreives the response IDs for the given part as an array reference containing
 3547: strings naming the response IDs. This may be empty.
 3548: 
 3549: =back
 3550: 
 3551: =cut
 3552: 
 3553: sub parts {
 3554:     my $self = shift;
 3555: 
 3556:     if ($self->ext) { return []; }
 3557: 
 3558:     $self->extractParts();
 3559:     return $self->{PARTS};
 3560: }
 3561: 
 3562: sub countParts {
 3563:     my $self = shift;
 3564:     
 3565:     my $parts = $self->parts();
 3566: 
 3567:     # If I left this here, then it's not necessary.
 3568:     #my $delta = 0;
 3569:     #for my $part (@$parts) {
 3570:     #    if ($part eq '0') { $delta--; }
 3571:     #}
 3572: 
 3573:     if ($self->{RESOURCE_ERROR}) {
 3574:         return 0;
 3575:     }
 3576: 
 3577:     return scalar(@{$parts}); # + $delta;
 3578: }
 3579: 
 3580: sub multipart {
 3581:     my $self = shift;
 3582:     return $self->countParts() > 1;
 3583: }
 3584: 
 3585: sub singlepart {
 3586:     my $self = shift;
 3587:     return $self->countParts() == 1;
 3588: }
 3589: 
 3590: sub responseType {
 3591:     my $self = shift;
 3592:     my $part = shift;
 3593: 
 3594:     $self->extractParts();
 3595:     if (defined($self->{RESPONSE_TYPES}->{$part})) {
 3596: 	return @{$self->{RESPONSE_TYPES}->{$part}};
 3597:     } else {
 3598: 	return undef;
 3599:     }
 3600: }
 3601: 
 3602: sub responseIds {
 3603:     my $self = shift;
 3604:     my $part = shift;
 3605: 
 3606:     $self->extractParts();
 3607:     if (defined($self->{RESPONSE_IDS}->{$part})) {
 3608: 	return @{$self->{RESPONSE_IDS}->{$part}};
 3609:     } else {
 3610: 	return undef;
 3611:     }
 3612: }
 3613: 
 3614: # Private function: Extracts the parts information, both part names and
 3615: # part types, and saves it. 
 3616: sub extractParts { 
 3617:     my $self = shift;
 3618:     
 3619:     return if (defined($self->{PARTS}));
 3620:     return if ($self->ext);
 3621: 
 3622:     $self->{PARTS} = [];
 3623: 
 3624:     my %parts;
 3625: 
 3626:     # Retrieve part count, if this is a problem
 3627:     if ($self->is_problem()) {
 3628: 	my $partorder = &Apache::lonnet::metadata($self->src(), 'partorder');
 3629:         my $metadata = &Apache::lonnet::metadata($self->src(), 'packages');
 3630: 
 3631: 	if ($partorder) {
 3632: 	    my @parts;
 3633: 	    for my $part (split (/,/,$partorder)) {
 3634: 		if (!Apache::loncommon::check_if_partid_hidden($part, $self->symb())) {
 3635: 		    push @parts, $part;
 3636: 		    $parts{$part} = 1;
 3637: 		}
 3638: 	    }
 3639: 	    $self->{PARTS} = \@parts;
 3640: 	} else {
 3641: 	    if (!$metadata) {
 3642: 		$self->{RESOURCE_ERROR} = 1;
 3643: 		$self->{PARTS} = [];
 3644: 		$self->{PART_TYPE} = {};
 3645: 		return;
 3646: 	    }
 3647: 	    foreach (split(/\,/,$metadata)) {
 3648: 		if ($_ =~ /^part_(.*)$/) {
 3649: 		    my $part = $1;
 3650: 		    # This floods the logs if it blows up
 3651: 		    if (defined($parts{$part})) {
 3652: 			&Apache::lonnet::logthis("$part multiply defined in metadata for " . $self->symb());
 3653: 		    }
 3654: 		    
 3655: 		    # check to see if part is turned off.
 3656: 		    
 3657: 		    if (!Apache::loncommon::check_if_partid_hidden($part, $self->symb())) {
 3658: 			$parts{$part} = 1;
 3659: 		    }
 3660: 		}
 3661: 	    }
 3662: 	    my @sortedParts = sort keys %parts;
 3663: 	    $self->{PARTS} = \@sortedParts;
 3664:         }
 3665:         
 3666: 
 3667:         my %responseIdHash;
 3668:         my %responseTypeHash;
 3669: 
 3670: 
 3671:         # Init the responseIdHash
 3672:         foreach (@{$self->{PARTS}}) {
 3673:             $responseIdHash{$_} = [];
 3674:         }
 3675: 
 3676:         # Now, the unfortunate thing about this is that parts, part name, and
 3677:         # response id are delimited by underscores, but both the part
 3678:         # name and response id can themselves have underscores in them.
 3679:         # So we have to use our knowlege of part names to figure out 
 3680:         # where the part names begin and end, and even then, it is possible
 3681:         # to construct ambiguous situations.
 3682:         foreach (split /,/, $metadata) {
 3683:             if ($_ =~ /^([a-zA-Z]+)response_(.*)/) {
 3684:                 my $responseType = $1;
 3685:                 my $partStuff = $2;
 3686:                 my $partIdSoFar = '';
 3687:                 my @partChunks = split /_/, $partStuff;
 3688:                 my $i = 0;
 3689:                 for ($i = 0; $i < scalar(@partChunks); $i++) {
 3690:                     if ($partIdSoFar) { $partIdSoFar .= '_'; }
 3691:                     $partIdSoFar .= $partChunks[$i];
 3692:                     if ($parts{$partIdSoFar}) {
 3693:                         my @otherChunks = @partChunks[$i+1..$#partChunks];
 3694:                         my $responseId = join('_', @otherChunks);
 3695:                         push @{$responseIdHash{$partIdSoFar}}, $responseId;
 3696:                         push @{$responseTypeHash{$partIdSoFar}}, $responseType;
 3697:                     }
 3698:                 }
 3699:             }
 3700:         }
 3701:         $self->{RESPONSE_IDS} = \%responseIdHash;
 3702:         $self->{RESPONSE_TYPES} = \%responseTypeHash;
 3703:     }
 3704: 
 3705:     return;
 3706: }
 3707: 
 3708: =pod
 3709: 
 3710: =head2 Resource Status
 3711: 
 3712: Problem resources have status information, reflecting their various
 3713: dates and completion statuses.
 3714: 
 3715: There are two aspects to the status: the date-related information and
 3716: the completion information.
 3717: 
 3718: Idiomatic usage of these two methods would probably look something
 3719: like
 3720: 
 3721:  foreach ($resource->parts()) {
 3722:     my $dateStatus = $resource->getDateStatus($_);
 3723:     my $completionStatus = $resource->getCompletionStatus($_);
 3724: 
 3725:     or
 3726: 
 3727:     my $status = $resource->status($_);
 3728: 
 3729:     ... use it here ...
 3730:  }
 3731: 
 3732: Which you use depends on exactly what you are looking for. The
 3733: status() function has been optimized for the nav maps display and may
 3734: not precisely match what you need elsewhere.
 3735: 
 3736: The symbolic constants shown below can be accessed through the
 3737: resource object: C<$res->OPEN>.
 3738: 
 3739: =over 4
 3740: 
 3741: =item * B<getDateStatus>($part):
 3742: 
 3743: ($part defaults to 0). A convenience function that returns a symbolic
 3744: constant telling you about the date status of the part. The possible
 3745: return values are:
 3746: 
 3747: =back
 3748: 
 3749: B<Date Codes>
 3750: 
 3751: =over 4
 3752: 
 3753: =item * B<OPEN_LATER>:
 3754: 
 3755: The problem will be opened later.
 3756: 
 3757: =item * B<OPEN>:
 3758: 
 3759: Open and not yet due.
 3760: 
 3761: 
 3762: =item * B<PAST_DUE_ANSWER_LATER>:
 3763: 
 3764: The due date has passed, but the answer date has not yet arrived.
 3765: 
 3766: =item * B<PAST_DUE_NO_ANSWER>:
 3767: 
 3768: The due date has passed and there is no answer opening date set.
 3769: 
 3770: =item * B<ANSWER_OPEN>:
 3771: 
 3772: The answer date is here.
 3773: 
 3774: =item * B<NETWORK_FAILURE>:
 3775: 
 3776: The information is unknown due to network failure.
 3777: 
 3778: =back
 3779: 
 3780: =cut
 3781: 
 3782: # Apparently the compiler optimizes these into constants automatically
 3783: sub OPEN_LATER             { return 0; }
 3784: sub OPEN                   { return 1; }
 3785: sub PAST_DUE_NO_ANSWER     { return 2; }
 3786: sub PAST_DUE_ANSWER_LATER  { return 3; }
 3787: sub ANSWER_OPEN            { return 4; }
 3788: sub NOTHING_SET            { return 5; } 
 3789: sub NETWORK_FAILURE        { return 100; }
 3790: 
 3791: # getDateStatus gets the date status for a given problem part. 
 3792: # Because answer date, due date, and open date are fully independent
 3793: # (i.e., it is perfectly possible to *only* have an answer date), 
 3794: # we have to completely cover the 3x3 maxtrix of (answer, due, open) x
 3795: # (past, future, none given). This function handles this with a decision
 3796: # tree. Read the comments to follow the decision tree.
 3797: 
 3798: sub getDateStatus {
 3799:     my $self = shift;
 3800:     my $part = shift;
 3801:     $part = "0" if (!defined($part));
 3802: 
 3803:     # Always return network failure if there was one.
 3804:     return $self->NETWORK_FAILURE if ($self->{NAV_MAP}->{NETWORK_FAILURE});
 3805: 
 3806:     my $now = time();
 3807: 
 3808:     my $open = $self->opendate($part);
 3809:     my $due = $self->duedate($part);
 3810:     my $answer = $self->answerdate($part);
 3811: 
 3812:     if (!$open && !$due && !$answer) {
 3813:         # no data on the problem at all
 3814:         # should this be the same as "open later"? think multipart.
 3815:         return $self->NOTHING_SET;
 3816:     }
 3817:     if (!$open || $now < $open) {return $self->OPEN_LATER}
 3818:     if (!$due || $now < $due) {return $self->OPEN}
 3819:     if ($answer && $now < $answer) {return $self->PAST_DUE_ANSWER_LATER}
 3820:     if ($answer) { return $self->ANSWER_OPEN; }
 3821:     return PAST_DUE_NO_ANSWER;
 3822: }
 3823: 
 3824: =pod
 3825: 
 3826: B<>
 3827: 
 3828: =over 4
 3829: 
 3830: =item * B<getCompletionStatus>($part):
 3831: 
 3832: ($part defaults to 0.) A convenience function that returns a symbolic
 3833: constant telling you about the completion status of the part, with the
 3834: following possible results:
 3835: 
 3836: =back
 3837: 
 3838: B<Completion Codes>
 3839: 
 3840: =over 4
 3841: 
 3842: =item * B<NOT_ATTEMPTED>:
 3843: 
 3844: Has not been attempted at all.
 3845: 
 3846: =item * B<INCORRECT>:
 3847: 
 3848: Attempted, but wrong by student.
 3849: 
 3850: =item * B<INCORRECT_BY_OVERRIDE>:
 3851: 
 3852: Attempted, but wrong by instructor override.
 3853: 
 3854: =item * B<CORRECT>:
 3855: 
 3856: Correct or correct by instructor.
 3857: 
 3858: =item * B<CORRECT_BY_OVERRIDE>:
 3859: 
 3860: Correct by instructor override.
 3861: 
 3862: =item * B<EXCUSED>:
 3863: 
 3864: Excused. Not yet implemented.
 3865: 
 3866: =item * B<NETWORK_FAILURE>:
 3867: 
 3868: Information not available due to network failure.
 3869: 
 3870: =item * B<ATTEMPTED>:
 3871: 
 3872: Attempted, and not yet graded.
 3873: 
 3874: =back
 3875: 
 3876: =cut
 3877: 
 3878: sub NOT_ATTEMPTED         { return 10; }
 3879: sub INCORRECT             { return 11; }
 3880: sub INCORRECT_BY_OVERRIDE { return 12; }
 3881: sub CORRECT               { return 13; }
 3882: sub CORRECT_BY_OVERRIDE   { return 14; }
 3883: sub EXCUSED               { return 15; }
 3884: sub ATTEMPTED             { return 16; }
 3885: 
 3886: sub getCompletionStatus {
 3887:     my $self = shift;
 3888:     return $self->NETWORK_FAILURE if ($self->{NAV_MAP}->{NETWORK_FAILURE});
 3889: 
 3890:     my $status = $self->queryRestoreHash('solved', shift);
 3891: 
 3892:     # Left as separate if statements in case we ever do more with this
 3893:     if ($status eq 'correct_by_student') {return $self->CORRECT;}
 3894:     if ($status eq 'correct_by_override') {return $self->CORRECT_BY_OVERRIDE; }
 3895:     if ($status eq 'incorrect_attempted') {return $self->INCORRECT; }
 3896:     if ($status eq 'incorrect_by_override') {return $self->INCORRECT_BY_OVERRIDE; }
 3897:     if ($status eq 'excused') {return $self->EXCUSED; }
 3898:     if ($status eq 'ungraded_attempted') {return $self->ATTEMPTED; }
 3899:     return $self->NOT_ATTEMPTED;
 3900: }
 3901: 
 3902: sub queryRestoreHash {
 3903:     my $self = shift;
 3904:     my $hashentry = shift;
 3905:     my $part = shift;
 3906:     $part = "0" if (!defined($part) || $part eq '');
 3907:     return $self->NETWORK_FAILURE if ($self->{NAV_MAP}->{NETWORK_FAILURE});
 3908: 
 3909:     $self->getReturnHash();
 3910: 
 3911:     return $self->{RETURN_HASH}->{'resource.'.$part.'.'.$hashentry};
 3912: }
 3913: 
 3914: =pod
 3915: 
 3916: B<Composite Status>
 3917: 
 3918: Along with directly returning the date or completion status, the
 3919: resource object includes a convenience function B<status>() that will
 3920: combine the two status tidbits into one composite status that can
 3921: represent the status of the resource as a whole. This method represents
 3922: the concept of the thing we want to display to the user on the nav maps
 3923: screen, which is a combination of completion and open status. The precise logic is
 3924: documented in the comments of the status method. The following results
 3925: may be returned, all available as methods on the resource object
 3926: ($res->NETWORK_FAILURE): In addition to the return values that match
 3927: the date or completion status, this function can return "ANSWER_SUBMITTED"
 3928: if that problemstatus parameter value is set to No, suppressing the
 3929: incorrect/correct feedback.
 3930: 
 3931: =over 4
 3932: 
 3933: =item * B<NETWORK_FAILURE>:
 3934: 
 3935: The network has failed and the information is not available.
 3936: 
 3937: =item * B<NOTHING_SET>:
 3938: 
 3939: No dates have been set for this problem (part) at all. (Because only
 3940: certain parts of a multi-part problem may be assigned, this can not be
 3941: collapsed into "open later", as we do not know a given part will EVER
 3942: be opened. For single part, this is the same as "OPEN_LATER".)
 3943: 
 3944: =item * B<CORRECT>:
 3945: 
 3946: For any reason at all, the part is considered correct.
 3947: 
 3948: =item * B<EXCUSED>:
 3949: 
 3950: For any reason at all, the problem is excused.
 3951: 
 3952: =item * B<PAST_DUE_NO_ANSWER>:
 3953: 
 3954: The problem is past due, not considered correct, and no answer date is
 3955: set.
 3956: 
 3957: =item * B<PAST_DUE_ANSWER_LATER>:
 3958: 
 3959: The problem is past due, not considered correct, and an answer date in
 3960: the future is set.
 3961: 
 3962: =item * B<ANSWER_OPEN>:
 3963: 
 3964: The problem is past due, not correct, and the answer is now available.
 3965: 
 3966: =item * B<OPEN_LATER>:
 3967: 
 3968: The problem is not yet open.
 3969: 
 3970: =item * B<TRIES_LEFT>:
 3971: 
 3972: The problem is open, has been tried, is not correct, but there are
 3973: tries left.
 3974: 
 3975: =item * B<INCORRECT>:
 3976: 
 3977: The problem is open, and all tries have been used without getting the
 3978: correct answer.
 3979: 
 3980: =item * B<OPEN>:
 3981: 
 3982: The item is open and not yet tried.
 3983: 
 3984: =item * B<ATTEMPTED>:
 3985: 
 3986: The problem has been attempted.
 3987: 
 3988: =item * B<ANSWER_SUBMITTED>:
 3989: 
 3990: An answer has been submitted, but the student should not see it.
 3991: 
 3992: =back
 3993: 
 3994: =cut
 3995: 
 3996: sub TRIES_LEFT       { return 20; }
 3997: sub ANSWER_SUBMITTED { return 21; }
 3998: 
 3999: sub status {
 4000:     my $self = shift;
 4001:     my $part = shift;
 4002:     if (!defined($part)) { $part = "0"; }
 4003:     my $completionStatus = $self->getCompletionStatus($part);
 4004:     my $dateStatus = $self->getDateStatus($part);
 4005: 
 4006:     # What we have is a two-dimensional matrix with 4 entries on one
 4007:     # dimension and 5 entries on the other, which we want to colorize,
 4008:     # plus network failure and "no date data at all".
 4009: 
 4010:     #if ($self->{RESOURCE_ERROR}) { return NETWORK_FAILURE; }
 4011:     if ($completionStatus == NETWORK_FAILURE) { return NETWORK_FAILURE; }
 4012: 
 4013:     my $suppressFeedback = $self->problemstatus($part) eq 'no';
 4014:     # If there's an answer date and we're past it, don't
 4015:     # suppress the feedback; student should know
 4016:     if ($self->answerdate($part) && $self->answerdate($part) < time()) {
 4017: 	$suppressFeedback = 0;
 4018:     }
 4019: 
 4020:     # There are a few whole rows we can dispose of:
 4021:     if ($completionStatus == CORRECT ||
 4022:         $completionStatus == CORRECT_BY_OVERRIDE ) {
 4023:         return $suppressFeedback? ANSWER_SUBMITTED : CORRECT; 
 4024:     }
 4025: 
 4026:     if ($completionStatus == ATTEMPTED) {
 4027:         return ATTEMPTED;
 4028:     }
 4029: 
 4030:     # If it's EXCUSED, then return that no matter what
 4031:     if ($completionStatus == EXCUSED) {
 4032:         return EXCUSED; 
 4033:     }
 4034: 
 4035:     if ($dateStatus == NOTHING_SET) {
 4036:         return NOTHING_SET;
 4037:     }
 4038: 
 4039:     # Now we're down to a 4 (incorrect, incorrect_override, not_attempted)
 4040:     # by 4 matrix (date statuses).
 4041: 
 4042:     if ($dateStatus == PAST_DUE_ANSWER_LATER ||
 4043:         $dateStatus == PAST_DUE_NO_ANSWER ) {
 4044:         return $dateStatus; 
 4045:     }
 4046: 
 4047:     if ($dateStatus == ANSWER_OPEN) {
 4048:         return ANSWER_OPEN;
 4049:     }
 4050: 
 4051:     # Now: (incorrect, incorrect_override, not_attempted) x 
 4052:     # (open_later), (open)
 4053:     
 4054:     if ($dateStatus == OPEN_LATER) {
 4055:         return OPEN_LATER;
 4056:     }
 4057: 
 4058:     # If it's WRONG...
 4059:     if ($completionStatus == INCORRECT || $completionStatus == INCORRECT_BY_OVERRIDE) {
 4060:         # and there are TRIES LEFT:
 4061:         if ($self->tries($part) < $self->maxtries($part) || !$self->maxtries($part)) {
 4062:             return $suppressFeedback ? ANSWER_SUBMITTED : TRIES_LEFT;
 4063:         }
 4064:         return $suppressFeedback ? ANSWER_SUBMITTED : INCORRECT; # otherwise, return orange; student can't fix this
 4065:     }
 4066: 
 4067:     # Otherwise, it's untried and open
 4068:     return OPEN; 
 4069: }
 4070: 
 4071: sub CLOSED { return 23; }
 4072: sub ERROR { return 24; }
 4073: 
 4074: =pod
 4075: 
 4076: B<Simple Status>
 4077: 
 4078: Convenience method B<simpleStatus> provides a "simple status" for the resource.
 4079: "Simple status" corresponds to "which icon is shown on the
 4080: Navmaps". There are six "simple" statuses:
 4081: 
 4082: =over 4
 4083: 
 4084: =item * B<CLOSED>: The problem is currently closed. (No icon shown.)
 4085: 
 4086: =item * B<OPEN>: The problem is open and unattempted.
 4087: 
 4088: =item * B<CORRECT>: The problem is correct for any reason.
 4089: 
 4090: =item * B<INCORRECT>: The problem is incorrect and can still be
 4091: completed successfully.
 4092: 
 4093: =item * B<ATTEMPTED>: The problem has been attempted, but the student
 4094: does not know if they are correct. (The ellipsis icon.)
 4095: 
 4096: =item * B<ERROR>: There is an error retrieving information about this
 4097: problem.
 4098: 
 4099: =back
 4100: 
 4101: =cut
 4102: 
 4103: # This hash maps the composite status to this simple status, and
 4104: # can be used directly, if you like
 4105: my %compositeToSimple = 
 4106:     (
 4107:       NETWORK_FAILURE()       => ERROR,
 4108:       NOTHING_SET()           => CLOSED,
 4109:       CORRECT()               => CORRECT,
 4110:       EXCUSED()               => CORRECT,
 4111:       PAST_DUE_NO_ANSWER()    => INCORRECT,
 4112:       PAST_DUE_ANSWER_LATER() => INCORRECT,
 4113:       ANSWER_OPEN()           => INCORRECT,
 4114:       OPEN_LATER()            => CLOSED,
 4115:       TRIES_LEFT()            => OPEN,
 4116:       INCORRECT()             => INCORRECT,
 4117:       OPEN()                  => OPEN,
 4118:       ATTEMPTED()             => ATTEMPTED,
 4119:       ANSWER_SUBMITTED()      => ATTEMPTED
 4120:      );
 4121: 
 4122: sub simpleStatus {
 4123:     my $self = shift;
 4124:     my $part = shift;
 4125:     my $status = $self->status($part);
 4126:     return $compositeToSimple{$status};
 4127: }
 4128: 
 4129: =pod
 4130: 
 4131: B<simpleStatusCount> will return an array reference containing, in
 4132: this order, the number of OPEN, CLOSED, CORRECT, INCORRECT, ATTEMPTED,
 4133: and ERROR parts the given problem has.
 4134: 
 4135: =cut
 4136:     
 4137: # This maps the status to the slot we want to increment
 4138: my %statusToSlotMap = 
 4139:     (
 4140:      OPEN()      => 0,
 4141:      CLOSED()    => 1,
 4142:      CORRECT()   => 2,
 4143:      INCORRECT() => 3,
 4144:      ATTEMPTED() => 4,
 4145:      ERROR()     => 5
 4146:      );
 4147: 
 4148: sub statusToSlot { return $statusToSlotMap{shift()}; }
 4149: 
 4150: sub simpleStatusCount {
 4151:     my $self = shift;
 4152: 
 4153:     my @counts = (0, 0, 0, 0, 0, 0, 0);
 4154:     foreach my $part (@{$self->parts()}) {
 4155: 	$counts[$statusToSlotMap{$self->simpleStatus($part)}]++;
 4156:     }
 4157: 
 4158:     return \@counts;
 4159: }
 4160: 
 4161: =pod
 4162: 
 4163: B<Completable>
 4164: 
 4165: The completable method represents the concept of I<whether the student can
 4166: currently do the problem>. If the student can do the problem, which means
 4167: that it is open, there are tries left, and if the problem is manually graded
 4168: or the grade is suppressed via problemstatus, the student has not tried it
 4169: yet, then the method returns 1. Otherwise, it returns 0, to indicate that 
 4170: either the student has tried it and there is no feedback, or that for
 4171: some reason it is no longer completable (not open yet, successfully completed,
 4172: out of tries, etc.). As an example, this is used as the filter for the
 4173: "Uncompleted Homework" option for the nav maps.
 4174: 
 4175: If this does not quite meet your needs, do not fiddle with it (unless you are
 4176: fixing it to better match the student's conception of "completable" because
 4177: it's broken somehow)... make a new method.
 4178: 
 4179: =cut
 4180: 
 4181: sub completable {
 4182:     my $self = shift;
 4183:     if (!$self->is_problem()) { return 0; }
 4184:     my $partCount = $self->countParts();
 4185: 
 4186:     foreach my $part (@{$self->parts()}) {
 4187:         if ($part eq '0' && $partCount != 1) { next; }
 4188:         my $status = $self->status($part);
 4189:         # "If any of the parts are open, or have tries left (implies open),
 4190:         # and it is not "attempted" (manually graded problem), it is
 4191:         # not "complete"
 4192: 	if ($self->getCompletionStatus($part) == ATTEMPTED() ||
 4193: 	    $status == ANSWER_SUBMITTED() ) {
 4194: 	    # did this part already, as well as we can
 4195: 	    next;
 4196: 	}
 4197: 	if ($status == OPEN() || $status == TRIES_LEFT()) {
 4198: 	    return 1;
 4199: 	}
 4200:     }
 4201:         
 4202:     # If all the parts were complete, so was this problem.
 4203:     return 0;
 4204: }
 4205: 
 4206: =pod
 4207: 
 4208: =head2 Resource/Nav Map Navigation
 4209: 
 4210: =over 4
 4211: 
 4212: =item * B<getNext>():
 4213: 
 4214: Retreive an array of the possible next resources after this
 4215: one. Always returns an array, even in the one- or zero-element case.
 4216: 
 4217: =item * B<getPrevious>():
 4218: 
 4219: Retreive an array of the possible previous resources from this
 4220: one. Always returns an array, even in the one- or zero-element case.
 4221: 
 4222: =cut
 4223: 
 4224: sub getNext {
 4225:     my $self = shift;
 4226:     my @branches;
 4227:     my $to = $self->to();
 4228:     foreach my $branch ( split(/,/, $to) ) {
 4229:         my $choice = $self->{NAV_MAP}->getById($branch);
 4230:         my $next = $choice->goesto();
 4231:         $next = $self->{NAV_MAP}->getById($next);
 4232: 
 4233:         push @branches, $next;
 4234:     }
 4235:     return \@branches;
 4236: }
 4237: 
 4238: sub getPrevious {
 4239:     my $self = shift;
 4240:     my @branches;
 4241:     my $from = $self->from();
 4242:     foreach my $branch ( split /,/, $from) {
 4243:         my $choice = $self->{NAV_MAP}->getById($branch);
 4244:         my $prev = $choice->comesfrom();
 4245:         $prev = $self->{NAV_MAP}->getById($prev);
 4246: 
 4247:         push @branches, $prev;
 4248:     }
 4249:     return \@branches;
 4250: }
 4251: 
 4252: sub browsePriv {
 4253:     my $self = shift;
 4254:     if (defined($self->{BROWSE_PRIV})) {
 4255:         return $self->{BROWSE_PRIV};
 4256:     }
 4257: 
 4258:     $self->{BROWSE_PRIV} = &Apache::lonnet::allowed('bre', $self->src());
 4259: }
 4260: 
 4261: =pod
 4262: 
 4263: =back
 4264: 
 4265: =cut
 4266: 
 4267: 1;
 4268: 
 4269: __END__
 4270: 
 4271: 

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>