NAME

Liz::MiniSum - Allow for a minimal ``Systeem voor Uren Management''


SYNOPSIS

 use Liz::MiniSum;

 $file = new Liz::MiniSum;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::MiniSum;


DESCRIPTION

The Liz::MiniSum package allows for very simple storage of sets of records related to hours worked by people for projects.


Incorporate into Client Module

The Liz::MiniSum module itself works best when incorporated into a client module because it moves the responsibility of aquiring a connection to a database to the client module and it allows any customisation to take place transparently to the developer.

Take for example the MiniSum method of HN.pm module:

 sub MiniSum {

 # Obtain the parameters
 # Start the file using the $hn handle as the database handle
 # Return the finished object

 my( $hn,$token ) = @_;
 my( $minisum ) = Liz::MiniSum->new( $token,$hn );
 $minisum;
 }

Because of the above code in HN.pm, it is now possible to write the following code:

 $hn = new HN;
 $minisum = $hn->MiniSum( 'technology' );

Note that the database connection of the file is hidden in the creation of the $hn object.


CLASS METHODS

The following methods can be called without an object specification, but as a class method such as Liz::MiniSum->method().


minisums

Return list of file identification names of all minisums in the database specified. Usually not called by itself, but rather incorporated inside a Client Module.

Input Parameters

 1 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
 2 wildcard specification to match
   (default: all)
Output Parameters

 1 reference to list of identification names in the current database
 2 reference to hash with full names
Example

 $hn = new HN;
 ($id,$name) = $hn->MiniSums;
 $minisums = @{$id};
 print "All $minisums minisums in Hospitality Net:\n";
 foreach( @{$id} ) {
   print " MiniSum '$$name{$_}' ($_)\n";
 }

In HN.pm:

 sub MiniSums { Liz::MiniSum->minisums( @_ ) }


new

Create a new Liz::MiniSum object. Creates connection or re-establishes connection with the MySQL database. Usually not called by itself, but rather incorporated inside a Client Module.

Input Parameters

 1 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
 2 identification name of the minisum
   (default: default file set for database)
Output Parameters

 1 instantiated object
 2 flag whether MiniSum was just created
Example

 $hn = new HN;
 $minisum = $hn->MiniSum( 'technology' );

In HN.pm:

 sub MiniSum { Liz::MiniSum->new( @_ ) }


reset

Delete all tables of the MiniSum object. Please use this with caution, as it will destroy any information that is stored for this MiniSum. If called in a void context, no tables exist for this MiniSum anymore, and any references in the NextID table are also removed. Otherwise, the tables will be re-created automatically and a new object will be returned, just as if the new method was called.

Output Parameters

 1 newly created MiniSum object, current object will not work anymore
Example

 $minisum->reset;
Example

 $minisum = $minisum->reset;


CONTENT METHODS

The following methods allow changes to information that is associated with an entire minisum.


Name

Specify or return the current name of the minisum object. The name can be anything to further identify the goal of the minisum.

Input Parameters

 1 new name of minisum
   (default: no change)
Output Parameters

 1 current/old name of minisum
Example

 $xxlink = new xxLINK;
 $minisum = $xxlink->MiniSum( 'eurest' );
 $minisum->Name( 'Eurestjes' );


UpdateFieldInIDs

Update a field to the same value in a number of records, specified by a list of ID's.

Input Parameters

 1    field to set values of
 2    new value to set
      (default: empty)
 3..N ID's of records in which to change the field
Example

 $minisum->UpdateFieldInIDs( 'contact','baas',@ID );


RECORD METHODS

The following methods allow changes to a single record in a MiniSum.


delete

Delete a specific Liz::MiniSum::Record object from the database.

Input Parameters

 1..N identifiers of the Liz::MiniSum::Record to be deleted
Output Parameters

 1    flag: whether action was successful
Example

 $record->delete;


Record

Create a new Liz::MiniSum::Record object, either from existing information or for a new entry. For more documentation, see the Liz::MiniSum::Record object itself.

Input Parameters

 1 ID to create Record object with
   (default: none = new record)
Output Parameters

 1 instantiated Record object
Example

 $hn = new HN;
 $minisum = $hn->MiniSum( 'technology' );

 $record = $minisum->Record;
 $record = $minisum->Record( $ID );


LIST METHODS

The following methods return SQL result handles or lists of information with regards to the Records in the MiniSum.


List

Return an SQL statement handle for a generic list of records.

The following fields may be specified with the first input parameter:

 ID
 The ID of the record

 created
 Timestamp value when this record was created

 updated
 Timestamp when the record was last updated

 status
 Status of the record

 doneon
 Timestamp when the record is to be expired

 doneby
 The name of the person performing the work

 client
 The name of the client for whom the work was done

 contact
 The name of the contact person

 project
 The name of the project

 subproject
 The name of the subproject

 minutes
 How many minutes that were spent on the work

 invoice
 Invoice information of this record

 done
 Description of what was done
Input Parameters

 1 fields to return (comma delimited)
   (default: 'ID,status,doneon,doneby,client,contact,project,subproject,minutes,invoice,done,updated,created' );
 2 fieldname on which to order the result
   (default: 'doneon DESC,updated DESC')
 3 extra condition to be applied
   (default: none)
Output Parameters

 1 SQL statement handle (on which method "fetchrow" can be applied)


ListByDoneBy

Return an SQL statement handle for a list of records for a DoneBy.

Input Parameters

 1 DoneBy for which to return the list
   (default: $ENV{'REMOTE_USER'})
 2 fields to be returned (see 1st parameter of L<List>)
   (default: 'ID,status,doneon,client,contact,project,subproject,minutes,invoice,done,updated,created';
 3 fieldname on which to order the result
   (default: 'created DESC')
 4 extra condition to be applied
   (default: status<>255)
 5 which records to return (LIMIT specification)
   (default: first 20)
Output Parameters

 1 SQL statement handle (on which method "fetchrow" can be applied)


Clients

Return a list of the clients that are currently known.

Input Parameters

 1    additional condition to be used
      (default: none)
Output Parameters

 1..N Clients available
Example

 foreach ($minisum->Clients) {
  print "$_\n";
 }


Contacts

Return a list of the contacts that are currently known for a client.

Input Parameters

 1    client for which to return the contacts
      (default: all)
 2    additional condition to be used
      (default: none)
Output Parameters

 1..N Contacts available
Example

 foreach ($minisum->Contacts) {
  print "$_\n";
 }


DoneBys

Return a list of the donebys that are currently known.

Input Parameters

 1    additional condition to be used
      (default: none)
Output Parameters

 1..N DoneBys available
Example

 foreach ($minisum->DoneBys) {
  print "$_\n";
 }


Projects

Return a list of the projects that are currently known for a client.

Input Parameters

 1    client for which to return the projects
      (default: all)
 2    additional condition to be used
      (default: none)
Output Parameters

 1..N Projects available
Example

 foreach ($minisum->Projects) {
  print "$_\n";
 }


ProjectsSubprojects

Return a list and a hash that contain all the different combinations of Project and SubProject for a Client.

Input Parameters

 1 client for which to obtain projects/subprojects
 2 extra SQL condition to be applied
   (default: none)
Output Parameters

 1 reference to list with project names
 2 reference to hash (keyed to project name)  with references to lists of subproject names
Example

 ($projects,$subprojects) = $minisum->ProjectsSubprojects;
 foreach $project (@{$projects}) {
  print "$project:\n";
  foreach (@{$subproject->{$project}}) {
   print "  $_\n";
  }
 }


SubProjects

Return a list of the subprojects that are currently known.

Input Parameters

 1    client name for which to obtain subprojects
      (default: all clients)
 2    additional condition to be used
      (default: none)
Output Parameters

 1..N SubProjects available
Example

 foreach ($minisum->SubProjects) {
  print "$_\n";
 }


SUM METHODS

The following methods are related to the summation of data.


DateDoneBy2Minutes

Return the number of minutes that one or more persons have worked. Defaults to the number of minutes for today for the current user.

Input Parameters

 1 date for which to obtain the number of minutes, in format YYYMMDD
   (default: today)
 2 doneby for which to obtain the number of minutes
   (default: $ENV{'REMOTE_USER'}
Output Parameters

 1 number of minutes
Example

 $minutes = $minisum->DateDoneBy2Minutes;
Example

 $minutes = $minisum->DateDoneBy2Minutes( $date,$doneby );


Minutes2Text

Convert a number of minutes to displayeable text. Can also be called as a subroutine.

Input Parameters

 1 minutes for which to create a text
Output Parameters

 1 displayable text in format HH:MM
Example

 print $minisum->Minutes2Text( $minutes );


CACHE METHODS

The following methods are related to the caching of client, project and subproject combinations.


InitContactsCache

Initialize the cache of Contacts for all clients or a single client. This effectively deletes (all|the) cached table(s) and recreates those for the (now existing) client(s).

Input Parameters

 1..N clients for which to initialize contacts cache
      (default: all)
Example

 $minisum->InitContactscCache( @client );
Example

 $minisum->InitContactscCache;


InitProjectsSubprojectsCache

Initialize the cache of Projects and Subprojects for all clients. This efectively deletes all cached tables and recreates those for the now existing clients.

Input Parameters

 1..N clients for which to initialize cache
      (default: all)
Example

 $minisum->InitProjectsSubprojectscCache( @client );
Example

 $minisum->InitProjectsSubprojectscCache;


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.23, 5 December 1999

Added extra unlink in internal subroutine InitCache to make sure files do not exist, which would cause INSERT INTO OUTFILE to fail.

Version 0.22, 25 November 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method Record.

Version 0.21, 24 November 1999

Adapted internal subroutine InitCache so that the table being read from is also locked. This should speed up things quite a bit.

Version 0.20, 23 November 1999

Changed the default of number of records returned by ListByDoneBy back to 20 from 50.

Fixed problem in DateDoneBy2Minutes which would include deleted records.

Version 0.19, 20 November 1999

Added subroutine/method Minutes2Text to create displayeable time format.

Added method DateDoneBy2Minutes which returns the number of minutes someone has worked on a day.

Removed method Import as the notion of importing records has been removed from the MiniSum.

Version 0.18, 16 November 1999

Adapted methods InitContactsCache and InitProjectsSubprojectsCache and internal subroutine InitCache to accept a list of clients for which to initialize the cache, instead of just a singe client.

Adapted internal subroutine InitCache so that it will keep the old tables as much and as long as possible, so that initialization of the tables can be done during operation without too much interference.

Adapted method Contacts to use the new cache feature.

Added internal subroutine DistinctByClientCache which allows transparent searching in a cached table when available.

Added new InitContactsCache method for creating a cache of distinct contacts with a client.

Adapted method InitProjectsSubprojectsCache to use the new internal InitCache subroutine.

Added internal subroutine InitCache to create a cache of distinct field(s) for each client.

Version 0.17, 15 November 1999

Changed the default sort order of ListByDoneBy to 'created DESC'.

Version 0.16, 14 November 1999

Adapted method ProjectsSubprojects so that the cache is used if no condition is specified.

Added method InitProjectsSubprojectsCache which pre-figures out which project and subproject combinations a/each client has.

Version 0.15, 13 November 1999

Changed the default of number of records returned by ListByDoneBy from 20 to 50.

Replaced method ListDistinctProjectSubproject by method ProjectsSubprojects, which returns a much handier format, namely a reference to a list and a reference to a hash.

Version 0.14, 12 November 1999

Changed the default condition of ListByDoneBy.

Added method ListDistinctProjectSubproject.

Version 0.13, 11 November 1999

Changed methods Contacts, Projects and SubProjects so that the first parameter is the client for which to obtain the list of values.

Created new internal subroutine DistinctByClient that returns all distinct values of a field for a particular client.

Version 0.12, 9 November 1999

Adapted method ListByDoneBy to limit number of records returned to a maximum of 20 (by default).

Version 0.11, 7 November 1999

Adapted method delete so that it no longer deletes, but only sets the status to 255.

Added methods Import and UpdateFieldInIDs.

Version 0.10, 18 October 1999

First version of this true Perl module.