NAME

Liz::Forum::List - List entries in the Liz::Forum module


SYNOPSIS

 use Liz::Forum;

 $forum = new Liz::Forum;
 $list = $forum->List;


EXAMPLES


DESCRIPTION

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.


CONSTRUCTOR METHODS

The following methods create new objects.


new

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.

Input Parameters

 1 Liz::Forum object to be used
 2 identification name of list
   (default: the default list of the forum object)
Output Parameters

 1 instantiated object
Example

 $forum = new Liz::Forum( 'ModPerl' );
 $list = $forum->List;


CONTENT METHODS

The following methods allow changes to information that is associated with the list object.


Reset

Reset all message ID information in the table.

Example

 $list->Reset;
 print "All structure to messages has been removed\n";


SetTopList

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.

Input Parameters

 1..N messageID's to be put in the TopList.
Output Parameters

 1    the object itself (handy for oneliners)
Example

 @ID = $forum->TopList( 1,999999,'ID','subject' )->fetchcol(0);
 $list = $forum->List( 'bysubject' );
 $list->SetTopList( @ID );


AddMessageID

Add a message ID at the specified position. Move the message ID to the indicated position if the ID is already in the list.

Input Parameters

 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)
Example

 $list->AddMessageID( $newthreadID );
 $list->AddMessageID( $newresponseID,$parentID );


DeleteMessageID

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.

Input Parameters

 1    message ID to be deleted
 2    flag: whether to delete just this message
      (default: delete all messages below also)
Output Parameters

 1..N ID's of messages that were deleted
Example

 @removedID = $list->DeleteMessageID( $deleteID );


ExistsMessageID

Returns whether a message ID exists in the list.

Input Parameters

 1 message ID to check for
Output Parameters

 1 flag: true if ID found
Example

 if( $list->ExistsMessageID( $isitID ) ) {
   print "ID $isitID exists in this list\n";
 }


DIRECTION METHODS

The following methods can be used to ``move'' between messages in the Liz::Forum::List object.


NextMessageID

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.

Input Parameters

 1 ID of message of which to return the next ID
 2 flag: whether to not search for responses
   (default: search for responses)
Output Parameters

 1 ID of next message
   (undef = no next message)
Example

 $nextID = $list->NextMessageID( $currentID );


PreviousMessageID

Return the ID of the previous message in the tree

Input Parameters

 1 ID of message of which to return the previous ID
Output Parameters

 1 ID of previous message
   (undef = no previous message)
Example

 $previousID = $list->PreviousMessageID( $currentID );


OriginalMessageID

Return the ID of the original message (to which the first response was given) in the tree.

Input Parameters

 1 ID of message of which to return the original ID
Output Parameters

 1 ID of original message
   (undef = invalid ID to start with)
Example

 $originalID = $list->OriginalMessageID( $currentID );


ParentMessageID

Return the parent ID of a message ID

Input Parameters

 1 ID of which to obtain the parent ID
Output Parameters

 1 parent ID (undef: invalid ID specified)
Example

 $parentID = $list->ParentMessageID( $currentID );


NextThreadID

Return the ID of the first message in the next thread

Input Parameters

 1 ID of message of which to return the first in next thread
 2 original ID of message
   (default: lookup)
Output Parameters

 1 ID of first message in next thread
   (undef = no next thread)
Example

 $nextthreadID = $list->NextThreadID( $currentID );


PreviousThreadID

Return the ID of the first message in the previous thread

Input Parameters

 1 ID of message of which to return the first in previous thread
 2 original ID of message
   (default: lookup)
Output Parameters

 1 ID of first message in previous thread
   (undef = no previous thread)
Example

 $previousthreadID = $list->PreviousThreadID( $currentID );


LIST METHODS

The following methods can be used to create lists of messages within the Liz::Forum::List object.


FirstOnPage

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.

Input Parameters

 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)
Output Parameters

 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
Example

 ($firstID,$more) = $list->FirstOnPage( $currentID,5 );


LastChanged

Return the timestamp and ID of the message thread that was last changed, or return the last changed timestamp of a specific message thread.

Input Parameters

 1 ID of the message thread to obtain info of
   (default: return last changed thread info)
Output Parameters

 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
Example

 ($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";


NoThread

Used to indicate that we don't want to use the threadlist tables. Can be used in case only top-level messages are required.

Input Parameters

 1 flag to indicate if we need to drop existing 
   threadlist tables (default: don't drop existing)
Output Parameters

 1 the calling (list)object
Example

 # 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 ); 


More

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.

Input Parameters

 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)
Output Parameters

 1 flag: whether there are still messages after this page
 2 total number of messages in list
Example

 if( $list->More( $first,5 ) ) {
   print "There are still more threads\n";
 }


ThreadList

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
Input Parameters

 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)
Output Parameters

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

 $result = $list->ThreadList( $currentID );
 while( ($ID,$subject,$depth) = $result->fetchrow ) {
   print "ID: $subject ($depth)\n";
 }


getSubThread

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>

Input Parameters

 1 ID of the message/response you want to get the list of
Output Parameters

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


TopList

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
Input Parameters

 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)
Output Parameters

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

 $result = $list->TopList;
 while( ($ID,$subject,$responses) = $result->fetchrow ) {
   print "ID: $subject ($responses)\n";
 }


CONTENT METHODS

The following methods can be used to obtain information about messages in a list without having to create an entire message object.


AuthorID

Return the author ID of a message ID.

Input Parameters

 1 ID of which to obtain the author ID
Output Parameters

 1 author ID (undef: invalid ID specified)
Example

 $authorID = $list->AuthorID( $currentID );


Body

Return the body of a message ID.

Input Parameters

 1 ID of which to obtain the body
Output Parameters

 1 body (undef: invalid ID specified)
Example

 $body = $list->Body( $currentID );


Created

Return the created timestamp of a message ID

Input Parameters

 1 ID of which to obtain the created timestamp
Output Parameters

 1 created timestamp (undef: invalid ID specified)
Example

 $created = $list->Created( $currentID );


Header

Return the header of a message ID

Input Parameters

 1 ID of which to obtain the header
Output Parameters

 1 header (undef: invalid ID specified)
Example

 $header = $list->Header( $currentID );


Name

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

Input Parameters

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

 1 current/old name of list 
Example

 $xxlink = new xxLINK;
 $forum = $xxlink->Forum( 'eurest' );
 $list = $forum->List;
 $name = $list->Name;


ReSuCrUp

Return the responses, subject, the created and the updated timestamp of a message ID. Usually used when listing messages.

Input Parameters

 1 ID of which to obtain the subject, created and updated timestamp
Output Parameters

 1 responses (undef: invalid ID specified)
 2 subject
 3 created timestamp
 4 updated timestamp
Example

 ($responses,$subject,$created,$updated) = $list->ReSuCrUp( $currentID );


Responses

Return the number of responses of a message ID

Input Parameters

 1 ID of which to obtain the number of responses
Output Parameters

 1 number of responses
Example

 $responses = $list->Responses( $currentID );


Subject

Return the subject of a message ID

Input Parameters

 1 ID of which to obtain the subject
Output Parameters

 1 subject (undef: invalid ID specified)
Example

 $subject = $list->Subject( $currentID );


SuCrUp

Return the subject, the created and the updated timestamp of a message ID. Usually used when listing messages.

Input Parameters

 1 ID of which to obtain the subject, created and updated timestamp
Output Parameters

 1 subject (undef: invalid ID specified)
 2 created timestamp
 3 updated timestamp
Example

 ($subject,$created,$updated) = $list->SuCrUp( $currentID );


ThreadUpdated

Return the updated timestamp of the last updated messages in a thread.

Input Parameters

 1 originalID of which to obtain the updated timestamp
Output Parameters

 1 updated timestamp (undef: invalid ID specified)
Example

 $lastupdated = $list->ThreadUpdated( $originalID );


Updated

Return the updated timestamp of a message ID.

Input Parameters

 1 ID of which to obtain the updated timestamp
Output Parameters

 1 updated timestamp (undef: invalid ID specified)
Example

 $updated = $list->Updated( $currentID );


Other AUTOLOADed methods

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


INTERNAL METHODS

The following methods are primarily intended for internal usage only.


List

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.

Input Parameters

 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)
Output Parameters

 1..N list of ID's of the given parent in the order of the list
Example

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


UpdateTopList

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.

Example

 $list->UpdateTopList


UpdateThreadList

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.

Input Parameters

 1 ID of the message at the start of the thread
   (default: create Thread Lists for all messages in the Top List
Example

 $list->UpdateThreadList;
 print "All ThreadLists have been updated\n";

 $list->UpdateThreadList( $currentID );
 print "The ThreadList of $currentID has been updated\n";


DeleteThreadList

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.

Input Parameters

 1 ID of the message at the start of the thread
   (default: delete all thread lists)
Example

 $list->DeleteThreadList;
 print "All ThreadLists have been deleted\n";

 $list->DeleteThreadList( $currentID );
 print "The ThreadList of $currentID has been deleted\n";


Repair

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.

Example

 $list->Repair;
 print "The TopList and all ThreadLists have now been repaired\n";


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.77 28 August 2000

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

Version 0.76, 30 September 1999

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

Version 0.75, 9 July 1999

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.

Version 0.74, 23 June 1999

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

Version 0.73, 18 April 1999

Fixed problem with DeleteMessageID which would attempt to drop thread lists if there were none.

Version 0.72, 17 April 1999

Fixed problem with LastChanged which would cause an execution error when NoTread was active in a list environment.

Version 0.71, 13 April 1999

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!

Version 0.70, 9 April 1999

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.

Version 0.69, 10 January 1999

Fixed problem in AddMessageID which would prevent the right tables to be locked.

Version 0.68, 17 December 1998

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

Version 0.67, 25 November 1998

Added extra ``order'' parameter to methods TopList and ThreadList.

Version 0.66, 7 Oktober 1998

Moved code to drop threadlist-tables from new to NoThread.

Version 0.65, 6 Oktober 1998

Reduced memory footprint by fully qualifying global variables.

Added method NoThread.

Version 0.64, 17 September 1998

Method <LastChanged> now also returns the information on the message that was actually last changed (not just the thread).

Version 0.63, 10 September 1998

Added Name to add a viewable name to a list

Version 0.62, 1 September 1998

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.

Version 0.61, 28 August 1998

Fixed problem in AddMessageID when inserting before the first response.

Version 0.6, 19 August 1998

New method ExistsMessageID added: return whether a messagID exists in the list.

Fixed problem in LastChanged.

Version 0.5, 10 August 1998

Support for field 'published' added to TopList and ThreadList.

Version 0.47, 26 July 1998

Fixed problem with table locking when deleting a message.

Version 0.46, 20 July 1998

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.

Version 0.45, 18 July 1998

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.

Version 0.44, 3 July 1998

Fixed problems in NextThreadID and PreviousThreadID.

Version 0.43, 1 July 1998

Methods More and FirstOnPage now also return the total number of messages in the list.

Version 0.42, 30 June 1998

New method More allows you to find out whether there are more messages after the current page.

Version 0.41, 28 June 1998

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.

Version 0.4, 28 June 1998

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.

Version 0.3, 27 June 1998

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.

Version 0.2, 25 June 1998

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.

Version 0.1, 15 May 1998

First version of this true Perl module.