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

Diff for /loncom/interface/lonnavmaps.pm between versions 1.215 and 1.216

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

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