[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.217

version 1.216, 2003/07/17 18:40:49 version 1.217, 2003/07/21 20:25:42
Line 552  sub timeToHumanString { Line 552  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 563  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 717  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 1605  package Apache::lonnavmaps::navmap; Line 1604  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
   
 =head2 Creation  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
   
   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>(navHashFile, parmHashFile, 
   genMailDiscussStatus, getUserData):    genCourseAndUserOptions, genMailDiscussStatus, getUserData):
   
 Binds a new navmap object to the compiled nav map hash and parm hash  Binds a new navmap object to the compiled nav map hash and parm hash
 given as filenames. genCourseAndUserOptions is a flag saying whether  given as filenames. genCourseAndUserOptions is a flag saying whether
Line 1628  retreive the user's performance data for Line 1663  retreive the user's performance data for
   
 =back  =back
   
   Once you have the $navmap object, call ->init() on it when you are ready
   to use it. This allows you to check if the course map is defined (see
   B<courseMapDefined> below) before engaging in potentially expensive 
   initialization routines for the genCourseAndUserOptions and 
   genMailDiscussStatus option.
   
   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 1810  sub navhash { Line 1855  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 1891  the given map. This is one of the proper Line 1945  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 2248  new branch. The possible tokens are: Line 2301  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 2872  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 2894  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  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
 =over 4  an HTML page, external resource, problem, etc., or it can be a
   container sequence, such as a "page" or a "map".
 =item * B<new>($navmapRef, $idString):  
   To see a sequence from the user's point of view, please see the
 The first arg is a reference to the parent navmap object. The second  B<Creating a Course: Maps and Sequences> chapter of the Author's
 is the idString of the resource itself. Very rarely, if ever, called  Manual.
 directly. Use the nav map->getByID() method.  
   A Resource Object, once obtained from a navmap object via a B<getBy*>
 =back  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 2978  sub navHash {
   
 =pod  =pod
   
 B<Metadata Retreival>  =head2 Methods
   
 These are methods that help you retrieve metadata about the resource:  Once you have a resource object, here's what you can do with it:
 Method names are based on the fields in the compiled course  
 representation.  =head3 Attribute Retrieval
   
   Every resource has certain attributes that can be retrieved and used:
   
 =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 3003  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 3030  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 3039  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 3068  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;
Removed from v.1.216  
changed lines
  Added in v.1.217

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