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

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

version 1.216, 2003/07/17 18:40:49 version 1.221, 2003/08/07 17:26:44
Line 129  sub real_handler { Line 129  sub real_handler {
     $r->send_http_header;      $r->send_http_header;
   
     # Create the nav map      # Create the nav map
     my $navmap = Apache::lonnavmaps::navmap->new(      my $navmap = Apache::lonnavmaps::navmap->new();
                         $ENV{"request.course.fn"}.".db",  
                         $ENV{"request.course.fn"}."_parms.db", 1, 1);  
   
   
     if (!defined($navmap)) {      if (!defined($navmap)) {
Line 161  sub real_handler { Line 159  sub real_handler {
   
     $r->rflush();      $r->rflush();
   
     # Now that we've displayed some stuff to the user, init the navmap  
     $navmap->init();  
   
     $r->rflush();  
   
     # Check that it's defined      # Check that it's defined
     if (!($navmap->courseMapDefined())) {      if (!($navmap->courseMapDefined())) {
         $r->print('<font size="+2" color="red">Coursemap undefined.</font>' .          $r->print('<font size="+2" color="red">Coursemap undefined.</font>' .
Line 552  sub timeToHumanString { Line 545  sub timeToHumanString {
   
 =head1 NAME  =head1 NAME
   
 Apache::lonnavmap - Subroutines to handle and render the navigation maps  Apache::lonnavmap - Subroutines to handle and render the navigation
       maps
   
 =head1 SYNOPSIS  =head1 SYNOPSIS
   
Line 562  other modules. Line 556  other modules.
   
 =head1 OVERVIEW  =head1 OVERVIEW
   
 When a user enters a course, LON-CAPA examines the course structure  X<lonnavmaps, overview> When a user enters a course, LON-CAPA examines the
 and caches it in what is often referred to as the "big hash". You  course structure and caches it in what is often referred to as the
 can see it if you are logged into LON-CAPA, in a course, by going  "big hash" X<big hash>. You can see it if you are logged into
 to /adm/test. (You may need to tweak the /home/httpd/lonTabs/htpasswd  LON-CAPA, in a course, by going to /adm/test. (You may need to
 file to view it.) The content of the hash will be under the heading  tweak the /home/httpd/lonTabs/htpasswd file to view it.) The
 "Big Hash".  content of the hash will be under the heading "Big Hash".
   
 Big Hash contains, among other things, how resources are related  Big Hash contains, among other things, how resources are related
 to each other (next/previous), what resources are maps, which   to each other (next/previous), what resources are maps, which 
Line 716  to override vertical and horizontal alig Line 710  to override vertical and horizontal alig
   
 =head2 Parameters  =head2 Parameters
   
 Most of these parameters are only useful if you are *not* using the  Minimally, you should be
 folder interface (i.e., the default first column), which is probably  
 the common case. If you are using this interface, then you should be  
 able to get away with just using 'cols' (to specify the columns  able to get away with just using 'cols' (to specify the columns
 shown), 'url' (necessary for the folders to link to the current screen  shown), 'url' (necessary for the folders to link to the current screen
 correctly), and possibly 'queryString' if your app calls for it. In  correctly), and possibly 'queryString' if your app calls for it. In
Line 1173  sub render { Line 1165  sub render {
     if (!$ENV{'form.folderManip'} && !defined($args->{'iterator'})) {      if (!$ENV{'form.folderManip'} && !defined($args->{'iterator'})) {
         # 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();
                         $ENV{"request.course.fn"}.".db",  
                         $ENV{"request.course.fn"}."_parms.db", 1, 1);  
             $mustCloseNavMap = 1;              $mustCloseNavMap = 1;
         }          }
         $navmap->init();  
   
         # Step two: Locate what kind of here marker is necessary          # Step two: Locate what kind of here marker is necessary
         # Determine where the "here" marker is and where the screen jumps to.          # Determine where the "here" marker is and where the screen jumps to.
Line 1239  sub render { Line 1228  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($r,               $navmap = Apache::lonnavmaps::navmap->new();
                         $ENV{"request.course.fn"}.".db",  
                         $ENV{"request.course.fn"}."_parms.db", 1, 1);  
             $mustCloseNavMap = 1;              $mustCloseNavMap = 1;
         }          }
         # Paranoia: Make sure it's ready  
         $navmap->init();  
   
         # See if we're being passed a specific map          # See if we're being passed a specific map
         if ($args->{'iterator_map'}) {          if ($args->{'iterator_map'}) {
Line 1605  package Apache::lonnavmaps::navmap; Line 1590  package Apache::lonnavmaps::navmap;
   
 =head1 Object: Apache::lonnavmaps::navmap  =head1 Object: Apache::lonnavmaps::navmap
   
 You must obtain resource objects through the navmap object.  =head2 Overview
   
   The navmap object's job is to provide access to the resources
   in the course as Apache::lonnavmaps::resource objects, and to
   query and manage the relationship between those resource objects.
   
   Generally, you'll use the navmap object in one of three basic ways.
   In order of increasing complexity and power:
   
   =over 4
   
   =item * C<$navmap-E<gt>getByX>, where X is B<Id>, B<Symb>, B<Url> or B<MapPc>. This provides
       various ways to obtain resource objects, based on various identifiers.
       Use this when you want to request information about one object or 
       a handful of resources you already know the identities of, from some
       other source. For more about Ids, Symbs, and MapPcs, see the
       Resource documentation. Note that Url should be a B<last resort>,
       not your first choice; it only works when there is only one
       instance of the resource in the course, which only applies to
       maps, and even that may change in the future.
   
   =item * C<my @resources = $navmap-E<gt>retrieveResources(args)>. This
       retrieves resources matching some criterion and returns them
       in a flat array, with no structure information. Use this when
       you are manipulating a series of resources, based on what map
       the are in, but do not care about branching, or exactly how
       the maps and resources are related. This is the most common case.
   
   =item * C<$it = $navmap-E<gt>getIterator(args)>. This allows you traverse
       the course's navmap in various ways without writing the traversal
       code yourself. See iterator documentation below. Use this when
       you need to know absolutely everything about the course, including
       branches and the precise relationship between maps and resources.
   
   =back
   
   =head2 Creation And Destruction
   
 =head2 Creation  To create a navmap object, use the following function:
   
 =over 4  =over 4
   
 =item * B<new>(navHashFile, parmHashFile, genCourseAndUserOptions,  =item * B<Apache::lonnavmaps::navmap-E<gt>new>():
   genMailDiscussStatus, getUserData):  
   
 Binds a new navmap object to the compiled nav map hash and parm hash  Creates a new navmap object. Returns the navmap object if this is
 given as filenames. genCourseAndUserOptions is a flag saying whether  successful, or B<undef> if not.
 the course options and user options hash should be generated. This is  
 for when you are using the parameters of the resources that require  
 them; see documentation in resource object  
 documentation. genMailDiscussStatus causes the nav map to retreive  
 information about the email and discussion status of  
 resources. Returns the navmap object if this is successful, or  
 B<undef> if not. You must check for undef; errors will occur when you  
 try to use the other methods otherwise. getUserData, if true, will   
 retreive the user's performance data for various problems.  
   
 =back  =back
   
   When you are done with the $navmap object, you I<must> call 
   $navmap->untieHashes(), or you'll prevent the current user from using that 
   course until the web server is restarted. (!)
   
 =head2 Methods  =head2 Methods
   
 =over 4  =over 4
Line 1647  sub new { Line 1662  sub new {
     my $class = ref($proto) || $proto;      my $class = ref($proto) || $proto;
     my $self = {};      my $self = {};
   
     $self->{NAV_HASH_FILE} = shift;  
     $self->{PARM_HASH_FILE} = shift;  
     $self->{GENERATE_COURSE_USER_OPT} = shift;  
     $self->{GENERATE_EMAIL_DISCUSS_STATUS} = shift;  
     $self->{GET_USER_DATA} = shift;  
   
     # Resource cache stores navmap resources as we reference them. We generate      # Resource cache stores navmap resources as we reference them. We generate
     # them on-demand so we don't pay for creating resources unless we use them.      # them on-demand so we don't pay for creating resources unless we use them.
     $self->{RESOURCE_CACHE} = {};      $self->{RESOURCE_CACHE} = {};
Line 1665  sub new { Line 1674  sub new {
   
     my %navmaphash;      my %navmaphash;
     my %parmhash;      my %parmhash;
     if (!(tie(%navmaphash, 'GDBM_File', $self->{NAV_HASH_FILE},      my $courseFn = $ENV{"request.course.fn"};
       if (!(tie(%navmaphash, 'GDBM_File', "${courseFn}.db",
               &GDBM_READER(), 0640))) {                &GDBM_READER(), 0640))) {
         return undef;          return undef;
     }      }
           
     if (!(tie(%parmhash, 'GDBM_File', $self->{PARM_HASH_FILE},      if (!(tie(%parmhash, 'GDBM_File', "${courseFn}_parms.db",
               &GDBM_READER(), 0640)))                &GDBM_READER(), 0640)))
     {      {
         untie %{$self->{PARM_HASH}};          untie %{$self->{PARM_HASH}};
Line 1679  sub new { Line 1689  sub new {
   
     $self->{NAV_HASH} = \%navmaphash;      $self->{NAV_HASH} = \%navmaphash;
     $self->{PARM_HASH} = \%parmhash;      $self->{PARM_HASH} = \%parmhash;
     $self->{INITED} = 0;      $self->{PARM_CACHE} = {};
   
     bless($self);      bless($self);
                   
     return $self;      return $self;
 }  }
   
 sub init {  sub generate_course_user_opt {
     my $self = shift;      my $self = shift;
     if ($self->{INITED}) { return; }      if ($self->{COURSE_USER_OPT_GENERATED}) { return; }
   
     # If the course opt hash and the user opt hash should be generated,      my $uname=$ENV{'user.name'};
     # generate them      my $udom=$ENV{'user.domain'};
     if ($self->{GENERATE_COURSE_USER_OPT}) {      my $uhome=$ENV{'user.home'};
         my $uname=$ENV{'user.name'};      my $cid=$ENV{'request.course.id'};
         my $udom=$ENV{'user.domain'};      my $chome=$ENV{'course.'.$cid.'.home'};
         my $uhome=$ENV{'user.home'};      my ($cdom,$cnum)=split(/\_/,$cid);
         my $cid=$ENV{'request.course.id'};      
         my $chome=$ENV{'course.'.$cid.'.home'};      my $userprefix=$uname.'_'.$udom.'_';
         my ($cdom,$cnum)=split(/\_/,$cid);      
               my %courserdatas; my %useropt; my %courseopt; my %userrdatas;
         my $userprefix=$uname.'_'.$udom.'_';      unless ($uhome eq 'no_host') { 
           
         my %courserdatas; my %useropt; my %courseopt; my %userrdatas;  
         unless ($uhome eq 'no_host') {   
 # ------------------------------------------------- Get coursedata (if present)  # ------------------------------------------------- Get coursedata (if present)
             unless ((time-$courserdatas{$cid.'.last_cache'})<240) {   unless ((time-$courserdatas{$cid.'.last_cache'})<240) {
                 my $reply=&Apache::lonnet::reply('dump:'.$cdom.':'.$cnum.      my $reply=&Apache::lonnet::reply('dump:'.$cdom.':'.$cnum.
                                                  ':resourcedata',$chome);       ':resourcedata',$chome);
                 # Check for network failure      # Check for network failure
                 if ( $reply =~ /no.such.host/i || $reply =~ /con_lost/i) {      if ( $reply =~ /no.such.host/i || $reply =~ /con_lost/i) {
                     $self->{NETWORK_FAILURE} = 1;   $self->{NETWORK_FAILURE} = 1;
                 } elsif ($reply!~/^error\:/) {      } elsif ($reply!~/^error\:/) {
                     $courserdatas{$cid}=$reply;   $courserdatas{$cid}=$reply;
                     $courserdatas{$cid.'.last_cache'}=time;   $courserdatas{$cid.'.last_cache'}=time;
                 }      }
             }   }
             foreach (split(/\&/,$courserdatas{$cid})) {   foreach (split(/\&/,$courserdatas{$cid})) {
                 my ($name,$value)=split(/\=/,$_);      my ($name,$value)=split(/\=/,$_);
                 $courseopt{$userprefix.&Apache::lonnet::unescape($name)}=      $courseopt{$userprefix.&Apache::lonnet::unescape($name)}=
                     &Apache::lonnet::unescape($value);   &Apache::lonnet::unescape($value);
             }   }
 # --------------------------------------------------- Get userdata (if present)  # --------------------------------------------------- Get userdata (if present)
             unless ((time-$userrdatas{$uname.'___'.$udom.'.last_cache'})<240) {   unless ((time-$userrdatas{$uname.'___'.$udom.'.last_cache'})<240) {
                 my $reply=&Apache::lonnet::reply('dump:'.$udom.':'.$uname.':resourcedata',$uhome);      my $reply=&Apache::lonnet::reply('dump:'.$udom.':'.$uname.':resourcedata',$uhome);
                 if ($reply!~/^error\:/) {      if ($reply!~/^error\:/) {
                     $userrdatas{$uname.'___'.$udom}=$reply;   $userrdatas{$uname.'___'.$udom}=$reply;
                     $userrdatas{$uname.'___'.$udom.'.last_cache'}=time;   $userrdatas{$uname.'___'.$udom.'.last_cache'}=time;
                 }      }
                 # check to see if network failed      # check to see if network failed
                 elsif ( $reply=~/no.such.host/i || $reply=~/con.*lost/i )      elsif ( $reply=~/no.such.host/i || $reply=~/con.*lost/i )
                 {      {
                     $self->{NETWORK_FAILURE} = 1;   $self->{NETWORK_FAILURE} = 1;
                 }      }
             }   }
             foreach (split(/\&/,$userrdatas{$uname.'___'.$udom})) {   foreach (split(/\&/,$userrdatas{$uname.'___'.$udom})) {
                 my ($name,$value)=split(/\=/,$_);      my ($name,$value)=split(/\=/,$_);
                 $useropt{$userprefix.&Apache::lonnet::unescape($name)}=      $useropt{$userprefix.&Apache::lonnet::unescape($name)}=
                     &Apache::lonnet::unescape($value);   &Apache::lonnet::unescape($value);
             }   }
             $self->{COURSE_OPT} = \%courseopt;   $self->{COURSE_OPT} = \%courseopt;
             $self->{USER_OPT} = \%useropt;   $self->{USER_OPT} = \%useropt;
         }  
     }     
   
     if ($self->{GENERATE_EMAIL_DISCUSS_STATUS}) {  
         my $cid=$ENV{'request.course.id'};  
         my ($cdom,$cnum)=split(/\_/,$cid);  
           
         my %emailstatus = &Apache::lonnet::dump('email_status');  
         my $logoutTime = $emailstatus{'logout'};  
         my $courseLeaveTime = $emailstatus{'logout_'.$ENV{'request.course.id'}};  
         $self->{LAST_CHECK} = (($courseLeaveTime > $logoutTime) ?  
                                $courseLeaveTime : $logoutTime);  
         my %discussiontime = &Apache::lonnet::dump('discussiontimes',   
                                                    $cdom, $cnum);  
         my %feedback=();  
         my %error=();  
         my $keys = &Apache::lonnet::reply('keys:'.  
                                           $ENV{'user.domain'}.':'.  
                                           $ENV{'user.name'}.':nohist_email',  
                                           $ENV{'user.home'});  
   
         foreach my $msgid (split(/\&/, $keys)) {  
             $msgid=&Apache::lonnet::unescape($msgid);  
             my $plain=&Apache::lonnet::unescape(&Apache::lonnet::unescape($msgid));  
             if ($plain=~/(Error|Feedback) \[([^\]]+)\]/) {  
                 my ($what,$url)=($1,$2);  
                 my %status=  
                     &Apache::lonnet::get('email_status',[$msgid]);  
                 if ($status{$msgid}=~/^error\:/) {   
                     $status{$msgid}='';   
                 }  
                   
                 if (($status{$msgid} eq 'new') ||   
                     (!$status{$msgid})) {   
                     if ($what eq 'Error') {  
                         $error{$url}.=','.$msgid;   
                     } else {  
                         $feedback{$url}.=','.$msgid;  
                     }  
                 }  
             }  
         }  
           
         $self->{FEEDBACK} = \%feedback;  
         $self->{ERROR_MSG} = \%error; # what is this? JB  
         $self->{DISCUSSION_TIME} = \%discussiontime;  
         $self->{EMAIL_STATUS} = \%emailstatus;  
           
     }      }
   
     if ($self->{GET_USER_DATA}) {      $self->{COURSE_USER_OPT_GENERATED} = 1;
  # Retreive performance data on problems      
  my %student_data = Apache::lonnet::currentdump($ENV{'request.course.id'},      return;
        $ENV{'user.domain'},  }
        $ENV{'user.name'});  
  $self->{STUDENT_DATA} = \%student_data;  sub generate_email_discuss_status {
       my $self = shift;
       if ($self->{EMAIL_DISCUSS_GENERATED}) { return; }
   
       my $cid=$ENV{'request.course.id'};
       my ($cdom,$cnum)=split(/\_/,$cid);
       
       my %emailstatus = &Apache::lonnet::dump('email_status');
       my $logoutTime = $emailstatus{'logout'};
       my $courseLeaveTime = $emailstatus{'logout_'.$ENV{'request.course.id'}};
       $self->{LAST_CHECK} = (($courseLeaveTime > $logoutTime) ?
      $courseLeaveTime : $logoutTime);
       my %discussiontime = &Apache::lonnet::dump('discussiontimes', 
          $cdom, $cnum);
       my %feedback=();
       my %error=();
       my $keys = &Apache::lonnet::reply('keys:'.
         $ENV{'user.domain'}.':'.
         $ENV{'user.name'}.':nohist_email',
         $ENV{'user.home'});
       
       foreach my $msgid (split(/\&/, $keys)) {
    $msgid=&Apache::lonnet::unescape($msgid);
    my $plain=&Apache::lonnet::unescape(&Apache::lonnet::unescape($msgid));
    if ($plain=~/(Error|Feedback) \[([^\]]+)\]/) {
       my ($what,$url)=($1,$2);
       my %status=
    &Apache::lonnet::get('email_status',[$msgid]);
       if ($status{$msgid}=~/^error\:/) { 
    $status{$msgid}=''; 
       }
       
       if (($status{$msgid} eq 'new') || 
    (!$status{$msgid})) { 
    if ($what eq 'Error') {
       $error{$url}.=','.$msgid; 
    } else {
       $feedback{$url}.=','.$msgid;
    }
       }
    }
     }      }
       
       $self->{FEEDBACK} = \%feedback;
       $self->{ERROR_MSG} = \%error; # what is this? JB
       $self->{DISCUSSION_TIME} = \%discussiontime;
       $self->{EMAIL_STATUS} = \%emailstatus;
       
       $self->{EMAIL_DISCUSS_GENERATED} = 1;
   }
   
     $self->{PARM_CACHE} = {};  sub get_user_data {
     $self->{INITED} = 1;      my $self = shift;
       if ($self->{RETRIEVED_USER_DATA}) { return; }
   
       # Retrieve performance data on problems
       my %student_data = Apache::lonnet::currentdump($ENV{'request.course.id'},
      $ENV{'user.domain'},
      $ENV{'user.name'});
       $self->{STUDENT_DATA} = \%student_data;
   
       $self->{RETRIEVED_USER_DATA} = 1;
 }  }
   
 # Internal function: Takes a key to look up in the nav hash and implements internal  # Internal function: Takes a key to look up in the nav hash and implements internal
Line 1810  sub navhash { Line 1826  sub navhash {
     return $self->{NAV_HASH}->{$key};      return $self->{NAV_HASH}->{$key};
 }  }
   
   =pod
   
   =item * B<courseMapDefined>(): Returns true if the course map is defined, 
       false otherwise. Undefined course maps indicate an error somewhere in
       LON-CAPA, and you will not be able to proceed with using the navmap.
       See the B<NAV> screen for an example of using this.
   
   =cut
   
 # Checks to see if coursemap is defined, matching test in old lonnavmaps  # Checks to see if coursemap is defined, matching test in old lonnavmaps
 sub courseMapDefined {  sub courseMapDefined {
     my $self = shift;      my $self = shift;
Line 1839  sub untieHashes { Line 1864  sub untieHashes {
 sub hasDiscussion {  sub hasDiscussion {
     my $self = shift;      my $self = shift;
     my $symb = shift;      my $symb = shift;
       
       $self->generate_email_discuss_status();
   
     if (!defined($self->{DISCUSSION_TIME})) { return 0; }      if (!defined($self->{DISCUSSION_TIME})) { return 0; }
   
     #return defined($self->{DISCUSSION_TIME}->{$symb});      #return defined($self->{DISCUSSION_TIME}->{$symb});
Line 1853  sub getFeedback { Line 1881  sub getFeedback {
     my $self = shift;      my $self = shift;
     my $symb = shift;      my $symb = shift;
   
       $self->generate_email_discuss_status();
   
     if (!defined($self->{FEEDBACK})) { return ""; }      if (!defined($self->{FEEDBACK})) { return ""; }
           
     return $self->{FEEDBACK}->{$symb};      return $self->{FEEDBACK}->{$symb};
Line 1862  sub getFeedback { Line 1892  sub getFeedback {
 sub getErrors {   sub getErrors { 
     my $self = shift;      my $self = shift;
     my $src = shift;      my $src = shift;
       
       $self->generate_email_discuss_status();
   
     if (!defined($self->{ERROR_MSG})) { return ""; }      if (!defined($self->{ERROR_MSG})) { return ""; }
     return $self->{ERROR_MSG}->{$src};      return $self->{ERROR_MSG}->{$src};
 }  }
Line 1891  the given map. This is one of the proper Line 1923  the given map. This is one of the proper
 # The strategy here is to cache the resource objects, and only construct them  # The strategy here is to cache the resource objects, and only construct them
 # as we use them. The real point is to prevent reading any more from the tied  # as we use them. The real point is to prevent reading any more from the tied
 # hash then we have to, which should hopefully alleviate speed problems.  # hash then we have to, which should hopefully alleviate speed problems.
 # Caching is just an incidental detail I throw in because it makes sense.  
   
 sub getById {  sub getById {
     my $self = shift;      my $self = shift;
Line 1974  sub parmval { Line 2005  sub parmval {
   
 sub parmval_real {  sub parmval_real {
     my $self = shift;      my $self = shift;
     my ($what,$symb) = @_;      my ($what,$symb,$recurse) = @_;
   
       # Make sure the {USER_OPT} and {COURSE_OPT} hashes are populated
       $self->generate_course_user_opt();
   
     my $cid=$ENV{'request.course.id'};      my $cid=$ENV{'request.course.id'};
     my $csec=$ENV{'request.course.sec'};      my $csec=$ENV{'request.course.sec'};
Line 2046  sub parmval_real { Line 2080  sub parmval_real {
  my $id=pop(@parts);   my $id=pop(@parts);
  my $part=join('_',@parts);   my $part=join('_',@parts);
  if ($part eq '') { $part='0'; }   if ($part eq '') { $part='0'; }
  my $partgeneral=$self->parmval($part.".$qualifier",$symb);   my $partgeneral=$self->parmval($part.".$qualifier",$symb,1);
  if (defined($partgeneral)) { return $partgeneral; }   if (defined($partgeneral)) { return $partgeneral; }
     }      }
       if ($recurse) { return undef; }
       my $pack_def=&Apache::lonnet::packages_tab_default($fn,'resource.'.$what);
       if (defined($pack_def)) { return $pack_def; }
     return '';      return '';
 }  }
   
Line 2248  new branch. The possible tokens are: Line 2285  new branch. The possible tokens are:
   
 =over 4  =over 4
   
 =item * BEGIN_MAP:  =item * B<BEGIN_MAP>:
   
 A new map is being recursed into. This is returned I<after> the map  A new map is being recursed into. This is returned I<after> the map
 resource itself is returned.  resource itself is returned.
   
 =item * END_MAP:  =item * B<END_MAP>:
   
 The map is now done.  The map is now done.
   
 =item * BEGIN_BRANCH:  =item * B<BEGIN_BRANCH>:
   
 A branch is now starting. The next resource returned will be the first  A branch is now starting. The next resource returned will be the first
 in that branch.  in that branch.
   
 =item * END_BRANCH:  =item * B<END_BRANCH>:
   
 The branch is now done.  The branch is now done.
   
Line 2819  use Apache::lonnet; Line 2856  use Apache::lonnet;
   
 =pod  =pod
   
 =head1 Object: resource  =head1 Object: resource 
   
   X<resource, navmap object>
 A resource object encapsulates a resource in a resource map, allowing  A resource object encapsulates a resource in a resource map, allowing
 easy manipulation of the resource, querying the properties of the  easy manipulation of the resource, querying the properties of the
 resource (including user properties), and represents a reference that  resource (including user properties), and represents a reference that
Line 2840  writing, there is no way to override thi Line 2878  writing, there is no way to override thi
 parts will never be returned, nor will their response types or ids be  parts will never be returned, nor will their response types or ids be
 stored.  stored.
   
 =head2 Public Members  =head2 Overview
   
 resource objects have a hash called DATA ($resourceRef->{DATA}) that  
 you can store whatever you want in. This allows you to easily do  
 two-pass algorithms without worrying about managing your own  
 resource->data hash.  
   
 =head2 Methods  
   
 =over 4  
   
 =item * B<new>($navmapRef, $idString):  A B<Resource> is the most granular type of object in LON-CAPA that can
   be included in a course. It can either be a particular resource, like
 The first arg is a reference to the parent navmap object. The second  an HTML page, external resource, problem, etc., or it can be a
 is the idString of the resource itself. Very rarely, if ever, called  container sequence, such as a "page" or a "map".
 directly. Use the nav map->getByID() method.  
   To see a sequence from the user's point of view, please see the
 =back  B<Creating a Course: Maps and Sequences> chapter of the Author's
   Manual.
   
   A Resource Object, once obtained from a navmap object via a B<getBy*>
   method of the navmap, or from an iterator, allows you to query
   information about that resource.
   
   Generally, you do not ever want to create a resource object yourself,
   so creation has been left undocumented. Always retrieve resources
   from navmap objects.
   
   =head3 Identifying Resources
   
   X<big hash>Every resource is identified by a Resource ID in the big hash that is
   unique to that resource for a given course. X<resource ID, in big hash>
   The Resource ID has the form #.#, where the first number is the same
   for every resource in a map, and the second is unique. For instance,
   for a course laid out like this:
   
    * Problem 1
    * Map
      * Resource 2
      * Resource 3
   
   C<Problem 1> and C<Map> will share a first number, and C<Resource 2>
   C<Resource 3> will share a first number. The second number may end up
   re-used between the two groups.
   
   The resource ID is only used in the big hash, but can be used in the
   context of a course to identify a resource easily. (For instance, the
   printing system uses it to record which resources from a sequence you 
   wish to print.)
   
   X<symb> X<resource, symb>
   All resources also have B<symb>s, which uniquely identify a resource
   in a course. Many internal LON-CAPA functions expect a symb. A symb
   carries along with it the URL of the resource, and the map it appears
   in. Symbs are much larger then resource IDs.
   
 =cut  =cut
   
Line 2896  sub navHash { Line 2962  sub navHash {
   
 =pod  =pod
   
 B<Metadata Retreival>  =head2 Methods
   
   Once you have a resource object, here's what you can do with it:
   
   =head3 Attribute Retrieval
   
 These are methods that help you retrieve metadata about the resource:  Every resource has certain attributes that can be retrieved and used:
 Method names are based on the fields in the compiled course  
 representation.  
   
 =over 4  =over 4
   
   =item * B<ID>: Every resource has an ID that is unique for that
       resource in the course it is in. The ID is actually in the hash
       representing the resource, so for a resource object $res, obtain
       it via C<$res->{ID}).
   
 =item * B<compTitle>:  =item * B<compTitle>:
   
 Returns a "composite title", that is equal to $res->title() if the  Returns a "composite title", that is equal to $res->title() if the
Line 2914  resource has a title, and is otherwise t Line 2987  resource has a title, and is otherwise t
   
 Returns true if the resource is external.  Returns true if the resource is external.
   
 =item * B<goesto>:  
   
 Returns the "goesto" value from the compiled nav map. (It is likely  
 you want to use B<getNext> instead.)  
   
 =item * B<kind>:  =item * B<kind>:
   
 Returns the kind of the resource from the compiled nav map.  Returns the kind of the resource from the compiled nav map.
Line 2946  Returns the symb for the resource. Line 3014  Returns the symb for the resource.
   
 Returns the title of the resource.  Returns the title of the resource.
   
 =item * B<to>:  
   
 Returns the "to" value from the compiled nav map. (It is likely you  
 want to use B<getNext> instead.)  
   
 =back  =back
   
 =cut  =cut
Line 2960  want to use B<getNext> instead.) Line 3023  want to use B<getNext> instead.)
 sub comesfrom { my $self=shift; return $self->navHash("comesfrom_", 1); }  sub comesfrom { my $self=shift; return $self->navHash("comesfrom_", 1); }
 sub ext { my $self=shift; return $self->navHash("ext_", 1) eq 'true:'; }  sub ext { my $self=shift; return $self->navHash("ext_", 1) eq 'true:'; }
 sub from { my $self=shift; return $self->navHash("from_", 1); }  sub from { my $self=shift; return $self->navHash("from_", 1); }
   # considered private and undocumented
 sub goesto { my $self=shift; return $self->navHash("goesto_", 1); }  sub goesto { my $self=shift; return $self->navHash("goesto_", 1); }
 sub kind { my $self=shift; return $self->navHash("kind_", 1); }  sub kind { my $self=shift; return $self->navHash("kind_", 1); }
 sub randomout { my $self=shift; return $self->navHash("randomout_", 1); }  sub randomout { my $self=shift; return $self->navHash("randomout_", 1); }
Line 2988  sub title { Line 3052  sub title {
  return $ENV{'course.'.$ENV{'request.course.id'}.'.description'};   return $ENV{'course.'.$ENV{'request.course.id'}.'.description'};
     }      }
     return $self->navHash("title_", 1); }      return $self->navHash("title_", 1); }
   # considered private and undocumented
 sub to { my $self=shift; return $self->navHash("to_", 1); }  sub to { my $self=shift; return $self->navHash("to_", 1); }
 sub compTitle {  sub compTitle {
     my $self = shift;      my $self = shift;
Line 3223  sub answerdate { Line 3288  sub answerdate {
 }  }
 sub awarded {   sub awarded { 
     my $self = shift; my $part = shift;      my $self = shift; my $part = shift;
       $self->{NAV_MAP}->get_user_data();
     if (!defined($part)) { $part = '0'; }      if (!defined($part)) { $part = '0'; }
     return $self->{NAV_MAP}->{STUDENT_DATA}->{$self->symb()}->{'resource.'.$part.'.awarded'};      return $self->{NAV_MAP}->{STUDENT_DATA}->{$self->symb()}->{'resource.'.$part.'.awarded'};
 }  }
Removed from v.1.216  
changed lines
  Added in v.1.221

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