--- loncom/interface/lonnavmaps.pm 2003/07/14 15:01:07 1.213 +++ loncom/interface/lonnavmaps.pm 2003/08/21 18:29:54 1.219.2.1 @@ -1,7 +1,7 @@ # The LearningOnline Network with CAPA # Navigate Maps Handler # -# $Id: lonnavmaps.pm,v 1.213 2003/07/14 15:01:07 bowersj2 Exp $ +# $Id: lonnavmaps.pm,v 1.219.2.1 2003/08/21 18:29:54 albertel Exp $ # # Copyright Michigan State University Board of Trustees # @@ -73,7 +73,7 @@ my %statusIconMap = $resObj->INCORRECT => 'navmap.wrong.gif', $resObj->OPEN => 'navmap.open.gif', $resObj->ATTEMPTED => 'navmap.ellipsis.gif', - $resObj->ANSWER_SUBMITTED => '' ); + $resObj->ANSWER_SUBMITTED => 'navmap.ellipsis.gif' ); my %iconAltTags = ( 'navmap.correct.gif' => 'Correct', @@ -552,7 +552,8 @@ sub timeToHumanString { =head1 NAME -Apache::lonnavmap - Subroutines to handle and render the navigation maps +Apache::lonnavmap - Subroutines to handle and render the navigation + maps =head1 SYNOPSIS @@ -560,18 +561,62 @@ The main handler generates the navigatio the other objects export this information in a usable fashion for other modules. +=head1 OVERVIEW + +X 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. 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: Apache::lonnavmaps I works for the "currently +logged in user"; if you want things like "due dates for another +student" lonnavmaps can not directly retrieve information like +that. You need the EXT function. This module can still help, +because many things, such as the course structure, are constant +between users, and Apache::lonnavmaps can help by providing +symbs for the EXT call. + +The rest of this file will cover the provided rendering routines, +which can often be used without fiddling with the navmap object at +all, then documents the Apache::lonnavmaps::navmap object, which +is the key to accessing the Big Hash information, covers the use +of the Iterator (which provides the logic for traversing the +somewhat-complicated Big Hash data structure), documents the +Apache::lonnavmaps::Resource objects that are returned by + =head1 Subroutine: render The navmap renderer package provides a sophisticated rendering of the standard navigation maps interface into HTML. The provided nav map handler is actually just a glorified call to this. -Because of the large number of parameters this function presents, +Because of the large number of parameters this function accepts, instead of passing it arguments as is normal, pass it in an anonymous -hash with the given options. This is because there is no obvious order -you may wish to override these in and a hash is easier to read and -understand then "undef, undef, undef, 1, undef, undef, renderButton, -undef, 0" when you mostly want default behaviors. +hash with the desired options. The package provides a function called 'render', called as Apache::lonnavmaps::render({}). @@ -599,29 +644,33 @@ that takes a resource reference, a part argument hash passed to the renderer, and returns a string that will be inserted into the HTML representation as it. +All other parameters are ways of either changing how the columns +are printing, or which rows are shown. + The pre-packaged column names are refered to by constants in the Apache::lonnavmaps namespace. The following currently exist: =over 4 -=item * B: +=item * B: 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