Liz::Forum - Forum module
use Liz::Forum;
$forum = new Liz::Forum;
#!/usr/local/bin/perl
use Liz::Forum;
The Liz::Forum package allows for very simple storage of messages of many kinds, such as the email, mailing lists, newsgroups, guestbooks, etc. etc.
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.
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.
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.
The following methods can be called without an object specification, but as a class method such as Liz::Forum->method().
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.
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)
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
$forum = $hn->Forum( 'technology' );
$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] ) }
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.
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)
1 instantiated object 2 flag: whether the forum was just created
$hn = new HN; $forum = $hn->Forum( 'technology' );
In HN.pm:
sub Forum { Liz::Forum->new( $_[1],$_[0] ) }
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.
1..N object types that are allowed to create new forums again
(default: no change)
1..N object types that are currently B<not> allowed to create new forums
Liz::Forum->AllowNewForum( qw(Tasking) );
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.
1..N object types that are not allowed to create new forums
(default: package name of caller)
1..N object types that are currently not allowed to create new forums
Liz::Forum->InhibitNewForum( qw(Tasking) );
or, when called inside the Tasking client module:
Liz::Forum->InhibitNewForum;
Delete one or more messages from the Liz::Forum database without first having to create an object for each message to be deleted.
1..N message ID's to be deleted
$hn = new HN; $forum = $hn->Forum( 'technology' ); $forum->delete( 3000320,3000321 );
Returns the version of the format of the database.
1 string with version of database format, usually the date the format was implemented (e.g. '19981125' );
$xxlink = new xxLINK; $forum = $xxlink->Forum( 'test' ); $version = $forum->DatabaseVersion;
Create a new Liz::EmailAddress object, either from existing information or for a new entry.
1 ID of existing email address to use (default: create new email address)
1 instantiated Liz::EmailAddress object
$hn = new HN; $forum = $hn->Forum( 'technology' );
$address = $forum->EmailAddress; $address = $forum->EmailAddress( $authorID );
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.
1 identification name of list (default: default list of forum)
1 instantiated List object
$hn = new HN; $forum = $hn->Forum( 'technology' );
$list = $forum->List; $list = $forum->List( 'overview' );
Return the tokens of the lists associated with the forum object.
1 wildcard specification to be matched (default: match all)
1 reference to list with tokens of the list associated with the forum 2 reference to hash table with names of lists
$hn = new HN;
$forum = $hn->Forum( 'technology' );
foreach( $forum->Lists ) {
$list = $forum->List( $_ );
}
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.
1 Liz::Mail object
1 instantiated Message object
$hn = new HN; $forum = $hn->Forum( 'technology' );
$mail = Liz::Mail->receive; $message = $forum->Mail( $mail );
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.
1 ID of message (default: create new object)
1 instantiated Message object
$hn = new HN; $forum = $hn->Forum( 'technology' );
$message = $forum->Message; $message = $forum->Message( $messageID );
Returns the last updated timestamp of a specific message.
1 ID of which to obtain the last updated timestamp
1 timestamp
$xxlink = new xxLINK; $forum = $xxlink->Forum( 'test' ); $updated = $forum->MessageUpdated( $ID );
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
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)
1 SQL statement handle (on which method "fetchrow" can be applied)
$result = $forum->TopList( 1,999 );
while( ($ID,$subject,$created) = $result->fetchrow ) {
print "ID: $subject ($created)\n";
}
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
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)
1 SQL statement handle (on which method "fetchrow" can be applied)
$result = $forum->ProperTopList( 1,999 );
while( ($ID,$subject,$created) = $result->fetchrow ) {
print "ID: $subject ($created)\n";
}
The following methods allow changes to information that is associated with an entire forum.
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)
1 new reference to routine to perform the conversion
1 current/old reference to routine
$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;
}
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.
1 authorID to be translated
1 name associated with the authorID 2 email address associated with the authorID
$xxlink = new xxLINK; $forum = $xxlink->Forum( 'eurest' ); $message = $forum->Message( 9000320 ); $authorID = $message->AuthorID; ($name,$email) = $forum->AuthorID2NameEmail( $authorID );
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.
1 new contents of the charter of the forum (default: no change)
1 current/old charter of forum 2 last updated timestamp of the charter
$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
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.
1 ordinal number of director message (1..255) 2 new text of director message (default: no change)
1 current/old name of director message
$xxlink = new xxLINK; $forum = $xxlink->Forum( 'eurest' ); $forum->DirectorMessage( 1,'Dat was echt niet te vreten!' );
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.
1 ID for existing associated file (default: create a new Liz::FileSet::File object)
1 instantiated Liz::FileSet::File compatible object
$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;
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.
1 ID of which to obtain the associated FileID's
(default: ID of object itself)
1..N ID's of associated Liz::FileSet::File objects
foreach( $forum->FileIDs( $messageID ) ) {
$forum->File( $_ )->Get( qw(Title MIMEType Bytes) );
print "$title ($mimetype,$bytes bytes)\n";
}
Return the FileSet object that is associated with the Forum.
1 FileSet object
$xxlink = new xxLINK; $forum = $xxlink->Forum; $fileset = $forum->FileSet;
Return one or more fields from a message, specified by its ID.
1 ID of which to obtain fields 2..N name of fields of which to obtain contents
1..N contents of specified fields
($created,$updated) = $forum->GetFieldsFromMessageID( $ID,qw(created updated) );
Specify or return the current name of the forum object. The name can be anything to further identify the goal of the forum.
1 new name of forum (default: no change)
1 current/old name of forum
$xxlink = new xxLINK; $forum = $xxlink->Forum( 'eurest' ); $forum->Name( 'Eurestjes' );
Specify or return the current options of the forum object. The options can be anything to further identify the function of the forum.
1 new options of forum (default: no change)
1 current/old options of forum
$xxlink = new xxLINK; $forum = $xxlink->Forum( 'eurest' ); $forum->Options( 'F' );
Add a user to the list of subscribers
1 name of user
$forum->Subscribe( 'Jantje' );
Checks if a user is subscribed to a forum
1 name to check
if( $forum->Subscribed( 'Jantje' ) ){
$message = 'Jantje is subscribed';
};
Returns the list of subscribers to the current forum
1 list of subscribed users
@subscribees = $forum->SubscriberList;
Return the token with which the forum is accessed.
1 token with which the forum can be accessed
$token = $forum->Token;
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.
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
$forum->UnFile( $messageID ); $forum->UnFile( $messageID,$fileID );
Remove a user from the list of subscribers
1 name of user to remove
$forum->UnSubscribe( 'Jantje' );
Elizabeth Mattijsen ( lizperl@INC.nl )
With contributions by:
- Sjoerd Lawende ( sjoerd@xxLINK.nl ) - Joris Hilhorst ( joris@xxlink.nl ) (bugfix)
(C) 1998-1999 International Network Consultants
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)
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in methods EmailAddress, Mail and FileSet.
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in methods Message and List.
Now no longer adds Exporter to ISA: it wasn't necessary.
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.
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.
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.
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.
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.
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.
Moved method GetFieldsFromMessageID here from the Liz::Forum::List module. This method is useful with a Liz::Forum environment also.
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.
Now also inherits internal field LANGUAGE, which allows language settings to filter through from the parent object in method new.
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'.
Method Token now also allowed.
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.
Method InhibitNewForum now defaults to the package name of the calling subroutine.
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.
Fixed problem in forums that would prevent the forum with the default identification from being listed.
Fixed problem in method new which would cause a database upgrade when a new forum was created.
Support for Status added: allows messages to have a status associated with it.
Support for internal subroutine RawTableName added.
New method MessageUpdated added: returns the timestamp of a specific message in the forum.
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).
Method TopList now allows en extra SQL-condition to be specified.
Reduced memory footprint by fully qualifying global variables.
Reduced memory footprint by not importing all routines from the Liz.pm module.
Added method Lists: return lists associated with the forum.
Added method Options: set/return options associated with a whole forum.
Added methods Subscribe, UnSubscribe, SubscriberList and Subscribed to provide e-mail subscribtions for forum users. (sjoerd)
Method TopList now also has a parameter to specify the field to order the list on.
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.
Removed source of method delete: now inherited from Liz::SQL.
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.
POD documentation significantly expanded.
New method Charter added: allows specification of the forum's charter (rules of use).
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.
Changed attachment table name to xxx__Attachments.
Removed method NiceDate: method Timestamp2Date should instead be used.
Method forums now also accepts a Liz::SQL compatible handle as a connection parameter.
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.
First version of this true Perl module.