File Coverage

=head1 NAME

C4::ShelfBrowser - functions that deal with the shelf browser feature found in
the OPAC.

=head1 SYNOPSIS

  use C4::ShelfBrowser;

=head1 DESCRIPTION

This module provides functions to get items nearby to another item, for use
in the shelf browser function.

'Nearby' is controlled by a handful of system preferences that specify what
to take into account.

=head1 FUNCTIONS

=head2 GetNearbyItems($itemnumber, [$num_each_side])

  $nearby = GetNearbyItems($itemnumber, [$num_each_side]);

  @next = @{ $nearby->{next} };
  @prev = @{ $nearby->{prev} };

  foreach (@next) {
      # These won't format well like this, but here are the fields
  	  print $_->{title};
  	  print $_->{biblionumber};
  	  print $_->{itemnumber};
  	  print $_->{browser_normalized_upc};
  	  print $_->{browser_normalized_oclc};
  	  print $_->{browser_normalized_isbn};
  }

  # This is the information required to scroll the browser to the next left
  # or right set. Can be derived from next/prev, but it's here for convenience.
  print $nearby->{prev_itemnumber};
  print $nearby->{next_itemnumber};
  print $nearby->{prev_biblionumber};
  print $nearby->{next_biblionumber};

  # These will be undef if the values are not used to calculate the 
  # nearby items.
  print $nearby->{starting_homebranch}->{code};
  print $nearby->{starting_homebranch}->{description};
  print $nearby->{starting_location}->{code};
  print $nearby->{starting_location}->{description};
  print $nearby->{starting_ccode}->{code};
  print $nearby->{starting_ccode}->{description};

  print $nearby->{starting_itemnumber};
  
This finds the items that are nearby to the supplied item, and supplies
those previous and next, along with the other useful information for displaying
the shelf browser.

It automatically applies the following user preferences to work out how to
calculate things: C<ShelfBrowserUsesLocation>, C<ShelfBrowserUsesHomeBranch>, 
C<ShelfBrowserUsesCcode>.

The option C<$num_each_side> value determines how many items will be fetched
each side of the supplied item. Note that the item itself is the first entry
in the 'next' set, and counts towards this limit (this is to keep the
behaviour consistant with the code that this is a refactor of.) Default is
3.

This will throw an exception if something went wrong.

=cut