[Koha-cvs] CVS: koha/C4 Database.pm,1.6,1.7 Koha.pm,1.6,1.7 Output.pm,1.16,1.17 Search.pm,1.36,1.37

[Pat Eyler]

Update of /cvsroot/koha/koha/C4
In directory usw-pr-cvs1:/tmp/cvs-serv20261

Modified Files:
        Database.pm Koha.pm Output.pm Search.pm 
Log Message:
adding POD from Andres Arensburger

Index: Database.pm
===================================================================
RCS file: /cvsroot/koha/koha/C4/Database.pm,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -r1.6 -r1.7
*** Database.pm 14 Aug 2002 18:12:51 -0000      1.6
--- Database.pm 20 Sep 2002 12:49:47 -0000      1.7
***************
*** 1,3 ****
! package C4::Database; #asummes C4/Database
  
  #requires DBI.pm to be installed
--- 1,3 ----
! package C4::Database; #assumes C4/Database
  
  #requires DBI.pm to be installed
***************
*** 61,64 ****
--- 61,76 ----
  } # sub C4Connect
  
+ =item requireDBI
+ 
+   &requireDBI($dbh, $functionnname);
+ 
+ Verifies that C<$dbh> is a valid DBI::db database handle (presumably
+ to the Koha database). If it isn't, the function dies.
+ 
+ C<$functionname> is the name of the calling function, which will be
+ used in error messages.
+ 
+ =cut
+ #'
  #------------------
  # Helper subroutine to make sure database handle was passed properly
***************
*** 67,70 ****
--- 79,86 ----
        $dbh,
        $subrname,      # name of calling subroutine
+                       # FIXME - Ought to get this with 'caller',
+                       # instead of requiring developers to always
+                       # get it right. Plus, it'd give the line
+                       # number.
      )address@hidden;
  
***************
*** 78,79 ****
--- 94,105 ----
  
  END { }
+ 
+ 1;
+ __END__
+ =back
+ 
+ =head1 SEE ALSO
+ 
+ L<DBI(3)|DBI>
+ 
+ =cut

Index: Koha.pm
===================================================================
RCS file: /cvsroot/koha/koha/C4/Koha.pm,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -r1.6 -r1.7
*** Koha.pm     14 Aug 2002 18:12:51 -0000      1.6
--- Koha.pm     20 Sep 2002 12:49:47 -0000      1.7
***************
*** 27,30 ****
--- 27,54 ----
  $VERSION = 0.01;
      
+ =head1 NAME
+ 
+ C4::Koha - Perl Module containing convenience functions for Koha scripts
+ 
+ =head1 SYNOPSIS
+ 
+   use C4::Koha;
+ 
+ 
+   $date = slashifyDate("01-01-2002")
+   $ethnicity = fixEthnicity('asian');
+   ($categories, $labels) = borrowercategories();
+   ($categories, $labels) = ethnicitycategories();
+ 
+ =head1 DESCRIPTION
+ 
+ Koha.pm provides many functions for Koha scripts.
+ 
+ =head1 FUNCTIONS
+ 
+ =over 2
+ 
+ =cut
+ 
  @ISA = qw(Exporter);
  @EXPORT = qw(&slashifyDate
***************
*** 38,41 ****
--- 62,74 ----
  my $DEBUG = 0;
  
+ =item slashifyDate
+ 
+   $slash_date = &slashifyDate($dash_date);
+ 
+ Takes a string of the form "DD-MM-YYYY" (or anything separated by
+ dashes), converts it to the form "YYYY/MM/DD", and returns the result.
+ 
+ =cut
+ 
  sub slashifyDate {
      # accepts a date of the form xx-xx-xx[xx] and returns it in the 
***************
*** 45,48 ****
--- 78,92 ----
  }
  
+ =item fixEthnicity
+ 
+   $ethn_name = &fixEthnicity($ethn_code);
+ 
+ Takes an ethnicity code (e.g., "european" or "pi") and returns the
+ corresponding descriptive name from the C<ethnicity> table in the
+ Koha database ("European" or "Pacific Islander").
+ 
+ =cut
+ #'
+ 
  sub fixEthnicity($) { 
  
***************
*** 57,60 ****
--- 101,116 ----
  }
  
+ =item borrowercategories
+ 
+   ($codes_arrayref, $labels_hashref) = &borrowercategories();
+ 
+ Looks up the different types of borrowers in the database. Returns two
+ elements: a reference-to-array, which lists the borrower category
+ codes, and a reference-to-hash, which maps the borrower category codes
+ to category descriptions.
+ 
+ =cut
+ #'
+ 
  sub borrowercategories {
      my $dbh=C4Connect;
***************
*** 72,75 ****
--- 128,143 ----
  }
  
+ =item ethnicitycategories
+ 
+   ($codes_arrayref, $labels_hashref) = &ethnicitycategories();
+ 
+ Looks up the different ethnic types in the database. Returns two
+ elements: a reference-to-array, which lists the ethnicity codes, and a
+ reference-to-hash, which maps the ethnicity codes to ethnicity
+ descriptions.
+ 
+ =cut
+ #'
+ 
  sub ethnicitycategories {
      my $dbh=C4Connect;
***************
*** 90,112 ****
  __END__
  
! =head1 NAME
! 
! Koha - Perl Module containing convenience functions for Koha scripts
! 
! =head1 SYNOPSIS
! 
!   use Koha;
! 
! 
!   $date = slashifyDate("01-01-2002")
!   $ethnicity=fixEthnicity('asian');
!   ($categories,$labels)=borrowercategories();
! 
! =head1 DESCRIPTION
! 
! Koha.pm provides many functions for Koha scripts.
! 
! slashifyDate() takes a dash separated date string and returns a slash 
! separated date string
  
  =head1 AUTHOR
--- 158,162 ----
  __END__
  
! =back
  
  =head1 AUTHOR
***************
*** 119,125 ****
  
  =cut
- 
- 
- 
- 
- 
--- 169,170 ----

Index: Output.pm
===================================================================
RCS file: /cvsroot/koha/koha/C4/Output.pm,v
retrieving revision 1.16
retrieving revision 1.17
diff -C2 -r1.16 -r1.17
*** Output.pm   17 Sep 2002 12:42:52 -0000      1.16
--- Output.pm   20 Sep 2002 12:49:47 -0000      1.17
***************
*** 34,37 ****
--- 34,59 ----
  $VERSION = 0.01;
  
+ =head1 NAME
+ 
+ C4::Output - Functions for generating HTML for the Koha web interface
+ 
+ =head1 SYNOPSIS
+ 
+   use C4::Output;
+ 
+   $str = &mklink("http://www.koha.org/";, "Koha web page");
+   print $str;
+ 
+ =head1 DESCRIPTION
+ 
+ The functions in this module generate HTML, and return the result as a
+ printable string.
+ 
+ =head1 FUNCTIONS
+ 
+ =over 2
+ 
+ =cut
+ 
  @ISA = qw(Exporter);
  @EXPORT = qw(&startpage &endpage 
***************
*** 49,60 ****
  # as well as any optionally exported functions
  
! @EXPORT_OK   = qw($Var1 %Hashit);
  
  
  # non-exported package globals go here
! use vars qw(@more $stuff);
  
  # initalize package globals, first exported ones
  
  my $Var1   = '';
  my %Hashit = ();
--- 71,83 ----
  # as well as any optionally exported functions
  
! @EXPORT_OK   = qw($Var1 %Hashit);     # FIXME - These are never used
  
  
  # non-exported package globals go here
! use vars qw(@more $stuff);            # FIXME - These are never used
  
  # initalize package globals, first exported ones
  
+ # FIXME - These are never used
  my $Var1   = '';
  my %Hashit = ();
***************
*** 62,65 ****
--- 85,89 ----
  
  # then the others (which are still accessible as $Some::Module::stuff)
+ # FIXME - These are never used
  my $stuff  = '';
  my @more   = ();
***************
*** 71,74 ****
--- 95,101 ----
  # Change this value to reflect where you will store your includes
  #
+ # FIXME - Since this is used in several places, it ought to be put
+ # into a separate file. Better yet, put "use C4::Config;" inside the
+ # &import method of any package that requires the config file.
  my %configfile;
  open (KC, "/etc/koha.conf");
***************
*** 94,101 ****
--- 121,149 ----
  # make all your functions, whether exported or not;
  
+ =item picktemplate
+ 
+   $template = &picktemplate($includes, $base);
+ 
+ Returns the preferred template for a given page. C<$base> is the
+ basename of the script that will generate the page (with the C<.pl>
+ extension stripped off), and C<$includes> is the directory in which
+ HTML include files are located.
+ 
+ The preferred template is given by the C<template> entry in the
+ C<systempreferences> table in the Koha database. If
+ C<$includes>F</templates/preferred-template/>C<$base.tmpl> exists,
+ C<&picktemplate> returns the preferred template; otherwise, it returns
+ the string C<default>.
+ 
+ =cut
+ #'
  sub picktemplate {
    my ($includes, $base) = @_;
    my $dbh=C4Connect;
    my $templates;
+   # FIXME - Instead of generating the list of possible templates, and
+   # then querying the database to see if, by chance, one of them has
+   # been selected, wouldn't it be better to query the database first,
+   # and then see whether the selected template file exists?
    opendir (D, "$includes/templates");
    my @dirlist=readdir D;
***************
*** 237,244 ****
--- 285,307 ----
  }
  
+ =item endmenu
+ 
+   @lines = &endmenu($type);
+   print join("", @lines);
+ 
+ Given a page type, or category, returns a set of lines of HTML which,
+ when concatenated, generate the menu at the bottom of the web page.
+ 
+ C<$type> may be one of C<issue>, C<opac>, C<member>, C<acquisitions>,
+ C<report>, C<circulation>, or something else, in which case the menu
+ will be for the catalog pages.
  
+ =cut
+ #'
  sub endmenu {
    my ($type) = @_;
    if ( ! defined $type ) { $type=''; }
+   # FIXME - It's bad form to die in a CGI script. It's even worse form
+   # to die without issuing an error message.
    if ($type eq 'issue') {
      open (FILE,"$path/issues-bottom.inc") || die;
***************
*** 365,372 ****
          $text="<input type=radio name=$keys[$i2] value=$data[1]>$data[1]
        <input type=radio name=$keys[$i2] value=$data[2]>$data[2]";
!       } 
        if ($data[0] eq 'text') {
          $text="<input type=$data[0] name=$keys[$i2] value=\"$data[1]\" 
size=40>";
        }
        if ($data[0] eq 'textarea') {
          $text="<textarea name=$keys[$i2] cols=40 rows=4>$data[1]</textarea>";
--- 428,437 ----
          $text="<input type=radio name=$keys[$i2] value=$data[1]>$data[1]
        <input type=radio name=$keys[$i2] value=$data[2]>$data[2]";
!       }
!       # FIXME - Is 40 the right size in all cases?
        if ($data[0] eq 'text') {
          $text="<input type=$data[0] name=$keys[$i2] value=\"$data[1]\" 
size=40>";
        }
+       # FIXME - Is 40x4 the right size in all cases?
        if ($data[0] eq 'textarea') {
          $text="<textarea name=$keys[$i2] cols=40 rows=4>$data[1]</textarea>";
***************
*** 378,382 ****
          my $val = $data[$i+1];
                  $text = $text."<option value=$data[$i]>$val";
!         $i = $i+2;
        }
        $text=$text."</select>";
--- 443,447 ----
          my $val = $data[$i+1];
                  $text = $text."<option value=$data[$i]>$val";
!         $i = $i+2;            # FIXME - Use $i += 2.
        }
        $text=$text."</select>";
***************
*** 388,397 ****
--- 453,465 ----
    }
    my $temp=join("\n",@order);
+   # FIXME - Use ".=". That's what it's for.
    $string=$string.$temp;
    $string=$string.mktablerow(1,'white','<input type=submit>');
    $string=$string.mktableft;
    $string=$string."</form>";
+   # FIXME - A return statement, while not strictly necessary, would be nice.
  }
  
+ # XXX - POD
  sub mkformnotable{
    my ($action,@inputs)address@hidden;
***************
*** 421,424 ****
--- 489,565 ----
  }
  
+ =item mkform2
+ 
+   $str = &mkform2($action,
+       $fieldname => 
"$fieldpos\t$required\t$label\t$fieldtype\t$value0\t$value1\t...",
+       ...
+       );
+   print $str;
+ 
+ Takes a set of arguments that define an input form, generates an HTML
+ string for the form, and returns the string.
+ 
+ C<$action> is the action for the form, usually the URL of the script
+ that will process it.
+ 
+ The remaining arguments define the fields in the form. C<$fieldname>
+ is the field's name. This is for the script's benefit, and will not be
+ shown to the user.
+ 
+ C<$fieldpos> is an integer; fields will be output in order of
+ increasing C<$fieldpos>. This number must be unique: if two fields
+ have the same C<$fieldpos>, one will be picked at random, and the
+ other will be ignored. See below for special considerations, however.
+ 
+ If C<$required> is the string C<R>, then the field is required, and
+ the label will have C< (Req.)> appended.
+ 
+ C<$label> is a string that will appear next to the input field.
+ 
+ C<$fieldtype> specifies the type of the input field. It may be one of
+ the following:
+ 
+ =over 4
+ 
+ =item C<hidden>
+ 
+ Generates a hidden field, used to pass data to the script without
+ showing it to the user. C<$value0> is its value.
+ 
+ =item C<radio>
+ 
+ Generates a pair of radio buttons, with values C<$value0> and
+ C<$value1>. In both cases, C<$value0> and C<$value1> will be shown to
+ the user, next to the radio button.
+ 
+ =item C<text>
+ 
+ Generates a one-line text input field. Its size may be specified by
+ C<$value0>. The default is 40. The initial text of the field may be
+ specified by C<$value1>.
+ 
+ =item C<textarea>
+ 
+ Generates a text input area. C<$value0> may be a string of the form
+ "WWWxHHH", in which case the text input area will be WWW columns wide
+ and HHH rows tall. The size defaults to 40x4.
+ 
+ The initial text (which, of course, may not contain any tabs) may be
+ specified by C<$value1>.
+ 
+ =item C<select>
+ 
+ Generates a list of items, from which the user may choose one. Here,
+ C<$value1>, C<$value2>, etc. are a list of key-value pairs. In each
+ pair, the key specifies an internal label for a choice, and the value
+ specifies the description of the choice that will be shown the user.
+ 
+ If C<$value0> is the same as one of the keys that follows, then the
+ corresponding choice will initially be selected.
+ 
+ =back
+ 
+ =cut
+ #'
  sub mkform2{
      # FIXME
***************
*** 640,644 ****
  
  END { }       # module clean-up code here (global destructor)
-     
  
  
--- 781,792 ----
  
  END { }       # module clean-up code here (global destructor)
  
+ 1;
+ __END__
+ =back
+ 
+ =head1 SEE ALSO
+ 
+ L<DBI(3)|DBI>
  
+ =cut

Index: Search.pm
===================================================================
RCS file: /cvsroot/koha/koha/C4/Search.pm,v
retrieving revision 1.36
retrieving revision 1.37
diff -C2 -r1.36 -r1.37
*** Search.pm   19 Sep 2002 00:24:27 -0000      1.36
--- Search.pm   20 Sep 2002 12:49:47 -0000      1.37
***************
*** 31,34 ****
--- 31,58 ----
  $VERSION = 0.02;
      
+ =head1 NAME
+ 
+ C4::Search - Functions for searching the Koha catalog and other databases
+ 
+ =head1 SYNOPSIS
+ 
+   use C4::Search;
[...1300 lines suppressed...]
! Here I should go through and document each function thats exported and what 
it does. But I havent yet.
! 
! my ($count,@results)=catalogsearch($env,$type,$search,$num,$offset);
! This is a front end to all the other searches, depending on what is passed
! to it, it calls the appropriate search
! 
! =head2 EXPORT
  
! catalogsearch
  
  =head1 AUTHOR
--- 2398,2405 ----
  END { }       # module clean-up code here (global destructor)
  
! 1;
! __END__
  
! =back
  
  =head1 AUTHOR