--- loncom/interface/lonnavmaps.pm 2003/02/06 21:26:21 1.138 +++ loncom/interface/lonnavmaps.pm 2009/03/27 11:33:19 1.433 @@ -1,8 +1,7 @@ - # The LearningOnline Network with CAPA # Navigate Maps Handler # -# $Id: lonnavmaps.pm,v 1.138 2003/02/06 21:26:21 bowersj2 Exp $ +# $Id: lonnavmaps.pm,v 1.433 2009/03/27 11:33:19 bisitz Exp $ # # Copyright Michigan State University Board of Trustees # @@ -26,699 +25,543 @@ # # http://www.lon-capa.org/ # -# (Page Handler -# -# (TeX Content Handler -# -# 05/29/00,05/30 Gerd Kortemeyer) -# 08/30,08/31,09/06,09/14,09/15,09/16,09/19,09/20,09/21,09/23, -# 10/02,10/10,10/14,10/16,10/18,10/19,10/31,11/6,11/14,11/16 Gerd Kortemeyer) -# -# 3/1/1,6/1,17/1,29/1,30/1,2/8,9/21,9/24,9/25 Gerd Kortemeyer -# YEAR=2002 -# 1/1 Gerd Kortemeyer -# Oct-Nov Jeremy Bowers +### -package Apache::lonnavmaps; +=pod -use strict; -use Apache::Constants qw(:common :http); -use Apache::loncommon(); -use POSIX qw (floor strftime); +=head1 NAME -my %navmaphash; -my %parmhash; +Apache::lonnavmaps.pm -# symbolic constants -sub SYMB { return 1; } -sub URL { return 2; } -sub NOTHING { return 3; } +=head1 SYNOPSIS -# Some data +Handles navigational maps. -# Keep these mappings in sync with lonquickgrades, which uses the colors -# instead of the icons. -my %statusIconMap = - ( Apache::lonnavmaps::resource->NETWORK_FAILURE => '', - Apache::lonnavmaps::resource->NOTHING_SET => '', - Apache::lonnavmaps::resource->CORRECT => 'navmap.correct.gif', - Apache::lonnavmaps::resource->EXCUSED => 'navmap.correct.gif', - Apache::lonnavmaps::resource->PAST_DUE_NO_ANSWER => 'navmap.wrong.gif', - Apache::lonnavmaps::resource->PAST_DUE_ANSWER_LATER => 'navmap.wrong.gif', - Apache::lonnavmaps::resource->ANSWER_OPEN => 'navmap.wrong.gif', - Apache::lonnavmaps::resource->OPEN_LATER => '', - Apache::lonnavmaps::resource->TRIES_LEFT => 'navmap.open.gif', - Apache::lonnavmaps::resource->INCORRECT => 'navmap.wrong.gif', - Apache::lonnavmaps::resource->OPEN => 'navmap.open.gif', - Apache::lonnavmaps::resource->ATTEMPTED => 'navmap.open.gif' ); +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 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 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: 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 accepts, +instead of passing it arguments as is normal, pass it in an anonymous +hash with the desired options. -my %iconAltTags = - ( 'navmap.correct.gif' => 'Correct', - 'navmap.wrong.gif' => 'Incorrect', - 'navmap.open.gif' => 'Open' ); +The package provides a function called 'render', called as +Apache::lonnavmaps::render({}). -# Defines a status->color mapping, null string means don't color -my %colormap = - ( Apache::lonnavmaps::resource->NETWORK_FAILURE => '', - Apache::lonnavmaps::resource->CORRECT => '', - Apache::lonnavmaps::resource->EXCUSED => '#3333FF', - Apache::lonnavmaps::resource->PAST_DUE_ANSWER_LATER => '', - Apache::lonnavmaps::resource->PAST_DUE_NO_ANSWER => '', - Apache::lonnavmaps::resource->ANSWER_OPEN => '#006600', - Apache::lonnavmaps::resource->OPEN_LATER => '', - Apache::lonnavmaps::resource->TRIES_LEFT => '', - Apache::lonnavmaps::resource->INCORRECT => '', - Apache::lonnavmaps::resource->OPEN => '', - Apache::lonnavmaps::resource->NOTHING_SET => '' ); -# And a special case in the nav map; what to do when the assignment -# is not yet done and due in less then 24 hours -my $hurryUpColor = "#FF0000"; +=head2 Overview of Columns -sub cleanup { - if (tied(%navmaphash)){ - &Apache::lonnet::logthis('Cleanup navmaps: navmaphash'); - unless (untie(%navmaphash)) { - &Apache::lonnet::logthis('Failed cleanup navmaps: navmaphash'); - } - } - if (tied(%parmhash)){ - &Apache::lonnet::logthis('Cleanup navmaps: parmhash'); - unless (untie(%parmhash)) { - &Apache::lonnet::logthis('Failed cleanup navmaps: parmhash'); - } - } -} +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 +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. -sub handler { - my $r = shift; - real_handler($r); -} +All other parameters are ways of either changing how the columns +are printing, or which rows are shown. -sub real_handler { - my $r = shift; +The pre-packaged column names are refered to by constants in the +Apache::lonnavmaps namespace. The following currently exist: - &Apache::loncommon::get_unprocessed_cgi($ENV{QUERY_STRING}); +=over 4 - # Handle header-only request - if ($r->header_only) { - if ($ENV{'browser.mathml'}) { - $r->content_type('text/xml'); - } else { - $r->content_type('text/html'); - } - $r->send_http_header; - return OK; - } +=item * B: - # Send header, don't cache this page - if ($ENV{'browser.mathml'}) { - $r->content_type('text/xml'); - } else { - $r->content_type('text/html'); - } - &Apache::loncommon::no_cache($r); - $r->send_http_header; +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