NAME

Apache::lonnavmap - Subroutines to handle and render the navigation maps


SYNOPSIS

The main handler generates the navigational listing for the course, the other objects export this information in a usable fashion for other modules


Object: 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, 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.

The package provides a function called 'render', called as Apache::lonnavmaps::renderer->render({}).

Overview of Columns

The renderer will build an HTML table for the navmap and return it. The table is 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 preparent 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 <input> 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.

The pre-packaged column names are refered to by constants in the Apache::lonnavmaps::renderer namespace. The following currently exist:

If you add any others please be sure to document them here.

An example of a column renderer that will show the ID number of a resource, along with the part name if any:

 sub { 
  my ($resource, $part, $params) = @_;   
  if ($part) { return '<td>' . $resource->{ID} . ' ' . $part . '</td>'; }
  return '<td>' . $resource->{ID} . '</td>';
 }

Note these functions are responsible for the TD tags, which allow them to override vertical and horizontal alignment, etc.

Parameters

Most of these parameters are only useful if you are *not* using the 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 shown), 'url' (necessary for the folders to link to the current screen correctly), and possibly 'queryString' if your app calls for it. In that case, maintaining the state of the folders will be done automatically.

Additional Info

In addition to the parameters you can pass to the renderer, which will be passed through unchange to the column renderers, the renderer will generate the following information which your renderer may find 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.

lonnavmaps provides functions and objects for dealing with the 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.


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.

Methods


Object: navmap Iterator

An iterator encapsulates the logic required to traverse a data structure. navmap uses an iterator to traverse the course map according to the criteria you wish to use.

To obtain an iterator, call the getIterator() function of a navmap object. (Do not instantiate Apache::lonnavmaps::iterator directly.) This will return a reference to the iterator:

my $resourceIterator = $navmap->getIterator();

To get the next thing from the iterator, call next:

my $nextThing = $resourceIterator->next()

getIterator behaves as follows:

The other method available on the iterator is getStack, which returns an array populated with the current 'stack' of maps, as references to the resource objects. Example: This is useful when making the navigation map, as we need to check whether we are under a page map to see if we need to link directly to the resource, or to the page. The first elements in the array will correspond to the top of the stack (most inclusive map).


Object: resource

A resource object encapsulates a resource in a resource map, allowing easy manipulation of the resource, querying the properties of the resource (including user properties), and represents a reference that can be used as the canonical representation of the resource by lonnavmap clients like renderers.

A resource only makes sense in the context of a navmap, as some of the data is stored in the navmap object.

You will probably never need to instantiate this object directly. Use Apache::lonnavmaps::navmap, and use the ``start'' method to obtain the starting resource.

Resource objects respect the parameter_hiddenparts, which suppresses various parts according to the wishes of the map author. As of this writing, there is no way to override this parameter, and suppressed parts will never be returned, nor will their response types or ids be stored.

Public Members

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.

Methods

Metadata Retreival

These are methods that help you retrieve metadata about the resource: Method names are based on the fields in the compiled course representation.

Map Methods

These methods are useful for getting information about the map properties of the resource, if the resource is a map (is_map).

Resource Parameters

In order to use the resource parameters correctly, the nav map must have been instantiated with genCourseAndUserOptions set to true, so the courseopt and useropt is read correctly. Then, you can call these functions to get the relevant parameters for the resource. Each function defaults to part ``0'', but can be directed to another part by passing the part as the parameter.

These methods are responsible for getting the parameter correct, not merely reflecting the contents of the GDBM hashes. As we move towards dates relative to other dates, these methods should be updated to reflect that. (Then, anybody using these methods will not have to update their code.)

Resource misc

Misc. functions for the resource.

Resource Status

Problem resources have status information, reflecting their various dates and completion statuses.

There are two aspects to the status: the date-related information and the completion information.

Idiomatic usage of these two methods would probably look something like

 foreach ($resource->parts()) {
    my $dateStatus = $resource->getDateStatus($_);
    my $completionStatus = $resource->getCompletionStatus($_);
    or
    my $status = $resource->status($_);
    ... use it here ...
 }

Which you use depends on exactly what you are looking for. The status() function has been optimized for the nav maps display and may not precisely match what you need elsewhere.

The symbolic constants shown below can be accessed through the resource object: $res-OPEN>.

Date Codes

Completion Codes

Composite Status

Along with directly returning the date or completion status, the resource object includes a convenience function status() that will combine the two status tidbits into one composite status that can represent the status of the resource as a whole. This method represents the concept of the thing we want to display to the user on the nav maps screen, which is a combination of completion and open status. The precise logic is documented in the comments of the status method. The following results may be returned, all available as methods on the resource object ($res->NETWORK_FAILURE): In addition to the return values that match the date or completion status, this function can return ``ANSWER_SUBMITTED'' if that problemstatus parameter value is set to No, suppressing the incorrect/correct feedback.

Completable

The completable method represents the concept of whether the student can currently do the problem. If the student can do the problem, which means that it is open, there are tries left, and if the problem is manually graded or the grade is suppressed via problemstatus, the student has not tried it yet, then the method returns 1. Otherwise, it returns 0, to indicate that either the student has tried it and there is no feedback, or that for some reason it is no longer completable (not open yet, successfully completed, out of tries, etc.). As an example, this is used as the filter for the ``Uncompleted Homework'' option for the nav maps.

If this does not quite meet your needs, do not fiddle with it (unless you are fixing it to better match the student's conception of ``completable'' because it's broken somehow)... make a new method.

Resource/Nav Map Navigation