[BACK]Return to lonnavmaps.pm CVS log [TXT] [DIR] Up to [LON-CAPA] / loncom / interface

Diff for /loncom/interface/lonnavmaps.pm between versions 1.415.4.2 and 1.421

version 1.415.4.2, 2009/09/15 01:02:13 version 1.421, 2008/12/11 14:55:15
Line 27 Line 27
 #  #
 ###  ###
   
   =pod
   
   =head1 NAME
   
   Apache::lonnavmaps.pm
   
   =head1 SYNOPSIS
   
   Handles navigational maps.
   
   The main handler generates the navigational listing for the course,
   the other objects export this information in a usable fashion for
   other modules.
   
   
   This is part of the LearningOnline Network with CAPA project
   described at http://www.lon-capa.org.
   
   
   =head1 OVERVIEW
   
   X<lonnavmaps, overview> When a user enters a course, LON-CAPA examines the
   course structure and caches it in what is often referred to as the
   "big hash" X<big hash>. You can see it if you are logged into
   LON-CAPA, in a course, by going to /adm/test. (You may need to
   tweak the /home/httpd/lonTabs/htpasswd file to view it.) The
   content of the hash will be under the heading "Big Hash".
   
   Big Hash contains, among other things, how resources are related
   to each other (next/previous), what resources are maps, which 
   resources are being chosen to not show to the student (for random
   selection), and a lot of other things that can take a lot of time
   to compute due to the amount of data that needs to be collected and
   processed.
   
   Apache::lonnavmaps provides an object model for manipulating this
   information in a higher-level fashion than directly manipulating 
   the hash. It also provides access to several auxilary functions 
   that aren't necessarily stored in the Big Hash, but are a per-
   resource sort of value, like whether there is any feedback on 
   a given resource.
   
   Apache::lonnavmaps also abstracts away branching, and someday, 
   conditions, for the times where you don't really care about those
   things.
   
   Apache::lonnavmaps also provides fairly powerful routines for
   rendering navmaps, and last but not least, provides the navmaps
   view for when the user clicks the NAV button.
   
   B<Note>: Apache::lonnavmaps I<only> works for the "currently
   logged in user"; if you want things like "due dates for another
   student" lonnavmaps can not directly retrieve information like
   that. You need the EXT function. This module can still help,
   because many things, such as the course structure, are constant
   between users, and Apache::lonnavmaps can help by providing
   symbs for the EXT call.
   
   The rest of this file will cover the provided rendering routines, 
   which can often be used without fiddling with the navmap object at
   all, then documents the Apache::lonnavmaps::navmap object, which
   is the key to accessing the Big Hash information, covers the use
   of the Iterator (which provides the logic for traversing the 
   somewhat-complicated Big Hash data structure), documents the
   Apache::lonnavmaps::Resource objects that are returned by 
   
   =head1 Subroutine: render
   
   The navmap renderer package provides a sophisticated rendering of the
   standard navigation maps interface into HTML. The provided nav map
   handler is actually just a glorified call to this.
   
   Because of the large number of parameters this function accepts,
   instead of passing it arguments as is normal, pass it in an anonymous
   hash with the desired options.
   
   The package provides a function called 'render', called as
   Apache::lonnavmaps::render({}).
   
   =head2 Overview of Columns
   
   The renderer will build an HTML table for the navmap and return
   it. The table consists of several columns, and a row for each
   resource (or possibly each part). You tell the renderer how many
   columns to create and what to place in each column, optionally using
   one or more of the prepared columns, and the renderer will assemble
   the table.
   
   Any additional generally useful column types should be placed in the
   renderer code here, so anybody can use it anywhere else. Any code
   specific to the current application (such as the addition of <input>
   elements in a column) should be placed in the code of the thing using
   the renderer.
   
   At the core of the renderer is the array reference COLS (see Example
   section below for how to pass this correctly). The COLS array will
   consist of entries of one of two types of things: Either an integer
   representing one of the pre-packaged column types, or a sub reference
   that takes a resource reference, a part number, and a reference to the
   argument hash passed to the renderer, and returns a string that will
   be inserted into the HTML representation as it.
   
   All other parameters are ways of either changing how the columns
   are printing, or which rows are shown.
   
   The pre-packaged column names are refered to by constants in the
   Apache::lonnavmaps namespace. The following currently exist:
   
   =over 4
   
   =item * B<Apache::lonnavmaps::resource>:
   
   The general info about the resource: Link, icon for the type, etc. The
   first column in the standard nav map display. This column provides the
   indentation effect seen in the B<NAV> screen. This column also accepts
   the following parameters in the renderer hash:
   
   =over 4
   
   =item * B<resource_nolink>: default false
   
   If true, the resource will not be linked. By default, all non-folder
   resources are linked.
   
   =item * B<resource_part_count>: default true
   
   If true, the resource will show a part count B<if> the full
   part list is not displayed. (See "condense_parts" later.) If false,
   the resource will never show a part count.
   
   =item * B<resource_no_folder_link>:
   
   If true, the resource's folder will not be clickable to open or close
   it. Default is false. True implies printCloseAll is false, since you
   can't close or open folders when this is on anyhow.
   
   =back
   
   =item * B<Apache::lonnavmaps::communication_status>:
   
   Whether there is discussion on the resource, email for the user, or
   (lumped in here) perl errors in the execution of the problem. This is
   the second column in the main nav map.
   
   =item * B<Apache::lonnavmaps::quick_status>:
   
   An icon for the status of a problem, with five possible states:
   Correct, incorrect, open, awaiting grading (for a problem where the
   computer's grade is suppressed, or the computer can't grade, like
   essay problem), or none (not open yet, not a problem). The
   third column of the standard navmap.
   
   =item * B<Apache::lonnavmaps::long_status>:
   
   A text readout of the details of the current status of the problem,
   such as "Due in 22 hours". The fourth column of the standard navmap.
   
   =item * B<Apache::lonnavmaps::part_status_summary>:
   
   A text readout summarizing the status of the problem. If it is a
   single part problem, will display "Correct", "Incorrect", 
   "Not yet open", "Open", "Attempted", or "Error". If there are
   multiple parts, this will output a string that in HTML will show a
   status of how many parts are in each status, in color coding, trying
   to match the colors of the icons within reason.
   
   Note this only makes sense if you are I<not> showing parts. If 
   C<showParts> is true (see below), this column will not output
   anything. 
   
   =back
   
   If you add any others please be sure to document them here.
   
   An example of a column renderer that will show the ID number of a
   resource, along with the part name if any:
   
    sub { 
     my ($resource, $part, $params) = @_;   
     if ($part) { return '<td>' . $resource->{ID} . ' ' . $part . '</td>'; }
     return '<td>' . $resource->{ID} . '</td>';
    }
   
   Note these functions are responsible for the TD tags, which allow them
   to override vertical and horizontal alignment, etc.
   
   =head2 Parameters
   
   Minimally, you should be
   able to get away with just using 'cols' (to specify the columns
   shown), 'url' (necessary for the folders to link to the current screen
   correctly), and possibly 'queryString' if your app calls for it. In
   that case, maintaining the state of the folders will be done
   automatically.
   
   =over 4
   
   =item * B<iterator>: default: constructs one from %env
   
   A reference to a fresh ::iterator to use from the navmaps. The
   rendering will reflect the options passed to the iterator, so you can
   use that to just render a certain part of the course, if you like. If
   one is not passed, the renderer will attempt to construct one from
   env{'form.filter'} and env{'form.condition'} information, plus the
   'iterator_map' parameter if any.
   
   =item * B<iterator_map>: default: not used
   
   If you are letting the renderer do the iterator handling, you can
   instruct the renderer to render only a particular map by passing it
   the source of the map you want to process, like
   '/res/103/jerf/navmap.course.sequence'.
   
   =item * B<include_top_level_map>: default: false
   
   If you need to include the top level map (meaning the course) in the
   rendered output set this to true
   
   =item * B<navmap>: default: constructs one from %env
   
   A reference to a navmap, used only if an iterator is not passed in. If
   this is necessary to make an iterator but it is not passed in, a new
   one will be constructed based on env info. This is useful to do basic
   error checking before passing it off to render.
   
   =item * B<r>: default: must be passed in
   
   The standard Apache response object. This must be passed to the
   renderer or the course hash will be locked.
   
   =item * B<cols>: default: empty (useless)
   
   An array reference
   
   =item * B<showParts>:default true
   
   A flag. If true, a line for the resource itself, and a line
   for each part will be displayed. If not, only one line for each
   resource will be displayed.
   
   =item * B<condenseParts>: default true
   
   A flag. If true, if all parts of the problem have the same
   status and that status is Nothing Set, Correct, or Network Failure,
   then only one line will be displayed for that resource anyhow. If no,
   all parts will always be displayed. If showParts is 0, this is
   ignored.
   
   =item * B<jumpCount>: default: determined from %env
   
   A string identifying the URL to place the anchor 'curloc' at.
   It is the responsibility of the renderer user to
   ensure that the #curloc is in the URL. By default, determined through
   the use of the env{} 'jump' information, and should normally "just
   work" correctly.
   
   =item * B<here>: default: empty string
   
   A Symb identifying where to place the 'here' marker. The empty
   string means no marker.
   
   =item * B<indentString>: default: 25 pixel whitespace image
   
   A string identifying the indentation string to use. 
   
   =item * B<queryString>: default: empty
   
   A string which will be prepended to the query string used when the
   folders are opened or closed. You can use this to pass
   application-specific values.
   
   =item * B<url>: default: none
   
   The url the folders will link to, which should be the current
   page. Required if the resource info column is shown, and you 
   are allowing the user to open and close folders.
   
   =item * B<currentJumpIndex>: default: no jumping
   
   Describes the currently-open row number to cause the browser to jump
   to, because the user just opened that folder. By default, pulled from
   the Jump information in the env{'form.*'}.
   
   =item * B<printKey>: default: false
   
   If true, print the key that appears on the top of the standard
   navmaps.
   
   =item * B<printCloseAll>: default: true
   
   If true, print the "Close all folders" or "open all folders"
   links.
   
   =item * B<filterFunc>: default: sub {return 1;} (accept everything)
   
   A function that takes the resource object as its only parameter and
   returns a true or false value. If true, the resource is displayed. If
   false, it is simply skipped in the display.
   
   =item * B<suppressEmptySequences>: default: false
   
   If you're using a filter function, and displaying sequences to orient
   the user, then frequently some sequences will be empty. Setting this to
   true will cause those sequences not to display, so as not to confuse the
   user into thinking that if the sequence is there there should be things
   under it; for example, see the "Show Uncompleted Homework" view on the
   B<NAV> screen.
   
   =item * B<suppressNavmaps>: default: false
   
   If true, will not display Navigate Content resources. 
   
   =back
   
   =head2 Additional Info
   
   In addition to the parameters you can pass to the renderer, which will
   be passed through unchange to the column renderers, the renderer will
   generate the following information which your renderer may find
   useful:
   
   =over 4
   
   =item * B<counter>: 
   
   Contains the number of rows printed. Useful after calling the render 
   function, as you can detect whether anything was printed at all.
   
   =item * B<isNewBranch>:
   
   Useful for renderers: If this resource is currently the first resource
   of a new branch, this will be true. The Resource column (leftmost in the
   navmaps screen) uses this to display the "new branch" icon 
   
   =back
   
   =cut
   
   
   =head1 SUBROUTINES
   
   =over
   
   =item update()
   
   =item addToFilter()
   
   Convenience functions: Returns a string that adds or subtracts
   the second argument from the first hash, appropriate for the 
   query string that determines which folders to recurse on
   
   =item removeFromFilter()
   
   =item getLinkForResource()
   
   Convenience function: Given a stack returned from getStack on the iterator,
   return the correct src() value.
   
   =item getDescription()
   
   Convenience function: This separates the logic of how to create
   the problem text strings ("Due: DATE", "Open: DATE", "Not yet assigned",
   etc.) into a separate function. It takes a resource object as the
   first parameter, and the part number of the resource as the second.
   It's basically a big switch statement on the status of the resource.
   
   =item dueInLessThan24Hours()
   
   Convenience function, so others can use it: Is the problem due in less than 24 hours, and still can be done?
   
   =item lastTry()
   
   Convenience function, so others can use it: Is there only one try remaining for the
   part, with more than one try to begin with, not due yet and still can be done?
   
   =item advancedUser()
   
   This puts a human-readable name on the env variable.
   
   =item timeToHumanString()
   
   timeToHumanString takes a time number and converts it to a
   human-readable representation, meant to be used in the following
   manner:
   
   =over 4
   
   =item * print "Due $timestring"
   
   =item * print "Open $timestring"
   
   =item * print "Answer available $timestring"
   
   =back
   
   Very, very, very, VERY English-only... goodness help a localizer on
   this func...
   
   =item resource()
   
   returns 0
   
   =item communication_status()
   
   returns 1
   
   =item quick_status()
   
   returns 2
   
   =item long_status()
   
   returns 3
   
   =item part_status_summary()
   
   returns 4
   
   =item render_resource()
   
   =item render_communication_status()
   
   =item render_quick_status()
   
   =item render_long_status()
   
   =item render_parts_summary_status()
   
   =item setDefault()
   
   =item cmp_title()
   
   =item render()
   
   =item add_linkitem()
   
   =item show_linkitems()
   
   =back
   
   =cut
   
 package Apache::lonnavmaps;  package Apache::lonnavmaps;
   
 use strict;  use strict;
Line 116  this.document.navform.submit(); Line 558  this.document.navform.submit();
 ENDUPDATE  ENDUPDATE
 }  }
   
 # Convenience functions: Returns a string that adds or subtracts  
 # the second argument from the first hash, appropriate for the   
 # query string that determines which folders to recurse on  
 sub addToFilter {  sub addToFilter {
     my $hashIn = shift;      my $hashIn = shift;
     my $addition = shift;      my $addition = shift;
Line 137  sub removeFromFilter { Line 577  sub removeFromFilter {
     return join(",", keys(%hash));      return join(",", keys(%hash));
 }  }
   
 # Convenience function: Given a stack returned from getStack on the iterator,  
 # return the correct src() value.  
 sub getLinkForResource {  sub getLinkForResource {
     my $stack = shift;      my $stack = shift;
     my $res;      my $res;
Line 176  sub getLinkForResource { Line 614  sub getLinkForResource {
     return;      return;
 }  }
   
 # Convenience function: This separates the logic of how to create  
 # the problem text strings ("Due: DATE", "Open: DATE", "Not yet assigned",  
 # etc.) into a separate function. It takes a resource object as the  
 # first parameter, and the part number of the resource as the second.  
 # It's basically a big switch statement on the status of the resource.  
   
 sub getDescription {  sub getDescription {
     my $res = shift;      my $res = shift;
Line 229  sub getDescription { Line 663  sub getDescription {
         return &mt("Excused by instructor");          return &mt("Excused by instructor");
     }      }
     if ($status == $res->ATTEMPTED) {      if ($status == $res->ATTEMPTED) {
         if ($res->src() eq '/res/gci/gci/internal/submission.problem') {          return &mt("Answer submitted, not yet graded");
             return &mt('Question(s) submitted for review');  
         } else {  
             return &mt("Answer submitted, not yet graded");  
         }  
     }      }
     if ($status == $res->TRIES_LEFT) {      if ($status == $res->TRIES_LEFT) {
         my $tries = $res->tries($part);          my $tries = $res->tries($part);
         my $maxtries = $res->maxtries($part);          my $maxtries = $res->maxtries($part);
         my $triesString = "";          my $triesString = "";
         if ($tries && $maxtries) {          if ($tries && $maxtries) {
             $triesString = '<font size="-1"><i>('.&mt('[_1] of [quant,_2,try,tries] used',$tries,$maxtries).')</i></font>';              $triesString = '<font size="-1"><i>('.&mt('[_1] of [_2] tries used',$tries,$maxtries).')</i></font>';
             if ($maxtries > 1 && $maxtries - $tries == 1) {              if ($maxtries > 1 && $maxtries - $tries == 1) {
                 $triesString = "<b>$triesString</b>";                  $triesString = "<b>$triesString</b>";
             }              }
Line 253  sub getDescription { Line 683  sub getDescription {
         }          }
     }      }
     if ($status == $res->ANSWER_SUBMITTED) {      if ($status == $res->ANSWER_SUBMITTED) {
         if ($res->src() eq '/res/gci/gci/internal/submission.problem') {          return &mt('Answer submitted');
             return &mt('Question(s) submitted for review');  
         } else {  
             return &mt('Answer submitted');  
         }  
     }      }
 }  }
   
 # Convenience function, so others can use it: Is the problem due in less than  
 # 24 hours, and still can be done?  
   
 sub dueInLessThan24Hours {  sub dueInLessThan24Hours {
     my $res = shift;      my $res = shift;
Line 275  sub dueInLessThan24Hours { Line 699  sub dueInLessThan24Hours {
     $res->duedate($part) > time();      $res->duedate($part) > time();
 }  }
   
 # Convenience function, so others can use it: Is there only one try remaining for the  
 # part, with more than one try to begin with, not due yet and still can be done?  
 sub lastTry {  sub lastTry {
     my $res = shift;      my $res = shift;
     my $part = shift;      my $part = shift;
Line 288  sub lastTry { Line 711  sub lastTry {
         $res->duedate($part) > time();          $res->duedate($part) > time();
 }  }
   
 # This puts a human-readable name on the env variable.  
   
 sub advancedUser {  sub advancedUser {
     return $env{'request.role.adv'};      return $env{'request.role.adv'};
 }  }
   
   
 # timeToHumanString takes a time number and converts it to a  
 # human-readable representation, meant to be used in the following  
 # manner:  
 # print "Due $timestring"  
 # print "Open $timestring"  
 # print "Answer available $timestring"  
 # Very, very, very, VERY English-only... goodness help a localizer on  
 # this func...  
   
   
 sub timeToHumanString {  sub timeToHumanString {
     my ($time,$type,$format) = @_;      my ($time,$type,$format) = @_;
   
Line 423  sub timeToHumanString { Line 834  sub timeToHumanString {
 }  }
   
   
 =pod  
   
 =head1 NAME  
   
 Apache::lonnavmap - Subroutines to handle and render the navigation  
     maps  
   
 =head1 SYNOPSIS  
   
 The main handler generates the navigational listing for the course,  
 the other objects export this information in a usable fashion for  
 other modules.  
   
 =head1 OVERVIEW  
   
 X<lonnavmaps, overview> When a user enters a course, LON-CAPA examines the  
 course structure and caches it in what is often referred to as the  
 "big hash" X<big hash>. You can see it if you are logged into  
 LON-CAPA, in a course, by going to /adm/test. (You may need to  
 tweak the /home/httpd/lonTabs/htpasswd file to view it.) The  
 content of the hash will be under the heading "Big Hash".  
   
 Big Hash contains, among other things, how resources are related  
 to each other (next/previous), what resources are maps, which   
 resources are being chosen to not show to the student (for random  
 selection), and a lot of other things that can take a lot of time  
 to compute due to the amount of data that needs to be collected and  
 processed.  
   
 Apache::lonnavmaps provides an object model for manipulating this  
 information in a higher-level fashion than directly manipulating   
 the hash. It also provides access to several auxilary functions   
 that aren't necessarily stored in the Big Hash, but are a per-  
 resource sort of value, like whether there is any feedback on   
 a given resource.  
   
 Apache::lonnavmaps also abstracts away branching, and someday,   
 conditions, for the times where you don't really care about those  
 things.  
   
 Apache::lonnavmaps also provides fairly powerful routines for  
 rendering navmaps, and last but not least, provides the navmaps  
 view for when the user clicks the NAV button.  
   
 B<Note>: Apache::lonnavmaps I<only> works for the "currently  
 logged in user"; if you want things like "due dates for another  
 student" lonnavmaps can not directly retrieve information like  
 that. You need the EXT function. This module can still help,  
 because many things, such as the course structure, are constant  
 between users, and Apache::lonnavmaps can help by providing  
 symbs for the EXT call.  
   
 The rest of this file will cover the provided rendering routines,   
 which can often be used without fiddling with the navmap object at  
 all, then documents the Apache::lonnavmaps::navmap object, which  
 is the key to accessing the Big Hash information, covers the use  
 of the Iterator (which provides the logic for traversing the   
 somewhat-complicated Big Hash data structure), documents the  
 Apache::lonnavmaps::Resource objects that are returned by   
   
 =head1 Subroutine: render  
   
 The navmap renderer package provides a sophisticated rendering of the  
 standard navigation maps interface into HTML. The provided nav map  
 handler is actually just a glorified call to this.  
   
 Because of the large number of parameters this function accepts,  
 instead of passing it arguments as is normal, pass it in an anonymous  
 hash with the desired options.  
   
 The package provides a function called 'render', called as  
 Apache::lonnavmaps::render({}).  
   
 =head2 Overview of Columns  
   
 The renderer will build an HTML table for the navmap and return  
 it. The table consists of several columns, and a row for each  
 resource (or possibly each part). You tell the renderer how many  
 columns to create and what to place in each column, optionally using  
 one or more of the prepared columns, and the renderer will assemble  
 the table.  
   
 Any additional generally useful column types should be placed in the  
 renderer code here, so anybody can use it anywhere else. Any code  
 specific to the current application (such as the addition of <input>  
 elements in a column) should be placed in the code of the thing using  
 the renderer.  
   
 At the core of the renderer is the array reference COLS (see Example  
 section below for how to pass this correctly). The COLS array will  
 consist of entries of one of two types of things: Either an integer  
 representing one of the pre-packaged column types, or a sub reference  
 that takes a resource reference, a part number, and a reference to the  
 argument hash passed to the renderer, and returns a string that will  
 be inserted into the HTML representation as it.  
   
 All other parameters are ways of either changing how the columns  
 are printing, or which rows are shown.  
   
 The pre-packaged column names are refered to by constants in the  
 Apache::lonnavmaps namespace. The following currently exist:  
   
 =over 4  
   
 =item * B<Apache::lonnavmaps::resource>:  
   
 The general info about the resource: Link, icon for the type, etc. The  
 first column in the standard nav map display. This column provides the  
 indentation effect seen in the B<NAV> screen. This column also accepts  
 the following parameters in the renderer hash:  
   
 =over 4  
   
 =item * B<resource_nolink>: default false  
   
 If true, the resource will not be linked. By default, all non-folder  
 resources are linked.  
   
 =item * B<resource_part_count>: default true  
   
 If true, the resource will show a part count B<if> the full  
 part list is not displayed. (See "condense_parts" later.) If false,  
 the resource will never show a part count.  
   
 =item * B<resource_no_folder_link>:  
   
 If true, the resource's folder will not be clickable to open or close  
 it. Default is false. True implies printCloseAll is false, since you  
 can't close or open folders when this is on anyhow.  
   
 =back  
   
 =item * B<Apache::lonnavmaps::communication_status>:  
   
 Whether there is discussion on the resource, email for the user, or  
 (lumped in here) perl errors in the execution of the problem. This is  
 the second column in the main nav map.  
   
 =item * B<Apache::lonnavmaps::quick_status>:  
   
 An icon for the status of a problem, with five possible states:  
 Correct, incorrect, open, awaiting grading (for a problem where the  
 computer's grade is suppressed, or the computer can't grade, like  
 essay problem), or none (not open yet, not a problem). The  
 third column of the standard navmap.  
   
 =item * B<Apache::lonnavmaps::long_status>:  
   
 A text readout of the details of the current status of the problem,  
 such as "Due in 22 hours". The fourth column of the standard navmap.  
   
 =item * B<Apache::lonnavmaps::part_status_summary>:  
   
 A text readout summarizing the status of the problem. If it is a  
 single part problem, will display "Correct", "Incorrect",   
 "Not yet open", "Open", "Attempted", or "Error". If there are  
 multiple parts, this will output a string that in HTML will show a  
 status of how many parts are in each status, in color coding, trying  
 to match the colors of the icons within reason.  
   
 Note this only makes sense if you are I<not> showing parts. If   
 C<showParts> is true (see below), this column will not output  
 anything.   
   
 =back  
   
 If you add any others please be sure to document them here.  
   
 An example of a column renderer that will show the ID number of a  
 resource, along with the part name if any:  
   
  sub {   
   my ($resource, $part, $params) = @_;     
   if ($part) { return '<td>' . $resource->{ID} . ' ' . $part . '</td>'; }  
   return '<td>' . $resource->{ID} . '</td>';  
  }  
   
 Note these functions are responsible for the TD tags, which allow them  
 to override vertical and horizontal alignment, etc.  
   
 =head2 Parameters  
   
 Minimally, you should be  
 able to get away with just using 'cols' (to specify the columns  
 shown), 'url' (necessary for the folders to link to the current screen  
 correctly), and possibly 'queryString' if your app calls for it. In  
 that case, maintaining the state of the folders will be done  
 automatically.  
   
 =over 4  
   
 =item * B<iterator>: default: constructs one from %env  
   
 A reference to a fresh ::iterator to use from the navmaps. The  
 rendering will reflect the options passed to the iterator, so you can  
 use that to just render a certain part of the course, if you like. If  
 one is not passed, the renderer will attempt to construct one from  
 env{'form.filter'} and env{'form.condition'} information, plus the  
 'iterator_map' parameter if any.  
   
 =item * B<iterator_map>: default: not used  
   
 If you are letting the renderer do the iterator handling, you can  
 instruct the renderer to render only a particular map by passing it  
 the source of the map you want to process, like  
 '/res/103/jerf/navmap.course.sequence'.  
   
 =item * B<include_top_level_map>: default: false  
   
 If you need to include the top level map (meaning the course) in the  
 rendered output set this to true  
   
 =item * B<navmap>: default: constructs one from %env  
   
 A reference to a navmap, used only if an iterator is not passed in. If  
 this is necessary to make an iterator but it is not passed in, a new  
 one will be constructed based on env info. This is useful to do basic  
 error checking before passing it off to render.  
   
 =item * B<r>: default: must be passed in  
   
 The standard Apache response object. This must be passed to the  
 renderer or the course hash will be locked.  
   
 =item * B<cols>: default: empty (useless)  
   
 An array reference  
   
 =item * B<showParts>:default true  
   
 A flag. If true, a line for the resource itself, and a line  
 for each part will be displayed. If not, only one line for each  
 resource will be displayed.  
   
 =item * B<condenseParts>: default true  
   
 A flag. If true, if all parts of the problem have the same  
 status and that status is Nothing Set, Correct, or Network Failure,  
 then only one line will be displayed for that resource anyhow. If no,  
 all parts will always be displayed. If showParts is 0, this is  
 ignored.  
   
 =item * B<jumpCount>: default: determined from %env  
   
 A string identifying the URL to place the anchor 'curloc' at.  
 It is the responsibility of the renderer user to  
 ensure that the #curloc is in the URL. By default, determined through  
 the use of the env{} 'jump' information, and should normally "just  
 work" correctly.  
   
 =item * B<here>: default: empty string  
   
 A Symb identifying where to place the 'here' marker. The empty  
 string means no marker.  
   
 =item * B<indentString>: default: 25 pixel whitespace image  
   
 A string identifying the indentation string to use.   
   
 =item * B<queryString>: default: empty  
   
 A string which will be prepended to the query string used when the  
 folders are opened or closed. You can use this to pass  
 application-specific values.  
   
 =item * B<url>: default: none  
   
 The url the folders will link to, which should be the current  
 page. Required if the resource info column is shown, and you   
 are allowing the user to open and close folders.  
   
 =item * B<currentJumpIndex>: default: no jumping  
   
 Describes the currently-open row number to cause the browser to jump  
 to, because the user just opened that folder. By default, pulled from  
 the Jump information in the env{'form.*'}.  
   
 =item * B<printKey>: default: false  
   
 If true, print the key that appears on the top of the standard  
 navmaps.  
   
 =item * B<printCloseAll>: default: true  
   
 If true, print the "Close all folders" or "open all folders"  
 links.  
   
 =item * B<filterFunc>: default: sub {return 1;} (accept everything)  
   
 A function that takes the resource object as its only parameter and  
 returns a true or false value. If true, the resource is displayed. If  
 false, it is simply skipped in the display.  
   
 =item * B<suppressEmptySequences>: default: false  
   
 If you're using a filter function, and displaying sequences to orient  
 the user, then frequently some sequences will be empty. Setting this to  
 true will cause those sequences not to display, so as not to confuse the  
 user into thinking that if the sequence is there there should be things  
 under it; for example, see the "Show Uncompleted Homework" view on the  
 B<NAV> screen.  
   
 =item * B<suppressNavmaps>: default: false  
   
 If true, will not display Navigate Content resources.   
   
 =back  
   
 =head2 Additional Info  
   
 In addition to the parameters you can pass to the renderer, which will  
 be passed through unchange to the column renderers, the renderer will  
 generate the following information which your renderer may find  
 useful:  
   
 =over 4  
   
 =item * B<counter>:   
   
 Contains the number of rows printed. Useful after calling the render   
 function, as you can detect whether anything was printed at all.  
   
 =item * B<isNewBranch>:  
   
 Useful for renderers: If this resource is currently the first resource  
 of a new branch, this will be true. The Resource column (leftmost in the  
 navmaps screen) uses this to display the "new branch" icon   
   
 =back  
   
 =cut  
   
 sub resource { return 0; }  sub resource { return 0; }
 sub communication_status { return 1; }  sub communication_status { return 1; }
 sub quick_status { return 2; }  sub quick_status { return 2; }
Line 887  sub render_resource { Line 966  sub render_resource {
     # Is this the current resource?      # Is this the current resource?
     if (!$params->{'displayedHereMarker'} &&       if (!$params->{'displayedHereMarker'} && 
         $resource->symb() eq $params->{'here'} ) {          $resource->symb() eq $params->{'here'} ) {
         $curMarkerBegin = '<font color="red" size="+2">&gt;</font>';          $curMarkerBegin = '<span class="LC_fontcolor_red LC_fontsize_large">&gt;</span>';
         $curMarkerEnd = '<font color="red" size="+2">&lt;</font>';          $curMarkerEnd = '<span class="LC_fontcolor_red LC_fontsize_large">&lt;</span>';
         $params->{'displayedHereMarker'} = 1;          $params->{'displayedHereMarker'} = 1;
     }      }
   
Line 941  sub render_communication_status { Line 1020  sub render_communication_status {
             if ($msgid) {              if ($msgid) {
                 $feedbackHTML .= '&nbsp;<a '.$target.' href="/adm/email?display='                  $feedbackHTML .= '&nbsp;<a '.$target.' href="/adm/email?display='
                     . &escape($msgid) . '">'                      . &escape($msgid) . '">'
                     . '<img alt="'.&mt('New Email').'" src="'.$location.'/feedback.gif" '                      . '<img alt="'.&mt('New E-mail').'" src="'.$location.'/feedback.gif" '
                     . 'border="0" /></a>';                      . 'border="0" /></a>';
             }              }
         }          }
Line 1190  sub render { Line 1269  sub render {
         if (!defined($navmap)) {          if (!defined($navmap)) {
             $navmap = Apache::lonnavmaps::navmap->new();              $navmap = Apache::lonnavmaps::navmap->new();
     if (!defined($navmap)) {      if (!defined($navmap)) {
  # no longer in course   # no londer in course
  return '<span class="LC_error">'.&mt('No course selected').'</span><br />   return '<span class="LC_error">'.&mt('No course selected').'</span><br />
                         <a href="/adm/roles">'.&mt('Select a course').'</a><br />';                          <a href="/adm/roles">'.&mt('Select a course').'</a><br />';
     }      }
Line 1258  sub render { Line 1337  sub render {
         # Step 1: Check to see if we have a navmap          # Step 1: Check to see if we have a navmap
         if (!defined($navmap)) {          if (!defined($navmap)) {
             $navmap = Apache::lonnavmaps::navmap->new();              $navmap = Apache::lonnavmaps::navmap->new();
             if (!defined($navmap)) {  
                 # no longer in course  
                 return '<span class="LC_error">'.&mt('No course selected').'</span><br />  
                         <a href="/adm/roles">'.&mt('Select a course').'</a><br />';  
             }  
         }          }
   
         # See if we're being passed a specific map          # See if we're being passed a specific map
Line 1772  ENDBLOCK Line 1846  ENDBLOCK
   
 1;  1;
   
   
   
   
   
   
   
   
   
 package Apache::lonnavmaps::navmap;  package Apache::lonnavmaps::navmap;
   
 =pod  =pod
Removed from v.1.415.4.2  
changed lines
  Added in v.1.421

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