From 83db4d0e95cb1d672cd91113eb4b507df18d437f Mon Sep 17 00:00:00 2001 From: JT Smith Date: Sun, 19 Oct 2003 16:55:33 +0000 Subject: [PATCH] adding POD --- lib/WebGUI/Forum.pm | 15 ++ lib/WebGUI/Forum/Post.pm | 207 ++++++++++++++++++++++- lib/WebGUI/Forum/Thread.pm | 337 ++++++++++++++++++++++++++++++++++++- 3 files changed, 553 insertions(+), 6 deletions(-) diff --git a/lib/WebGUI/Forum.pm b/lib/WebGUI/Forum.pm index 4a44fd929..e0e8787fb 100644 --- a/lib/WebGUI/Forum.pm +++ b/lib/WebGUI/Forum.pm @@ -33,6 +33,21 @@ Data management class for forums. $forum = WebGUI::Forum->create(\%forumParams); $forum = WebGUI::Forum->new($forumId); + $boolean = $forum->canPost; + $scalar = $forum->get($param); + $obj = $forum->getThread($threadId); + $boolean = $forum->isModerator; + $boolean = $forum->isSubscribed; + + $forum->incrementReplies($postDate, $postId); + $forum->incrementThreads($postDate, $postId); + $forum->incrementViews; + $forum->purge; + $forum->recalculateRating; + $forum->set(\%data); + $forum->subscribe; + $forum->unsubscribe; + =head1 METHODS These methods are available from this class: diff --git a/lib/WebGUI/Forum/Post.pm b/lib/WebGUI/Forum/Post.pm index 1bbe49c89..3d8812422 100644 --- a/lib/WebGUI/Forum/Post.pm +++ b/lib/WebGUI/Forum/Post.pm @@ -28,8 +28,28 @@ Data management class for forum posts. =head1 SYNOPSIS use WebGUI::Forum::Post; - $forum = WebGUI::Forum::Post->create(\%params); - $forum = WebGUI::Forum::Post->new($postId); + $post = WebGUI::Forum::Post->create(\%params); + $post = WebGUI::Forum::Post->new($postId); + + $boolean = $post->canEdit; + $scalar = $post->get("forumPostId"); + $arrayRef = $post->getReplies; + $obj = $post->getThread; + $boolean = $post->hasRated; + $boolean = $post->isMarkedRead; + $boolean = $post->isReply; + + $post->incrementViews; + $post->markRead; + $post->rate($rating); + $post->recalculateRating; + $post->set(\%data); + $post->setStatusApproved; + $post->setStatusArchived; + $post->setStatusDeleted; + $post->setStatusDenied; + $post->setStatusPending; + $post->unmarkRead; =head1 METHODS @@ -187,12 +207,36 @@ sub hasRated { return $flag; } +#------------------------------------------------------------------- + +=head2 incrementViews ( ) + +Increments the views counter for this post. + +=cut + sub incrementViews { my ($self) = @_; WebGUI::SQL->write("update forumPost set views=views+1 where forumPostId=".$self->get("forumPostId")); $self->getThread->incrementViews; } +#------------------------------------------------------------------- + +=head2 isMarkedRead ( [ userId ] ) + +Returns a boolean indicating whether this post is marked read for the user. + +=over + +=item userId + +A unique id for a user that you want to check. Defaults to the current user. + +=back + +=cut + sub isMarkedRead { my ($self, $userId) = @_; $userId = $session{user}{userId} unless ($userId); @@ -200,6 +244,14 @@ sub isMarkedRead { return $isRead; } +#------------------------------------------------------------------- + +=head2 isReply ( ) + +Returns a boolean indicating whether this post is a reply or the root post in a thread. + +=cut + sub isReply { my ($self) = @_; if ($self->get("parentId") > 0) { @@ -209,6 +261,22 @@ sub isReply { } } +#------------------------------------------------------------------- + +=head2 markRead ( [ userId ] ) + +Marks this post read for this user. + +=over + +=item userId + +A unique identifier for a user. Defaults to the current user. + +=back + +=cut + sub markRead { my ($self, $userId) = @_; $userId = $session{user}{userId} unless ($userId); @@ -219,6 +287,22 @@ sub markRead { $self->incrementViews; } +#------------------------------------------------------------------- + +=head2 new ( postId ) + +Constructor. + +=over + +=item postId + +The unique identifier for the post object you wish to retrieve. + +=back + +=cut + sub new { my ($class, $forumPostId) = @_; my $properties = WebGUI::SQL->getRow("forumPost","forumPostId",$forumPostId); @@ -229,6 +313,30 @@ sub new { } } +#------------------------------------------------------------------- + +=head2 rate ( rating [ , userId, ipAddress ] ) + +Stores a rating against this post. + +=over + +=item rating + +An integer between 1 and 5 (5 being best) to rate this post with. + +=item userId + +The unique id for the user rating this post. Defaults to the current user. + +=item ipAddress + +The ip address of the user doing the rating. Defaults to the current user's IP. + +=back + +=cut + sub rate { my ($self, $rating, $userId, $ipAddress) = @_; $userId = $session{user}{userId} unless ($userId); @@ -238,6 +346,14 @@ sub rate { $self->recalculateRating; } +#------------------------------------------------------------------- + +=head2 recalculateRating ( ) + +Recalculates the average rating of the post from all the ratings and stores the result to the database. + +=cut + sub recalculateRating { my ($self) = @_; my ($count) = WebGUI::SQL->quickArray("select count(*) from forumPostRating where forumPostId=".$self->get("forumPostId")); @@ -248,6 +364,23 @@ sub recalculateRating { $self->getThread->recalculateRating; } +#------------------------------------------------------------------- + +=head2 set ( data ) + +Sets properties to the database and the object. + +=over + +=item data + +A hash reference containing the properties to set. See the forumPost table for details. + +=back + +=cut + + sub set { my ($self, $data) = @_; $data->{forumPostId} = $self->get("forumPostId") unless ($data->{forumPostId}); @@ -257,6 +390,15 @@ sub set { } } +#------------------------------------------------------------------- + +=head2 setStatusApproved ( ) + +Sets the status of this post to approved. + +=cut + + sub setStatusApproved { my ($self) = @_; $self->set({status=>'approved'}); @@ -266,6 +408,32 @@ sub setStatusApproved { } } +#------------------------------------------------------------------- + +=head2 setStatusArchived ( ) + +Sets the status of this post to archived. + +=cut + + +sub setStatusArchived { + my ($self) = @_; + $self->set({status=>'archived'}); + $self->getThread->setStatusArchived if ($self->getThread->get("rootPostId") == $self->get("forumPostId")); + if ($self->isReply) { + $self->getThread->incrementReplies($self->get("dateOfPost"),$self->get("forumPostId")); + } +} + +#------------------------------------------------------------------- + +=head2 setStatusDeleted ( ) + +Sets the status of this post to deleted. + +=cut + sub setStatusDeleted { my ($self) = @_; $self->set({status=>'deleted'}); @@ -273,22 +441,55 @@ sub setStatusDeleted { if ($self->getThread->get("lastPostId") == $self->get("forumPostId")) { my ($id, $date) = WebGUI::SQL->quickArray("select forumPostId,dateOfPost from forumPost where forumThreadId=" .$self->get("forumThreadId")." and status='approved'"); - $self->getThread->setLastPost($id,$date); + $self->getThread->setLastPost($date,$id); } } +#------------------------------------------------------------------- + +=head2 setStatusDenied ( ) + +Sets the status of this post to denied. + +=cut + sub setStatusDenied { my ($self) = @_; $self->set({status=>'denied'}); $self->getThread->setStatusDenied if ($self->getThread->get("rootPostId") == $self->get("forumPostId")); } +#------------------------------------------------------------------- + +=head2 setStatusPending ( ) + +Sets the status of this post to pending. + +=cut + sub setStatusPending { my ($self) = @_; $self->set({status=>'pending'}); $self->getThread->setStatusPending if ($self->getThread->get("rootPostId") == $self->get("forumPostId")); } + +#------------------------------------------------------------------- + +=head2 unmarkRead ( [ userId ] ) + +Negates the markRead method. + +=over + +=item userId + +The unique id of the user marking unread. Defaults to the current user. + +=back + +=cut + sub unmarkRead { my ($self, $userId) = @_; $userId = $session{user}{userId} unless ($userId); diff --git a/lib/WebGUI/Forum/Thread.pm b/lib/WebGUI/Forum/Thread.pm index 330cb3680..4e21ef0f9 100644 --- a/lib/WebGUI/Forum/Thread.pm +++ b/lib/WebGUI/Forum/Thread.pm @@ -29,8 +29,34 @@ Data management class for forum threads. =head1 SYNOPSIS use WebGUI::Forum; - $forum = WebGUI::Forum::Thread->create(\%params); - $forum = WebGUI::Forum::Thread->new($threadId); + $thread = WebGUI::Forum::Thread->create(\%params); + $thread = WebGUI::Forum::Thread->new($threadId); + + $scalar = $thread->get($param); + $obj = $thread->getForum; + $obj = $thread->getNextThread; + $obj = $thread->getPost($postId); + $obj = $thread->getPreviousThread; + $boolean = $thread->isLocked; + $boolean = $thread->isSticky; + $boolean = $thread->isSubscribed; + + $thread->incrementReplies($postDate, $postId); + $thread->incrementViews; + $thread->lock; + $thread->recalculateRating; + $thread->set(\%data); + $thread->setLastPost($postDate,$postId); + $thread->setStatusApproved; + $thread->setStatusArchived; + $thread->setStatusDeleted; + $thread->setStatusDenied; + $thread->setStatusPending; + $thread->stick; + $thread->subscribe; + $thread->unlock; + $thread->unstick; + $thread->unsubscribe; =head1 METHODS @@ -38,6 +64,26 @@ These methods are available from this class: =cut +#------------------------------------------------------------------- + +=head2 create ( data, postData ) + +Creates a new thread, including the root post in that thread. + +=over + +=item data + +The properties of this thread. See the forumThread table for details. + +=item postData + +The properties of the root post in this thread. See the forumPost table and the WebGUI::Forum::Post->create method for details. + +=back + +=cut + sub create { my ($self, $data, $postData) = @_; $data->{forumThreadId} = "new"; @@ -55,6 +101,22 @@ sub create { return $self; } +#------------------------------------------------------------------- + +=head2 get ( [ param ] ) + +Returns a hash reference containing all the properties of this thread. + +=over + +=item param + +The name of a specific property. If specified only the value of that property will be return as a scalar. + +=back + +=cut + sub get { my ($self, $key) = @_; if ($key eq "") { @@ -63,6 +125,14 @@ sub get { return $self->{_properties}->{$key}; } +#------------------------------------------------------------------- + +=head2 getForum ( ) + +Returns a forum object for the forum that is related to this thread. + +=cut + sub getForum { my ($self) = @_; unless (exists $self->{_forum}) { @@ -71,6 +141,14 @@ sub getForum { return $self->{_forum}; } +#------------------------------------------------------------------- + +=head2 getNextThread ( ) + +Returns a thread object for the next (newer) thread in the same forum. + +=cut + sub getNextThread { my ($self) = @_; unless (exists $self->{_next}) { @@ -81,6 +159,22 @@ sub getNextThread { return $self->{_next}; } +#------------------------------------------------------------------- + +=head getPost ( postId ) + +Returns a post object. + +=over + +=item + +The unique id of the post object you wish to retrieve. + +=back + +=cut + sub getPost { my ($self, $postId) = @_; unless (exists $self->{_post}{$postId}) { @@ -89,6 +183,14 @@ sub getPost { return $self->{_post}{$postId}; } +#------------------------------------------------------------------- + +=head2 getPreviousThread ( ) + +Returns a thread object for the previous (older) thread in the same forum. + +=cut + sub getPreviousThread { my ($self) = @_; unless (exists $self->{_previous}) { @@ -99,11 +201,39 @@ sub getPreviousThread { return $self->{_previous}; } +#------------------------------------------------------------------- + +=head2 isLocked ( ) + +Returns a boolean indicating whether this thread is locked from new posts and other edits. + +=cut + sub isLocked { my ($self) = @_; return $self->get("isLocked"); } +#------------------------------------------------------------------- + +=head2 incrementReplies ( lastPostDate, lastPostId ) + +Increments the replies counter for this thread. + +=over + +=item lastPostDate + +The date of the reply that caused the replies counter to be incremented. + +=item lastPostId + +The id of the reply that caused the replies counter to be incremented. + +=back + +=cut + sub incrementReplies { my ($self, $dateOfReply, $replyId) = @_; WebGUI::SQL->write("update forumThread set replies=replies+1, lastPostId=$replyId, lastPostDate=$dateOfReply @@ -111,17 +241,49 @@ sub incrementReplies { $self->getForum->incrementReplies($dateOfReply,$replyId); } +#------------------------------------------------------------------- + +=head2 incrementViews ( ) + +Increments the views counter for this thread. + +=cut + sub incrementViews { my ($self) = @_; WebGUI::SQL->write("update forumThread set views=views+1 where forumThreadId=".$self->get("forumThreadId")); $self->getForum->incrementViews; } +#------------------------------------------------------------------- + +=head2 isSticky ( ) + +Returns a boolean indicating whether this thread should be "stuck" a the top of the forum and not be sorted with the rest of the threads. + +=cut + sub isSticky { my ($self) = @_; return $self->get("isSticky"); } +#------------------------------------------------------------------- + +=head2 isSubscribed ( [ userId ] ) + +Returns a boolean indicating whether the user is subscribed to this thread. + +=over + +=item userId + +The unique id of the user to check. Defaults to the current user. + +=back + +=cut + sub isSubscribed { my ($self, $userId) = @_; $userId = $session{user}{userId} unless ($userId); @@ -130,11 +292,35 @@ sub isSubscribed { return $isSubscribed; } +#------------------------------------------------------------------- + +=head2 lock ( ) + +Sets this thread to be locked from edits. + +=cut + sub lock { my ($self) = @_; $self->set({isLocked=>1}); } +#------------------------------------------------------------------- + +=head2 new ( threadId ) + +Constructor. + +=over + +=item threadId + +The unique id of the thread object you wish to retrieve. + +=back + +=cut + sub new { my ($class, $forumThreadId) = @_; my $properties = WebGUI::SQL->getRow("forumThread","forumThreadId",$forumThreadId); @@ -145,6 +331,14 @@ sub new { } } +#------------------------------------------------------------------- + +=head2 recalculateRating ( ) + +Recalculates the average rating of this thread based upon all of the posts in the thread. + +=cut + sub recalculateRating { my ($self) = @_; my ($count) = WebGUI::SQL->quickArray("select count(*) from forumPost where forumThreadId=".$self->get("forumThreadId")." and rating>0"); @@ -155,6 +349,22 @@ sub recalculateRating { $self->getForum->recalculateRating; } +#------------------------------------------------------------------- + +=head2 set ( data ) + +Sets properties for this thread both to the object and to the database. + +=over + +=item data + +A hash reference containing the properties to set. See the forumThread table for details. + +=back + +=cut + sub set { my ($self, $data) = @_; $data->{forumThreadId} = $self->get("forumThreadId") unless ($data->{forumThreadId}); @@ -164,39 +374,128 @@ sub set { } } +#------------------------------------------------------------------- + +=head2 setLastPost ( lastPostDate, lastPostId ) + +Sets the pertinent details for the last post. Can also be done directly using the set method. + +=over + +=item lastPostDate + +The epoch date of the post. + +=item lastPostId + +The unique id of the post. + +=back + +=cut + sub setLastPost { - my ($self, $postId, $postDate) = @_; + my ($self, $postDate, $postId) = @_; $self->set({ lastPostId=>$postId, lastPostDate=>$postDate }); } +#------------------------------------------------------------------- + +=head2 setStatusApproved ( ) + +Sets the status of this thread to approved. + +=cut + sub setStatusApproved { my ($self) = @_; $self->set({status=>'approved'}); } +#------------------------------------------------------------------- + +=head2 setStatusArchived ( ) + +Sets the status of this thread to archived. + +=cut + +sub setStatusArchived { + my ($self) = @_; + $self->set({status=>'archived'}); +} + +#------------------------------------------------------------------- + +=head2 setStatusDeleted ( ) + +Sets the status of this thread to deleted. + +=cut + sub setStatusDeleted { my ($self) = @_; $self->set({status=>'deleted'}); } +#------------------------------------------------------------------- + +=head setStatusDenied ( ) + +Sets the status of this thread to denied. + +=cut + sub setStatusDenied { my ($self) = @_; $self->set({status=>'denied'}); } +#------------------------------------------------------------------- + +=head setStatusPending ( ) + +Sets the status of this thread to pending. + +=cut + sub setStatusPending { my ($self) = @_; $self->set({status=>'pending'}); } +#------------------------------------------------------------------- + +=head2 stick ( ) + +Makes this thread sticky. + +=cut + sub stick { my ($self) = @_; $self->set({isSticky=>1}); } +#------------------------------------------------------------------- + +=head2 subscribe ( [ userId ] ) + +Subscribes the user to this thread. + +=over + +=item userId + +The unique id of the user. Defaults to the current user. + +=back + +=cut + sub subscribe { my ($self, $userId) = @_; $userId = $session{user}{userId} unless ($userId); @@ -205,16 +504,48 @@ sub subscribe { } } +#------------------------------------------------------------------- + +=head2 unlock ( ) + +Negates the lock method. + +=cut + sub unlock { my ($self) = @_; $self->set({isLocked=>0}); } +#------------------------------------------------------------------- + +=head2 unstick ( ) + +Negates the stick method. + +=cut + sub unstick { my ($self) = @_; $self->set({isSticky=>0}); } +#------------------------------------------------------------------- + +=head2 unsubscribe ( [ userId ] ) + +Negates the subscribe method. + +=over + +=item userId + +The unique id of the user to unsubscribe. Defaults to the current user. + +=back + +=cut + sub unsubscribe { my ($self, $userId) = @_; $userId = $session{user}{userId} unless ($userId);