Liz::Forum::List - List entries in the Liz::Forum module
use Liz::Forum;
$forum = new Liz::Forum; $list = $forum->List;
The Liz::Forum::List package allows the messages that are stored with the Liz::Forum package to be ordered in a specific way: if there is no Liz::Forum::List object available, then the messages are only stored chronologically, in the order they arrive.
With the Liz::Forum::List package an tree-like order can be applied to the messages stored with the Liz::Forum package. Even more than one order for the same set of messages is possible.
The following methods create new objects.
Create a new Liz::Forum::List object from an already existing Liz::Forum object. Normally not called by itself, but with the Liz::Forum->List method.
1 Liz::Forum object to be used 2 identification name of list (default: the default list of the forum object)
1 instantiated object
$forum = new Liz::Forum( 'ModPerl' ); $list = $forum->List;
The following methods allow changes to information that is associated with the list object.
Reset all message ID information in the table.
$list->Reset; print "All structure to messages has been removed\n";
Reset the entire list structure and fill it with the list of messageID's specified as the top layer.
If you are sure that no threads will ever exist in this list, be user to call method NoThread at least once before for the lifetime of this list.
1..N messageID's to be put in the TopList.
1 the object itself (handy for oneliners)
@ID = $forum->TopList( 1,999999,'ID','subject' )->fetchcol(0); $list = $forum->List( 'bysubject' ); $list->SetTopList( @ID );
Add a message ID at the specified position. Move the message ID to the indicated position if the ID is already in the list.
1 message ID to be added or moved 2 message ID of parent to which this ID belongs (default: top level message) 3 message ID or ordinal number (if top level) after which this message should be added (default: at end) 4 flag: do not update TopList (default: update)
$list->AddMessageID( $newthreadID ); $list->AddMessageID( $newresponseID,$parentID );
Delete a message ID and all the message ID's that have that message ID as a (grand) parent. Optionally allows the messages below to be saved: in that case they will appended to the response list of the parent of the message ID being deleted.
1 message ID to be deleted
2 flag: whether to delete just this message
(default: delete all messages below also)
1..N ID's of messages that were deleted
@removedID = $list->DeleteMessageID( $deleteID );
Returns whether a message ID exists in the list.
1 message ID to check for
1 flag: true if ID found
if( $list->ExistsMessageID( $isitID ) ) {
print "ID $isitID exists in this list\n";
}
The following methods can be used to ``move'' between messages in the Liz::Forum::List object.
Return the ID of the next message in the tree. By default, this is the first response of the current message, or the next message if there are no responses. If response search is inhibited, then the next message on the same level will be returned.
The ID of the next message will always be returned, unless the current ID is actually the very, very last message in the list.
1 ID of message of which to return the next ID 2 flag: whether to not search for responses (default: search for responses)
1 ID of next message (undef = no next message)
$nextID = $list->NextMessageID( $currentID );
Return the ID of the previous message in the tree
1 ID of message of which to return the previous ID
1 ID of previous message (undef = no previous message)
$previousID = $list->PreviousMessageID( $currentID );
Return the ID of the original message (to which the first response was given) in the tree.
1 ID of message of which to return the original ID
1 ID of original message (undef = invalid ID to start with)
$originalID = $list->OriginalMessageID( $currentID );
Return the parent ID of a message ID
1 ID of which to obtain the parent ID
1 parent ID (undef: invalid ID specified)
$parentID = $list->ParentMessageID( $currentID );
Return the ID of the first message in the next thread
1 ID of message of which to return the first in next thread 2 original ID of message (default: lookup)
1 ID of first message in next thread (undef = no next thread)
$nextthreadID = $list->NextThreadID( $currentID );
Return the ID of the first message in the previous thread
1 ID of message of which to return the first in previous thread 2 original ID of message (default: lookup)
1 ID of first message in previous thread (undef = no previous thread)
$previousthreadID = $list->PreviousThreadID( $currentID );
The following methods can be used to create lists of messages within the Liz::Forum::List object.
Returns the ordinal number of the first ID that is on a page that contains the specified ID and for the specified page size. Similar to More but uses an ID as the base instead of an ordinal number.
1 ID of the message of which to obtain the first ordinal number 2 page size to be used (default: 10) 3 ID of the original message of the thread in ThreadList table (default: look at TopList table)
1 ordinal number of first ID on that page 2 flag: whether there are still messages after this page 3 total number of messages in list
($firstID,$more) = $list->FirstOnPage( $currentID,5 );
Return the timestamp and ID of the message thread that was last changed, or return the last changed timestamp of a specific message thread.
1 ID of the message thread to obtain info of (default: return last changed thread info)
1 timestamp of the last edited message thread 2 ID of the last edited message thread 3 ordinal number of ID in TopList 4 timestamp of the message that was actually last edited 5 ID of the message that was actually last edited 6 ordinal number of ID in ThreadList
($updated,$lastID) = $list->LastChanged; print "The last ID was $lastID, which was updated on $updated\n";
$updated = $list->LastChanged( $currentID ); print "The current ID ($currentID) was updated on $updated\n";
Used to indicate that we don't want to use the threadlist tables. Can be used in case only top-level messages are required.
1 flag to indicate if we need to drop existing threadlist tables (default: don't drop existing)
1 the calling (list)object
# Make a new list and don't use threads $list = $forum->List( 'a_nice_token' )->NoThread; # Open an existing list and kill any existing threadlist tables $list = $forum->List( 'existing_list_token' )->NoThread( 1 );
Returns flag indicating whether there are more entries after the given page. Similar to FirstOnPage but uses the ordinal number as a base instead of an ID.
1 ordinal number of first entry to be listed 2 page size to be used (default: 10) 3 ID of the original message of the thread in ThreadList table (default: look at TopList table)
1 flag: whether there are still messages after this page 2 total number of messages in list
if( $list->More( $first,5 ) ) {
print "There are still more threads\n";
}
Return an SQL statement handle for a list of messages in a thread, including the top level message.
The following fields may be specified with the 4th parameter:
ID The message ID of the message
subject The subject of the message
depth The depth of the message in the thread (0 = top message)
created Timestamp value when this message was created
name The name of the author of the message, if known
email The email address of the author of the message, if known
authorID The ID of the author: meaning depends on your particular implementation
directormessage Ordinal number of the director message, 0 if no director messages used
updated Timestamp when the message was last updated
published Timestamp when the message was published
1 ID of the top level message in the thread 2 ID of message or ordinal number from which to commence listing (default: list from top) 3 number of messages to list (default: 10) 4 number of messages to list before specified ID (default: 0) 5 fields to return (comma delimited) (default: 'ID,subject,depth,created,name,email,authorID,directormessage,updated,published' ) 6 order in which to list (default: ordinal)
1 SQL statement handle (on which method "fetchrow" can be applied)
$result = $list->ThreadList( $currentID );
while( ($ID,$subject,$depth) = $result->fetchrow ) {
print "ID: $subject ($depth)\n";
}
Return an SQL statement handle for a list of responses of a specific thread message, either toplevel or a response. Includes the original thread. the list returned is UNORDERED
U<NOTE: this function needs the table-integrity of the Liz::Forum::List construction>
1 ID of the message/response you want to get the list of
list of ID's (all children) =item Example
@result = $list->getSubThread( $currentID );
while ( my $r_arg = shift (@result) ) {
my ($ID, $subject, $depth) = @$r_arg;
print "ID $ID: $subject ($depth)\n";
}
Return an SQL statement handle for a list of top level messages (beginning of threads) with the most recent entry last.
The following fields may be specified with the 4th parameter:
ID The message ID of the message
subject The subject of the message
responses The total number of responses in this thread
created Timestamp value when this thread was created
name The name of the author of the message, if known
email The email address of the author of the message, if known
authorID The ID of the author: meaning depends on your particular implementation
directormessage Ordinal number of the director message, 0 if no director messages used
updated Timestamp when the thread was last updated
published Timestamp when the thread was last published
1 ordinal number or ID of message from which to commence listing (default: list from top) 2 number of messages to list (default: 10) 3 number of messages to list before specified ID (default: 0) 4 fields to return (comma delimited) (default: 'ID,subject,responses,created,name,email,authorID,directormessage,updated,published' ) 5 field(s) to order on (default: ordinal)
1 SQL statement handle (on which method "fetchrow" can be applied)
$result = $list->TopList;
while( ($ID,$subject,$responses) = $result->fetchrow ) {
print "ID: $subject ($responses)\n";
}
The following methods can be used to obtain information about messages in a list without having to create an entire message object.
Return the author ID of a message ID.
1 ID of which to obtain the author ID
1 author ID (undef: invalid ID specified)
$authorID = $list->AuthorID( $currentID );
Return the body of a message ID.
1 ID of which to obtain the body
1 body (undef: invalid ID specified)
$body = $list->Body( $currentID );
Return the created timestamp of a message ID
1 ID of which to obtain the created timestamp
1 created timestamp (undef: invalid ID specified)
$created = $list->Created( $currentID );
Return the header of a message ID
1 ID of which to obtain the header
1 header (undef: invalid ID specified)
$header = $list->Header( $currentID );
Specify or return the current name of the list object. The name can be anything to further identify the goal of the list.
1 new name of list (default: no change)
1 current/old name of list
$xxlink = new xxLINK; $forum = $xxlink->Forum( 'eurest' ); $list = $forum->List; $name = $list->Name;
Return the responses, subject, the created and the updated timestamp of a message ID. Usually used when listing messages.
1 ID of which to obtain the subject, created and updated timestamp
1 responses (undef: invalid ID specified) 2 subject 3 created timestamp 4 updated timestamp
($responses,$subject,$created,$updated) = $list->ReSuCrUp( $currentID );
Return the number of responses of a message ID
1 ID of which to obtain the number of responses
1 number of responses
$responses = $list->Responses( $currentID );
Return the subject of a message ID
1 ID of which to obtain the subject
1 subject (undef: invalid ID specified)
$subject = $list->Subject( $currentID );
Return the subject, the created and the updated timestamp of a message ID. Usually used when listing messages.
1 ID of which to obtain the subject, created and updated timestamp
1 subject (undef: invalid ID specified) 2 created timestamp 3 updated timestamp
($subject,$created,$updated) = $list->SuCrUp( $currentID );
Return the updated timestamp of the last updated messages in a thread.
1 originalID of which to obtain the updated timestamp
1 updated timestamp (undef: invalid ID specified)
$lastupdated = $list->ThreadUpdated( $originalID );
Return the updated timestamp of a message ID.
1 ID of which to obtain the updated timestamp
1 updated timestamp (undef: invalid ID specified)
$updated = $list->Updated( $currentID );
The following methods are AUTOLOADed: they can be used to change fields in the object or add values to already existing fields. Prefix values with ``+='' to append to existing values.
These methods do not exist in this module but are allowed to be executed on the object:
LevelHash NextIDHash OriginalIDHash ParentIDHash PreviousIDHash ResponsesHash
The following methods are primarily intended for internal usage only.
Return the list of ID's that belong to a certain parent ID. The list object contains various types of information about the ID's returned after execution of this method.
1 parent ID of message of which to return the list (default: list from top) 2 number of levels of recursion for creation of list (default: 0, -1 for maximum number of levels, >0 limited number of levels) 3 maximum number of ID's to obtain (default: unlimited)
1..N list of ID's of the given parent in the order of the list
@ID = $list->List; print "There are ".scalar(@ID)." threads\n";
@ID = $list->List( $currentID ); print "There are ".scalar(@ID)." direct responses to $currentID\n";
@ID = $list->List( $currentID,-1 ); print "There are ".scalar(@ID)." total responses to $currentID\n";
Create a new list of message at the top. This is normally not needed, but can be handy when messages are updated externally with a maintenance module. Calling this method will then make sure that the Top List is up-to-date.
$list->UpdateTopList
Create a new list of message in a thread. This is normally not needed, but can be handy when messages are updated externally with a maintenance module. Calling this method will then make sure that the Thread List is up-to-date.
1 ID of the message at the start of the thread (default: create Thread Lists for all messages in the Top List
$list->UpdateThreadList; print "All ThreadLists have been updated\n";
$list->UpdateThreadList( $currentID ); print "The ThreadList of $currentID has been updated\n";
Delete a Thread List of a message. This is normally not needed, but can be handy when messages are deleted externally with a maintenance module. Calling this method will then make sure that the Thread List has been removed.
1 ID of the message at the start of the thread (default: delete all thread lists)
$list->DeleteThreadList; print "All ThreadLists have been deleted\n";
$list->DeleteThreadList( $currentID ); print "The ThreadList of $currentID has been deleted\n";
This method should not be needed, but can be handy in case something has gone wrong. It basically re-creates all the TopList en ThreadList extra tables for the current Liz::Forum::List object.
$list->Repair; print "The TopList and all ThreadLists have now been repaired\n";
Elizabeth Mattijsen ( lizperl@INC.nl )
(C) 1998-1999 International Network Consultants
Added External function getSubThread which lists all of the children (unordered for now)
Added Internal function Joris_getChildren($id) which returns
all direct children. (uses $self->{TABLE} . '_' ) This function is
called recursively by getSubThread. because of the recursiveness, it is
important that changes to Liz::Forum::List tables are done through the
Liz::Forum::List interface.
Danger of stack overflow if you don't heed the above warning
In situations where it is possible that the tables are changed externally, Don't use this function.
Author: Joris Hilhorst : xxLINK internet Services. joris@xxlink.nl
Now no longer adds Exporter to ISA: it wasn't necessary.
Changed CREATE TABLEs to use new Liz::SQL 'create' method when possible.
Streamlined various methods using up-to-date Perl knowledge.
Changed source typography to new format.
Changed from using method ``Exists'' to ``Count'' in methods new and UpdateThreadList to check for the existence of a table much more quickly.
Fixed problem with DeleteMessageID which would attempt to drop thread lists if there were none.
Fixed problem with LastChanged which would cause an execution error when NoTread was active in a list environment.
Method Reset now refrains from attempting to delete ThreadList tables when the NoThread flag had been set.
Every ALTER TABLE SQL query that could be combined into a single SQL query, has now been combined. This should give a significant speed increase one larger tables.
Fixed problem in SetTopList: it would only reset the list!
Added fixed parameter to m// and s/// to increase speed at the expense of memory.
Moved method GetFieldsFromMessageID to the Liz::Forum module.
New method SetTopList added: set the top list of MessageID's according to a list of ID's.
Fixed problem in AddMessageID which would prevent the right tables to be locked.
Method AddMessageID now allows the ID after which a message should be added, to be specified as an ordinal number if the message is a top level message
Added extra ``order'' parameter to methods TopList and ThreadList.
Reduced memory footprint by fully qualifying global variables.
Added method NoThread.
Method <LastChanged> now also returns the information on the message that was actually last changed (not just the thread).
Added Name to add a viewable name to a list
Method AddMessageID can now also be used to move an existing ID to another location in the list. This also solves a problem when inserting the same ID twice, which would cause the list to become corrupt.
Method Reset now also removes all ThreadList tables.
Added simple examples to all method documentation.
Fixed problem in AddMessageID when inserting before the first response.
New method ExistsMessageID added: return whether a messagID exists in the list.
Fixed problem in LastChanged.
Support for field 'published' added to TopList and ThreadList.
Fixed problem with table locking when deleting a message.
New internal method Repair added: repairs all tables associated with a Liz::Forum::List object.
Fixed problem in UpdateTopList introduced with version on July 18.
New method ThreadUpdated: returns the last updated timestamp of the last updated message in a thread.
Fixed problems in TopList: last updated info there now always reflects the last updated info of the last changed message in the thread.
Fixed problems in NextThreadID and PreviousThreadID.
Methods More and FirstOnPage now also return the total number of messages in the list.
New method More allows you to find out whether there are more messages after the current page.
Method FirstOnPage can now also be used for threads and now also optionally returns a flag to indicate whether there are messages after the current page.
New method FirstOnPage: returns the ordinal number of the first ID on the page of a specified ID and page size. Output can be used as the first input parameter to TopList.
Method DeleteMessageID now allows deleting of one message only, and to keep the messages below the message being deleted.
New internal subroutine UpdateAuthorIDs: updates the name and email values in the TopList and ThreadList tables.
Methods TopList and ThreadList now allow the author's name and email address to also be returned.
Support for author's name and email address added.
Method List now sets the level information starting at 1, to make it more consistent with ThreadList.
New method ThreadList added: returns a SQL statement handle of the messages in a thread. New method DeleteThreadList added: deletes a ThreadList table. Not needed normally. Handy if changes were made to the Forum outside of the Liz::Forum::List module. New method UpdateThreadList added: either updates all ThreadList tables or a specific ThreadList from scratch. Handy if changes were made to the Forum outside of the Liz::Forum::List module.
Internal support for ThreadList added. Now, whenever a new message is added to or a message is deletedi from a thread, an extra ThreadList table is updated which contains information for listing of that thread.
New method LastChanged added: returns timestamp and ID of message thread that was last changed.
New method TopList added: returns a SQL statement handle of the messages at the beginning of the threads. New method UpdateTopList added: updates the TopList table from scratch. Handy if changes were made to the Forum outside of the Liz::Forum::List module.
Internal support for TopList added. Now, whenever a new message is added or a message is deleted, an extra TopList table is updated which contains information for listing the top of the threads.
First version of this true Perl module.