NAME

Liz::PictureSet - PictureSet module


SYNOPSIS

 use Liz::PictureSet;

 $picture = new Liz::PictureSet;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::PictureSet;


DESCRIPTION

The Liz::PictureSet package allows for very simple storage of sets of pictures (image-files). As such it can function as a database for images associated with a client or a project.


Incorporate into Client Module

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

 sub PictureSet {

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

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

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

 $hn = new HN;
 $pictureset = $hn->PictureSet( 'technology' );

Note that the database connection of the picture 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::PictureSet->method().


picturesets

Return list of picture identification names of all picturesets 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->PictureSets;
 $picturesets = @{$id};
 print "All $picturesets picturesets in Hospitality Net:\n";
 foreach( @{$id} ) {
   print " PictureSet '$$name{$_}' ($_)\n";
 }

In HN.pm:

 sub PictureSets { Liz::PictureSet->picturesets( $_[1],$_[0] ) }


new

Create a new Liz::PictureSet 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 picture set
   (default: default picture 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 PictureSet was just created
Example

 $hn = new HN;
 $picture = $hn->PictureSet( 'technology' );

In HN.pm:

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


delete

Delete one or more pictures from the Liz::PictureSet database without first having to create an object for each picture to be deleted.

Input Parameters

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

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


reset

Remove all pictures from this PictureSet.

Example

 $pictureset->reset;
 print "All pictures have been removed\n";


CONTENT METHODS

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


DefaultAuthor

Specify or return the default author of newly created Picture 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
 2 timestamp when the default author info was updated
Example

 $xxlink = new xxLINK;
 $pictureset = $xxlink->PictureSet( 'graphics' );
 $pictureset->DefaultAuthor( 'Anne Eysten' );


DefaultCopyright

Specify or return the default copyright information of newly created Picture 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
 2 timestamp when the default copyright info was updated
Example

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


FSPath

Specify or return the current path on the file system where the graphics files of the pictureset 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 PictureSet 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
 2 timestamp when the path was updated
Example

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


FSPathWritable

Return a flag whether the directory in which the graphics 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;
 $pictureset = $xxlink->PictureSet( 'graphics' );
 die "Cannot store new files\n" unless $pictureset->FSPathWritable;


Name

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

Input Parameters

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

 1 current/old name of pictureset
Example

 $xxlink = new xxLINK;
 $pictureset = $xxlink->PictureSet( 'eurest' );
 $pictureset->Name( 'Eurestjes' );


URLPath

Specify or return the current path in the URL where the graphics files of the pictureset 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 PictureSet token.

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

Input Parameters

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

 1 current/old path in URL
 2 timestamp when the path was updated
Example

 $xxlink = new xxLINK;
 $pictureset = $xxlink->PictureSet( 'graphics' );
 $pictureset->URLPath( '/g' );


HTML METHODS

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


AbsoluteFileName

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

Input Parameters

 1 ID of picture of which to return the absolute filename
   (default: ID of object)
Output Parameters

 1 absolute filename of the picture
Example

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


ContentType

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

Input Parameters

 1 ID of picture of which to return the Content-Type:
   (default: ID of object)
Output Parameters

 1 content-type of the picture
Example

 <PERL>
 ContentType( $pictureset->ContentType( $ID ) );
 </PERL>


HREF

Return the (almost) complete HTML for the display of a link to the picture. Use method SRC to display the actual picture directly.

Input Parameters

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

 1 HTML for a link
Example

 <A <PRINT "$pictureset->HREF( $imageID )">>picture</A>


SRC

Return the (almost) complete HTML for the display of the picture as an image or as a button.

Input Parameters

 1 ID of the picture of which to return the HTML
   (default: ID of object)
 2 border to be used for HTML
   (default: as specified with the picture)
 3 ALT-text to be used
   (default: as specified with the picture)
 4 width to be used
   (default: as specified with the picture)
 5 height to be used
   (default: as specified with the picture)
Output Parameters

 1 HTML of complete image display
Example

 <IMG <PRINT "$pictureset->SRC( $imageID )">>
 <INPUT TYPE="image" NAME="button" <PRINT "$pictureset->SRC( $buttonID )">>


PICTURE METHODS

The following methods allow changes to a single picture in a PictureSet.


Picture

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

Input Parameters

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

 1 instantiated Picture object
Example

 $hn = new HN;
 $pictureset = $hn->PictureSet( 'technology' );

 $picture = $pictureset->Picture;
 $picture = $pictureset->Picture( 'Toilet Seats' );
 $picture = $pictureset->Picture( $pictureID );


LIST METHODS

The following methods return lists of information in various forms.


List

Return an SQL statement handle for a list of pictures.

The following fields may be specified with the first parameter:

 ID
 The ID of the picture

 title
 The title of the picture

 extension
 The extension of the graphics file (usually the type)

 width
 The width of the picture in its original size

 height
 The width of the picture in its original size

 border
 The default border to be used with this picture

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

 published
 Timestamp value when this picture was published

 created
 Timestamp value when this picture was created

 updated
 Timestamp when the picture was last updated

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

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

 paletteID
 The ID of the palette information of this picture (0 = none known)

 options
 Options associated with the picture

 status
 The status of this picture
Input Parameters

 1 fields to return (comma delimited)
   (default: 'ID,title,extension,width,height,border,alt,published,created,updated,authorID,copyrightID,paletteID,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,width,height,border,alt,published,created,updated,authorID,copyrightID,paletteID,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,width,height,border,alt,published,created,updated,authorID,copyrightID,paletteID,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' );


ListByPalette

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

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 palette of which to return a list of pictures
   (default: return pictures without a copyright)
 2 fields to return (comma delimited)
   (default: 'ID,title,extension,width,height,border,alt,published,created,updated,authorID,copyrightID,paletteID,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->ListByPalette( 'True Color' );


ID2NAME METHODS

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


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";
 }


Palette2ListHash

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

Input Parameters

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

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

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


MANIPULATION METHODS

The Liz::PictureSet module does not contain any direct image manipulation methods, but does contain some interfaces with other image manipulation libraries/utilities such as the GD library.


GDImage

Return a GD::Image object for a picture with a specific ID. possible.

Input Parameters

 1 ID of Picture object to create GD::Image object of
Output Parameters

 1 GD::Image object (if possible)
Example

 $myImage = $pictureset->GDImage( $ID );
Note

The GD library is not included with the Liz::PictureSet module, and must therefore be -use-d seperately for this to work properly.


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.28, 3 December 1999

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

Version 0.27, 25 November 1999

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

Version 0.26, 1 October 1999

Fixed problem in new caused by change back of semantics in Liz::CategorySet's NameAlways2ParentIDFields. This causes a lot of things to be fixed in a number of Categorysets.

Version 0.25, 30 September 1999

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

Version 0.24, 5 September 1999

Now allows autoloaded method Token.

Version 0.23, 4 September 1999

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

Version 0.22, 1 September 1999

Fixed prblem in new that would cause the wrong parentID's to be stored in the object, causing future author, copyright and palette info to be stored in the top of the CategorySet tree. Probably also introduced on August 20th.

Fixed problem in new that would cause incorrect default author and copyright info to be stored in the object if any were specified. This was probably introduced on August 20th.

Adapted documentation of DefaultAuthor, DefaultCopyright, FSPath and URLPath to indicate the possibility of obtaining last updated info in a list context.

Version 0.21, 31 August 1999

Method new now sets the field PACKAGEPARENTID with the ID value of the parentID under which all other categories are located.

Version 0.20, 30 August 1999

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

Version 0.19, 29 August 1999

Method GDImage added: create a GD::Image object for manipulation given a specific ID.

Version 0.18, 20 August 1999

Method new now prepared to handle extra fields when available.

Version 0.17, 17 August 1999

Method picturesets now reduced to a call to Liz::SQL's ``sets''.

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

Changed to new source typography.

Version 0.16, 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.15, 9 July 1999

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

Version 0.14, 23 June 1999

Changed from using method ``Exists'' to ``Count'' in method new to allow much quicker check of whether a table exists.

Version 0.13, 21 January 1999

New method ContentType added: returns the content-type associated with a picture.

New method AbsoluteFileName added: returns the absolute filename of the picture on the filesystem it is stored.

Methods HREF and SRC now default to the ID of the object, so they can be inherited by subclasses.

Version 0.12, 7 January 1999

Fixed problem in picturesets that would prevent the picturset with the default identifications from being listed.

Version 0.11, 31 December 1998

Methods delete and reset now properly call their SUPER:: versions.

Version 0.1, 30 December 1998

First version of this true Perl module.