NAME

Liz::FileSet - FileSet module


SYNOPSIS

 use Liz::FileSet;

 $file = new Liz::FileSet;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::FileSet;


DESCRIPTION

The Liz::FileSet package allows for very simple storage of sets of files. As such it can function as a database for files associated with a client or a project.


Incorporate into Client Module

The Liz::FileSet 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 FileSet method of HN.pm module:

 sub FileSet {

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

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

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

 $hn = new HN;
 $fileset = $hn->FileSet( '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::FileSet->method().


filesets

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

Input Parameters

 1 wildcard specification to match
   (default: all)
 2 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
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->FileSets;
 $filesets = @{$id};
 print "All $filesets filesets in Hospitality Net:\n";
 foreach( @{$id} ) {
   print " FileSet '$$name{$_}' ($_)\n";
 }

In HN.pm:

 sub FileSets { Liz::FileSet->filesets( $_[1],$_[0] ) }


new

Create a new Liz::FileSet 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 identification name of file set
   (default: default file set for database)
 2 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
Output Parameters

 1 instantiated object
 2 flag indicating whether the FileSet was just created
Example

 $hn = new HN;
 $file = $hn->FileSet( 'technology' );

In HN.pm:

 sub FileSet { Liz::FileSet->new( $_[1],$_[0] ) }


delete

Delete one or more files from the Liz::FileSet database without first having to create an object for each file to be deleted.

Input Parameters

 1..N file ID's to be deleted
Example

 $hn = new HN;
 $file = $hn->FileSet( 'technology' );
 $file->delete( 3000320,3000321 );


reset

Remove all files from this FileSet.

Example

 $fileset->reset;
 print "All files have been removed\n";


CONTENT METHODS

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


DefaultAuthor

Specify or return the default author of newly created File objects. If no author information is specified with a new object, the default author will be filled in. Use method DefaultCopyright to specify the default copyright information.

Input Parameters

 1 new default author information
   (default: no change)
Output Parameters

 1 current/old default author information
Example

 $xxlink = new xxLINK;
 $fileset = $xxlink->FileSet( 'graphics' );
 $fileset->DefaultAuthor( 'Anne Eysten' );


DefaultCopyright

Specify or return the default copyright information of newly created File objects. If no copyright information is specified with a new object, the default copyright information will be filled in. Use method DefaultAuthor to specify the default author information.

Input Parameters

 1 new default copyright information
   (default: no change)
Output Parameters

 1 current/old default copyright information
Example

 $xxlink = new xxLINK;
 $fileset = $xxlink->FileSet( 'graphics' );
 $fileset->DefaultCopyright( '(C) 1998 xxLINK Internet Services' );


FSPath

Specify or return the current path on the file system where the files of the fileset object are stored. It should be specified at least once during the lifetime of the database associated with the object. It defaults to the ENV{'DOCUMENT_ROOT'} directory, followed by a lowercase version of the FileSet token.

A double slash at the beginning of the path, may be used to indicate a directory relative to the ENV{'DOCUMENT_ROOT'}.

Use method URLPath to specify the path to be used in URL's.

Input Parameters

 1 new path on filesystem
   (default: no change)
Output Parameters

 1 current/old path on filesystem
Example

 $xxlink = new xxLINK;
 $fileset = $xxlink->FileSet( 'graphics' );
 $fileset->FSPath( '/export/home/local/www/xxlink/root/g' );
 $fileset->FSPath( '//g' );


FSPathWritable

Return a flag whether the directory in which the files are stored, can be written to by the process we're currently in.

Output Parameters

 1 flag: whether the directory is writable
Example

 $xxlink = new xxLINK;
 $fileset = $xxlink->FileSet( 'graphics' );
 die "Cannot store new files\n" unless $fileset->FSPathWritable;


Name

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

Input Parameters

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

 1 current/old name of fileset
Example

 $xxlink = new xxLINK;
 $fileset = $xxlink->FileSet( 'eurest' );
 $fileset->Name( 'Eurestjes' );


URLPath

Specify or return the current path in the URL where the files of the fileset object are available from the Internet. It should be specified at least once during the lifetime of the database associated with the object. It defaults to a lowercase version of the FileSet token.

Use method FSPath to specify the path to be used to store the files on the file system.

Input Parameters

 1 new path in URL
   (default: no change)
Output Parameters

 1 current/old path in URL
Example

 $xxlink = new xxLINK;
 $fileset = $xxlink->FileSet( 'graphics' );
 $fileset->URLPath( '/g' );


HTML METHODS

The following methods create HTML of Liz::Perl's pseudo HTML from information in a fileset.


AbsoluteFileName

Return the absolute filename of file, specified by ID. Usually used in connection with the AsIs function of Liz::Perl. Use method MIMEType to find out the MIME-type associated with the file.

Input Parameters

 1 ID of file of which to return the absolute filename
   (default: ID of object)
 2 alternate extension to be used
   (default: current extension)
Output Parameters

 1 absolute filename of the file
Example

 <PERL>
 AsIs( $fileset->AbsoluteFileName( $ID ) );
 </PERL>


MIMEType

Return the MIME-type of file, specified by ID. Usually used in conjunction with the ContentType function of Liz::Perl. Use method AbsoluteFileName to find out the location of the file on the filesystem where it is stored.

Input Parameters

 1 ID of file of which to return the MIMEType:
   (default: ID of object)
Output Parameters

 1 MIMEtype of the file
Example

 <PERL>
 ContentType( $fileset->MIMEType( $ID ) );
 </PERL>


HREF

Return the (almost) complete HTML for the display of a link to the file.

Input Parameters

 1 ID of the file of which to return the HTML
   (default: ID of object)
 2 ALT-text to be used
   (default: as specified with the file)
Output Parameters

 1 HTML for a link
Example

 <A <PRINT "$fileset->HREF( $fileID )">>file</A>


SRC

Return the (almost) complete HTML for the display of the file as an IMG.

Input Parameters

 1 ID of the file of which to return the HTML
   (default: ID of object)
 2 ALT-text to be used
   (default: as specified with the file)
Output Parameters

 1 HTML for a link
Example

 <IMG <PRINT "$fileset->SRC( $ID )">>


FILE METHODS

The following methods allow changes to a single file in a FileSet.


File

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

Input Parameters

 1 ID/name to create File object with
   (default: none = new file)
 2 sortname of file (name of which file should be sorted)
   (default: same as name if 1st parameter is name)
Output Parameters

 1 instantiated File object
Example

 $hn = new HN;
 $fileset = $hn->FileSet( 'technology' );

 $file = $fileset->File;
 $file = $fileset->File( 'Toilet Seats' );
 $file = $fileset->File( $fileID );


LIST METHODS

The following methods return lists of files in various forms.


List

Return an SQL statement handle for a list of files.

The following fields may be specified with the first parameter:

 ID
 The ID of the file

 title
 The title of the file

 extension
 The extension of the file (usually the type)

 mimetype
 The mimetype of the file (usually directly related to the type)

 alt
 The default ALT-text to be used with this file

 published
 Timestamp value when this file was published

 created
 Timestamp value when this file was created

 updated
 Timestamp when the file was last updated

 authorID
 The ID of the author of this file (0 = none known)

 copyrightID
 The ID of the copyright information of this file (0 = none known)

 options
 Options associated with the file

 status
 The status of this file
Input Parameters

 1 fields to return (comma delimited)
   (default: 'ID,title,extension,mimetype,alt,published,created,updated,authorID,copyrightID,options,status' );
 2 fieldname on which to order the result
   (default: 'created')
 3 extra condition to be applied
   (default: none)
Output Parameters

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


ListByAuthor

Return an SQL statement handle for a list of pictures belonging to a specific Author.

The same fields that can be specified with the first input parameter of the method List can be specified here with the second input parameter.

Input Parameters

 1 author of which to return a list of pictures
   (default: return pictures without an Author)
 2 fields to return (comma delimited)
   (default: 'ID,title,extension,mimetype,alt,published,created,updated,authorID,copyrightID,options,status' );
 3 fieldname on which to order the result
   (default: 'created')
 4 extra condition to be applied
   (default: none)
Output Parameters

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

 $result = $pictureset->ListByAuthor( 'Karel Appel' );


ListByCopyright

Return an SQL statement handle for a list of pictures that have a specific Copyright.

The same fields that can be specified with the first input parameter of the method List can be specified here with the second input parameter.

Input Parameters

 1 copyright of which to return a list of pictures
   (default: return pictures without a copyright)
 2 fields to return (comma delimited)
   (default: 'ID,title,extension,mimetype,alt,published,created,updated,authorID,copyrightID,options,status' );
 3 fieldname on which to order the result
   (default: 'created')
 4 extra condition to be applied
   (default: none)
Output Parameters

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

 $result = $pictureset->ListByCopyright( '(C) 1999 NRC' );


ID2NAME METHODS

These methods allow for easy translation of ID's to names, such as AuthorID and CopyrightID.


Author2ListHash

Return a reference to a list containing author ID's and a hash containing the names of the available authors, keyed to their ID's.

Input Parameters

 1 order in which the names should be returned
   (default: 'sortname')
 2 condition to be applied
   (default: none)
Output Parameters

 1 reference to list containing authorID's
 2 reference to hash contain Author names
Example

 ($list,$hash) = $pictureset->Author2ListHash;
 foreach (@{$list}) {
   print "$_: $$hash{$_}\n";
 }


Copyright2ListHash

Return a reference to a list of copyright ID's and a hash containing the text of the available copyright info, keyed to their ID's.

Input Parameters

 1 order in which the copyright info should be returned
   (default: 'sortname')
 2 condition to be applied
   (default: none)
Output Parameters

 1 reference to list of copyright info ID's
 2 reference to hash contain copyright info
Example

 ($list,$hash) = $pictureset->Copyright2ListHash;
 foreach (@{$list}) {
   print "$_: $$hash{$_}\n";
 }


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.32, 3 December 1999

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

Version 0.31, 25 November 1999

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

Version 0.30, 30 September 1999

Now no longer adds Exporter to ISA: it wasn't necessary.

Version 0.29, 4 September 1999

Added methods ListByAuthor, ListByCopyright (and internal subroutine ListBy). Return a SQL-result handle for a specific Author or Copyright.

Version 0.28, 1 September 1999

Finally fixed problem in new with regards to storing Author and Copyright info at the wrong place in the CategorySet.

Version 0.27, 30 August 1999

Fixed problem in new which would caused Copyright information to be stored at the wrong location in the CategorySet.

New methods Author2ListHash and Copyright2ListHash added. For easy conversion between xxxID's and assciated names.

Version 0.26, 20 August 1999

Changed method new so that any extra fields are handled properly.

Version 0.25, 16 August 1999

Class method filesets now just calls Liz::SQL's ``sets'' method.

Method new now calls Liz::SQL's ``new'' to create an object.

Changed source to new typography.

Version 0.24, 14 August 1999

Removed dependency on local GetSetMeta internal subroutine and replaced this with a call to the new method TableMeta of the Liz::SQL module.

Version 0.23, 9 July 1999

Changed CREATE TABLE to new Liz::SQL 'create' method format.

Version 0.22, 23 June 1999

Changed from using method ``Exists'' to ``Count'' in method new to check for the existence of a table more quickly.

Version 0.21, 15 April 1999

Support for the SRC method added. Also, ALT texts are not shown anymore if they are empty.

Support for the Data field added.

Version 0.2, 11 March 1999

Added alternate extension parameter to method AbsoluteFileName.

Renamed method ContentType to the more appropriate MIMEType.

Added field for mimetypes in database, and added support for it in methods ContentType and List.

Version 0.1, 10 March 1999

First version of this true Perl module. Copied from the Liz::PictureSet module, which is less general than this.