NAME

Liz::Forum - Forum module


SYNOPSIS

 use Liz::Forum;

 $forum = new Liz::Forum;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::Forum;


DESCRIPTION

The Liz::Forum package allows for very simple storage of messages of many kinds, such as the email, mailing lists, newsgroups, guestbooks, etc. etc.


SubModules

The Liz::Forum package by itself is not very useful. But by either explicitely or implicitely using the Liz::Forum::Message and Liz::Forum::List submodules very powerful Hypermail, forum like applications can be built.

The Liz::Forum submodules are automatically included in the Liz::Forum module, so they do not need to be used externally also. The Liz::Forum module provides an interface to these submodules using the instantiated forum object.

An example of this is:

 $forum = new Liz::Forum;
 $message = $forum->Message;

The $forum object is a Liz::Forum object as expected, the $message object is a Liz::Forum::Message object, which may not be so clear at first hand.


Incorporate into Client Module

But even the Liz::Forum 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 (e.g. by specifying an alternate Author routine).

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

 sub Forum {

 # Obtain the parameters
 # Start the forum using the $hn handle as the database handle
 # Make sure we use the HN's module authorID -> Name/Email translation
 # Return the finished object

 my( $hn,$token ) = @_;
 my( $forum ) = Liz::Forum->new( $token,$hn );
 $forum->Author( \&DefaultAuthorID2NameEmail );
 $forum;
 }

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

 $hn = new HN;
 $forum = $hn->Forum( 'technology' );

Note that the database connection of the forum is hidden in the creation of the $hn object, and the customisation of the alternate authorID -> Name/Email translation is hidden in the creation of the $forum object.


Lists versus Archives

There are basically two ways in which the Liz::Forum module and its submodules can be used: either to create an archive of messages, in which there is no order other than the order in which messages are added to the database. Or as a thread-ordered list of messages such as seen in newsgroups.

In the archive mode of a forum, only the Liz::Forum and Liz::Forum::Message module are active. In the thread-ordered list of messages mode the Liz::Forum::List module is also used.

It is very important to realise that the messages by itself are stored in the database without any ``order'' in them. The ``structure'' of a forum is added ``later'' by creating an associated Liz::Forum::List object. So adding a message to a forum consists of a) adding a message with the Liz::Forum::Message->update method and b) adding the message location in the structure with a Liz::Forum::List->update method.

This approach allows archives to be created without the overhead of the structure, whereas on the other hand it is possible to have more than one ``independent'' lists apply to the same Liz::Forum object. This allows e.g. a simple implementation of a public forum in which maintainers are able to respond to messagesi that will be visible to other maintainers, without having those responses appear in the public version of the forum.


CLASS METHODS

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


forums

Return list of forum identification names of all forums 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
 3 reference to hash with database versions
Example

 $forum = $hn->Forum( 'technology' );
Example

 $hn = new HN;
 ($id,$name) = $hn->Forums;
 $forums = @{$id};
 print "All $forums forums in Hospitality Net:\n";
 foreach( 0..$#$id ) {
   print " Forum '$$name[$_]' ($$id[$_])\n";
 }

In HN.pm:

 sub Forums { Liz::Forum->forums( $_[1],$_[0] ) }


new

Create a new Liz::Forum 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 forum
   (default: default forum 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: whether the forum was just created
Example

 $hn = new HN;
 $forum = $hn->Forum( 'technology' );

In HN.pm:

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


AllowNewForum

Specify the object type(s) that are allowed to create any new forums. By default, an object is allowed to create new forums. Use class method InhibitNewForum to dis-allow creation of new forums.

Input Parameters

 1..N object types that are allowed to create new forums again
      (default: no change)
Output Parameters

 1..N object types that are currently B<not> allowed to create new forums
Example

 Liz::Forum->AllowNewForum( qw(Tasking) );


InhibitNewForum

Specify the object type(s) that are not allowed to create any new forums. This is particularly handy in a ModPerl environment. Use class method AllowNewForum to allow creation of new forums again.

Input Parameters

 1..N object types that are not allowed to create new forums
      (default: package name of caller)
Output Parameters

 1..N object types that are currently not allowed to create new forums
Example

 Liz::Forum->InhibitNewForum( qw(Tasking) );

or, when called inside the Tasking client module:

 Liz::Forum->InhibitNewForum;


delete

Delete one or more messages from the Liz::Forum database without first having to create an object for each message to be deleted.

Input Parameters

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

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


DatabaseVersion

Returns the version of the format of the database.

Output Parameters

 1 string with version of database format, usually the date the format was implemented
   (e.g. '19981125' );
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum( 'test' );
 $version = $forum->DatabaseVersion;


EmailAddress

Create a new Liz::EmailAddress object, either from existing information or for a new entry.

Input Parameters

 1 ID of existing email address to use
   (default: create new email address)
Output Parameters

 1 instantiated Liz::EmailAddress object
Example

 $hn = new HN;
 $forum = $hn->Forum( 'technology' );

 $address = $forum->EmailAddress;
 $address = $forum->EmailAddress( $authorID );


List

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

Input Parameters

 1 identification name of list
   (default: default list of forum)
Output Parameters

 1 instantiated List object
Example

 $hn = new HN;
 $forum = $hn->Forum( 'technology' );

 $list = $forum->List;
 $list = $forum->List( 'overview' );


Lists

Return the tokens of the lists associated with the forum object.

Input Parameters

 1 wildcard specification to be matched
   (default: match all)
Output Parameters

 1 reference to list with tokens of the list associated with the forum
 2 reference to hash table with names of lists
Example

 $hn = new HN;
 $forum = $hn->Forum( 'technology' );
 foreach( $forum->Lists ) {
   $list = $forum->List( $_ );
 }


Mail

Create a new Liz::Forum::Message object from a Liz::Mail object. This is e.g. handy when storing the output of a mailing list into a forum database. For more information, see the Liz::Forum::Message object itself.

Input Parameters

 1 Liz::Mail object
Output Parameters

 1 instantiated Message object
Example

 $hn = new HN;
 $forum = $hn->Forum( 'technology' );

 $mail = Liz::Mail->receive;
 $message = $forum->Mail( $mail );


Message

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

Input Parameters

 1 ID of message
   (default: create new object)
Output Parameters

 1 instantiated Message object
Example

 $hn = new HN;
 $forum = $hn->Forum( 'technology' );

 $message = $forum->Message;
 $message = $forum->Message( $messageID );


MessageUpdated

Returns the last updated timestamp of a specific message.

Input Parameters

 1 ID of which to obtain the last updated timestamp
Output Parameters

 1 timestamp
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum( 'test' );
 $updated = $forum->MessageUpdated( $ID );


TopList

Return an SQL statement handle for a list of messages in the order in which they are stored in the database. It is similar, but not identical to the TopList method of the Liz::Forum::List module.

The following fields may be specified with the 4th parameter:

 ID
 The message ID of the message

 subject
 The subject of the message

 created
 Timestamp value when this message was created

 authorID
 The ID of the author: meaning depends on your particular implementation

 directormessage
 Ordinal number of the director message (0..255), 0 if no director messages used

 updated
 Timestamp when the message was last updated in the database

 published
 Timestamp when the message was published (as specified by the program)

 foreignkey
 The foreign key associated with the message

 status
 The status (0..255) associated with the message
Input Parameters

 1 ordinal number of message from which to commence listing
   (default: 1)
 2 number of messages to list
   (default: 10)
 3 fields to return (comma delimited)
   (default: 'ID,subject,created,authorID,directormessage,updated,published,foreignkey' )
 4 order in which to return messages
   (default: created)
 5 extra SQL condition to be applied
   (default: none)
Output Parameters

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

 $result = $forum->TopList( 1,999 );
 while( ($ID,$subject,$created) = $result->fetchrow ) {
   print "ID: $subject ($created)\n";
 }
NOTE: DEPRECATED DO NOT USE. use ProperTopList instead.


ProperTopList

NOTE: this is a fixed version of TopList. use this instead of TopList

Return an SQL statement handle for a list of messages in the order in which they are stored in the database. It is similar, but not identical to the TopList method of the Liz::Forum::List module.

The following fields may be specified with the 4th parameter:

 ID
 The message ID of the message

 subject
 The subject of the message

 created
 Timestamp value when this message was created

 authorID
 The ID of the author: meaning depends on your particular implementation

 directormessage
 Ordinal number of the director message (0..255), 0 if no director messages used

 updated
 Timestamp when the message was last updated in the database

 published
 Timestamp when the message was published (as specified by the program)

 foreignkey
 The foreign key associated with the message

 status
 The status (0..255) associated with the message
Input Parameters

 1 ordinal number of message from which to commence listing
   (default: 1)
 2 number of messages to list
   (default: 10)
 3 fields to return (comma delimited)
   (default: 'ID,subject,created,authorID,directormessage,updated,published,foreignkey' )
 4 order in which to return messages
   (default: created)
 5 extra SQL condition to be applied
   (default: none)
Output Parameters

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

 $result = $forum->ProperTopList( 1,999 );
 while( ($ID,$subject,$created) = $result->fetchrow ) {
   print "ID: $subject ($created)\n";
 }


CONTENT METHODS

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


Author

Specify or return the reference to the routine that should be called to convert an AuthorID to a name and email address. If no such reference is specified for a forum, then the Liz::EmailAddress module will be used to store names and email addresses in the same database as the forum.

Since the conversion from AuthorID to name and email address is dependent on the actual usage of the Liz::Forum module, this routine can be supplied externally. By using an externally supplied routine for the conversion, it is possible for the Liz::Forum module to supply a generic interface to this conversion, namely the AuthorID2NameEmail method.

Is such a custom routine exists, this method should be called whenever a new forum object is created (at the same time method new is called). The reference to the routine is not stored in the database, just in the instantiated forum object.

The routine should expect two arguments:

 1 the forum object
 2 the authorID of which to obtain name and emailaddress

The routine should return two arguments:

 1 the name of the author (if any)
 2 the email address of the author (if any)
Input Parameters

 1 new reference to routine to perform the conversion
Output Parameters

 1 current/old reference to routine
Example

 $hn = new HN;
 $forum = $hn->Forum( 'technology' );

In HN.pm:

 sub Forum {
 my( $hn,$token ) = @_;
 my( $forum ) = Liz::Forum->new( $token,$hn );
 $forum->Author( \&DefaultAuthorID2NameEmail );
 $forum;
 }


AuthorID2NameEmail

Convert an AuthorID to the associated name and email address. This uses the subroutine previously specified with Author or the default subroutine provided by the Liz::Forum module.

Input Parameters

 1 authorID to be translated
Output Parameters

 1 name associated with the authorID
 2 email address associated with the authorID
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum( 'eurest' );
 $message = $forum->Message( 9000320 );
 $authorID = $message->AuthorID;
 ($name,$email) = $forum->AuthorID2NameEmail( $authorID );


Charter

Specify or return the current charter of the forum object. The charter is no more and no less than a set of rules that govern the usage of the forum.

Input Parameters

 1 new contents of the charter of the forum
   (default: no change)
Output Parameters

 1 current/old charter of forum
 2 last updated timestamp of the charter
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum( 'eurest' );
 $forum->Charter( <<EOD );
 Wat heb je vandaag gegeten? en was het lekker? niet teveel betaald? 
 <P>
 In dit forum is plaats voor discussies over ons Eurest restaurant
 of beter gezegd: kantine. 
 EOD


DirectorMessage

Specify or return a directory message of the forum object. A Director Message is a standard message that can be applied to a forum message to indicate a specific value or endorsement by the management of the forum.

This method allows the specification of the director messages available in the forum. It is possible to specify one of these messages to be associated with each message in the forum with the DirectorMessage method of the Liz::Forum::Message submodule.

Input Parameters

 1 ordinal number of director message (1..255)
 2 new text of director message
   (default: no change)
Output Parameters

 1 current/old name of director message
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum( 'eurest' );
 $forum->DirectorMessage( 1,'Dat was echt niet te vreten!' );


File

Create a Liz::FileSet::File object for a new file associated with a message object, or create a Liz::FileSet::File object for an existing file associated with a message object, specified by its ID.

Use method FileIDs to obtain the list of IDs of files associated with the object.

Liz::FileSet::File objects created in this way, are automatically updated when the Message object is updated.

Input Parameters

 1 ID for existing associated file
   (default: create a new Liz::FileSet::File object)
Output Parameters

 1 instantiated Liz::FileSet::File compatible object
Example

 $file = $forum->File( $messageID );
 $file->Title( 'image.jpg' );
 $file->Extension( 'jpg' );
 $file->MIMEType( 'image/jpeg' );
 $file->Contents( $contents );
 $file->update;

 $file = $forum->File( $fileID );
 $contents = $forum->File( $fileID )->Contents;


FileIDs

Return the ID's of the Liz::FileSet::File objects that are associated with a specific Message object. Use method File to obtain the Liz::FileSet::File object with the fileID specified.

Input Parameters

 1    ID of which to obtain the associated FileID's
      (default: ID of object itself)
Output Parameters

 1..N ID's of associated Liz::FileSet::File objects
Example

 foreach( $forum->FileIDs( $messageID ) ) {
   $forum->File( $_ )->Get( qw(Title MIMEType Bytes) );
   print "$title ($mimetype,$bytes bytes)\n";
 }


FileSet

Return the FileSet object that is associated with the Forum.

Output Parameters

 1 FileSet object
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum;
 $fileset = $forum->FileSet;


GetFieldsFromMessageID

Return one or more fields from a message, specified by its ID.

Input Parameters

 1    ID of which to obtain fields
 2..N name of fields of which to obtain contents
Output Parameters

 1..N contents of specified fields
Example

 ($created,$updated) =
  $forum->GetFieldsFromMessageID( $ID,qw(created updated) );


Name

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

Input Parameters

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

 1 current/old name of forum
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum( 'eurest' );
 $forum->Name( 'Eurestjes' );


Options

Specify or return the current options of the forum object. The options can be anything to further identify the function of the forum.

Input Parameters

 1 new options of forum
   (default: no change)
Output Parameters

 1 current/old options of forum
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum( 'eurest' );
 $forum->Options( 'F' );


Subscribe

Add a user to the list of subscribers

Input Parameters

 1 name of user
   
Example

 $forum->Subscribe( 'Jantje' );


Subscribed

Checks if a user is subscribed to a forum

Input Parameters

 1 name to check 
   
Example

 if( $forum->Subscribed( 'Jantje' ) ){
  $message = 'Jantje is subscribed';
 };


SubscriberList

Returns the list of subscribers to the current forum

Output Parameters

 1 list of subscribed users
   
Example

 @subscribees = $forum->SubscriberList;


Token

Return the token with which the forum is accessed.

Output Parameters

 1 token with which the forum can be accessed
Example

 $token = $forum->Token;


UnFile

Remove one or more Liz::FileSet::File objects associated with a Liz::Forum::Message object, specified by its ID.

Use method FileIDs to obtain the list of IDs of files associated with the object.

Input Parameters

 1    ID of Liz::Forum::Message object
      (default: ID of object itself)
 2..N ID's of existing associated files
      (default: all fileID's associated with Message object
Example

 $forum->UnFile( $messageID );
 $forum->UnFile( $messageID,$fileID );


UnSubscribe

Remove a user from the list of subscribers

Input Parameters

 1 name of user to remove
   
Example

 $forum->UnSubscribe( 'Jantje' );


AUTHORS

Elizabeth Mattijsen ( lizperl@INC.nl )

With contributions by:

- Sjoerd Lawende ( sjoerd@xxLINK.nl ) - Joris Hilhorst ( joris@xxlink.nl ) (bugfix)


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.72, 17 August 2000

Created the Liz::Forum::ProperTopList method to cover for the bug in Liz::Forum::TopList. Because of possible old code that are using their own local fixes, a new function was added and the TopList function has been declared DEPRECATED.

Joris Hilhorst (joris@xxlink.nl)

Version 0.71, 3 December 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in methods EmailAddress, Mail and FileSet.

Version 0.70, 25 November 1999

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

Version 0.69, 30 September 1999

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

Version 0.68, 17 August 1999

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

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

Version 0.67, 9 July 1999

Changed all CREATE TABLEs to use the new Liz::SQL 'create' method.

Streamlined all methods related to subscribing and subscriptions.

Changed source to new typography.

Version 0.66, 23 June 1999

Replaced calls to method ``Exists'' to ``Count'' in method new, which is a much faster method for checking the existence of a table, especially with large databases.

Version 0.65, 10 May 1999

The old attachmentstable (which wasn't being used anymore now that we have FileSet) is now being removed. The database format level is now raised to ``19990510''.

Method new now also obtains the names of any extra fields into the object, so that any Liz::Forum::Message subclassed does not have to access the Meta-information for each message that is opened.

Version 0.64, 9 May 1999

Method new now optionally returns a flag indicating whether the forum was just created. This is to facilitate subclassing of the Liz::Forum module in the future.

Version 0.63, 18 April 1999

Method delete now properly deletes any associated files also.

Moved methods File, FileIDs and UnFile here from the Liz::Forum::Message sub-module, to facilitate deleting of Message objects.

Version 0.62, 9 April 1999

Moved method GetFieldsFromMessageID here from the Liz::Forum::List module. This method is useful with a Liz::Forum environment also.

Version 0.61, 8 April 1999

Added caching of data in the AuthorID2NameEmail method. Before executing the actual routine, the hash in the object is checked for previous requests for the same authorID. The cache is kept for the lifetime of the forum object: creating a new forum object effectively creates a new cache, should that be necessary.

Version 0.60, 23 March 1999

Now also inherits internal field LANGUAGE, which allows language settings to filter through from the parent object in method new.

Version 0.59, 22 March 1999

Added support for HTML version of message, to allow for easy integration with the new Liz::Mail module, which allows an HTML version of the body to be specified and sent. This now causes a database format change to version '19990322'.

Version 0.58, 14 March 1999

Method Token now also allowed.

Version 0.57, 11 March 1999

New method FileSet added: returns the Liz::FileSet object that is associated with the forum.

Field 'TOKEN' now also being set with the token used for the database.

Version 0.56, 5 February 1999

Method InhibitNewForum now defaults to the package name of the calling subroutine.

Version 0.55, 3 February 1999

Added class methods InhibitNewForum and AllowNewForum: these allow (re-)setting of a global flag that is checked by method new when a new forum is about to be created.

Version 0.54, 7 January 1999

Fixed problem in forums that would prevent the forum with the default identification from being listed.

Version 0.53, 29 December 1998

Fixed problem in method new which would cause a database upgrade when a new forum was created.

Version 0.52, 15 December 1998

Support for Status added: allows messages to have a status associated with it.

Support for internal subroutine RawTableName added.

Version 0.51, 10 December 1998

New method MessageUpdated added: returns the timestamp of a specific message in the forum.

Version 0.5, 27 November 1998

Support for foreign keys added. Also: databases are now automatically converted to newer formats when the new method is called and it is found that the database has an older format.

Method forums now also returns a reference to a hash which contains the database version of each of the forums (since this is done without creating a database link, the version of the database is not changed to the most recent).

Method TopList now also returns the foreign key value if now fields are specified.

New method DatabaseVersion added: returns the database version of the forum (usually the date the format of the database was updated).

Version 0.47, 29 October 1998

Method TopList now allows en extra SQL-condition to be specified.

Version 0.46, 6 October 1998

Reduced memory footprint by fully qualifying global variables.

Version 0.45, 24 September 1998

Reduced memory footprint by not importing all routines from the Liz.pm module.

Version 0.44, 10 September 1998

Added method Lists: return lists associated with the forum.

Version 0.43, 9 September 1998

Added method Options: set/return options associated with a whole forum.

Version 0.42, 27 August 1998

Added methods Subscribe, UnSubscribe, SubscriberList and Subscribed to provide e-mail subscribtions for forum users. (sjoerd)

Version 0.41, 24 August 1998

Method TopList now also has a parameter to specify the field to order the list on.

Version 0.4, 21 August 1998

Method TopList added: return a list of the messages stored in the forum. Similar to TopList of Liz::Forum::List but uses the intrinsic order of messages in the database itself.

Version 0.34, 13 August 1998

Removed source of method delete: now inherited from Liz::SQL.

Version 0.33, 18 July 1998

Method forums now returns a reference to a hash instead of a reference to a list. This shouldn't break too many things yet, but would make much more sense.

Method Charter now also returns the last updated info of the charter.

Version 0.32, 7 July 1998

POD documentation significantly expanded.

Version 0.31, 29 June 1998

New method Charter added: allows specification of the forum's charter (rules of use).

Version 0.3, 28 June 1998

New autoloaded method Author added: specify the reference to the routine to perform AuthorID -> name and email address conversion.

New method AuthorID2NameEmail: converts an authorID to a name and email address using the subroutine specified with Author or the default routine supplied by the Liz::Forum module.

Support for default authorID to name and email conversion added.

Fixed problem in method forums: sub-tables such as the TopList and ThreadList were seen as forums.

Version 0.2, 26 June 1998

Changed attachment table name to xxx__Attachments.

Removed method NiceDate: method Timestamp2Date should instead be used.

Version 0.12, 20 June 1998

Method forums now also accepts a Liz::SQL compatible handle as a connection parameter.

Version 0.11, 4 June 1998

New method Mail: create a Liz::Forum::Message object from a Liz::Mail object.

Method new now also accepts a Liz::SQL compatible handle as a connection parameter.

Version 0.1, 25 May 1998

First version of this true Perl module.