[vhffs-dev] [2012] Reworked Vhffs::Tag

[subversion@xxxxxxxxxxxxx]

Revision: 2012
Author:   gradator
Date:     2012-02-17 00:55:06 +0100 (Fri, 17 Feb 2012)
Log Message:
-----------
Reworked Vhffs::Tag

Modified Paths:
--------------
    trunk/vhffs-api/src/Vhffs/Tag.pm

Modified: trunk/vhffs-api/src/Vhffs/Tag.pm
===================================================================
--- trunk/vhffs-api/src/Vhffs/Tag.pm	2012-02-16 22:15:09 UTC (rev 2011)
+++ trunk/vhffs-api/src/Vhffs/Tag.pm	2012-02-16 23:55:06 UTC (rev 2012)
@@ -28,14 +28,18 @@
 # ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 # POSSIBILITY OF SUCH DAMAGE.
 
-=head1 Vhffs::Tag
-=head2 SYNOPSIS
+=head1 NAME
 
-Object allowing tags manipulation
+Vhffs::Tag - Class allowing tags manipulation
 
+=head1 SYNOPSIS
+
+
+
+=head1 CLASS METHODS
+
 =cut
 
-
 use strict;
 use utf8;
 
@@ -44,20 +48,13 @@
 
 package Vhffs::Tag;
 
-sub create {
-	my ($main, $label, $description, $creator, $category, $created) = @_;
-	$created = time() unless(defined $created);
-	
-	my $dbh = $main->get_db_object();
-	
-	my $sql = q{INSERT INTO vhffs_tag(label, description, updated, category_id, updater_id) VALUES(?, ?, ?, ?, ?)};
-	my $sth = $dbh->prepare($sql);
-	$sth->execute($label, $description, $created, $category->{category_id}, $creator->get_uid);
-	
-	my $tag_id = $dbh->last_insert_id(undef, undef, 'vhffs_tag', undef);
-	return get_by_tag_id($main, $tag_id);
-}
+=pod
 
+=head2 _new
+
+	Self constructor, almost private, please use get_by_* methods instead.
+
+=cut
 sub _new {
 	my ($class, $main, $tag_id, $label, $description, $updated, $updater_id, $category_id) = @_;
 		
@@ -76,25 +73,52 @@
 	return $self;
 }
 
-sub get_updater {
-	my ($self) = @_;
-	
-	unless( defined $self->{updater} ) {
-		$self->{updater} = Vhffs::User::get_by_uid($self->{main}, $self->{updater_id});
-	}
-	return $self->{updater};
-}
+=head2 create
 
-sub get_category {
-	my ($self) = @_;
+my $tag = Vhffs::Tag::create($main, $label, $description, $creator, $category, $created)
+
+Create (in database) and return a new object.
+
+=over 4
+
+=item C<$main>: C<Vhffs::Main> instance
+
+=item C<$label>: Tag label.
+
+=item C<$description>: Tag description.
+
+=item C<$creator>: C<Vhffs::User> instance of the user who is creating this tag.
+
+=item C<$category>: C<Vhffs::Tag::Category> instance of the tag category.
+
+=time C<$created>: Unix timestamp.
+
+=back
+
+=cut
+sub create {
+	my ($main, $label, $description, $creator, $category, $created) = @_;
+	$created = time() unless(defined $created);
 	
-	unless( defined $self->{category} ) {
-		$self->{category} = Vhffs::Tag::Category::get_by_category_id($self->{main}, $self->{category_id});
-	}
+	my $dbh = $main->get_db_object();
 	
-	return $self->{category}
+	my $sql = q{INSERT INTO vhffs_tag(label, description, updated, category_id, updater_id) VALUES(?, ?, ?, ?, ?)};
+	my $sth = $dbh->prepare($sql);
+	$sth->execute($label, $description, $created, $category->{category_id}, $creator->get_uid);
+	
+	my $tag_id = $dbh->last_insert_id(undef, undef, 'vhffs_tag', undef);
+	return get_by_tag_id($main, $tag_id);
 }
 
+=cut
+
+=head2 Vhffs::Tag::get_by_tag_id
+
+my $tag = Vhffs::Tag::get_by_tag_id( $main, $tag_id );
+
+Fetches a tag by tag ID.
+
+=cut
 sub get_by_tag_id {
 	my($main, $tag_id) = @_;
 	
@@ -111,6 +135,15 @@
 	return $tag;
 }
 
+=cut
+
+=head2 Vhffs::Tag::get_all
+
+my $tags = Vhffs::Tag::get_all( $main );
+
+Fetches all tags.
+
+=cut
 sub get_all {
 	my ($main) = @_;
 	
@@ -118,6 +151,15 @@
 		FROM vhffs_tag ORDER BY label});
 }
 
+=cut
+
+=head2 Vhffs::Tag::get_by_category_id
+
+my $tags = Vhffs::Tag::get_all( $main, $category_id );
+
+Fetches all tags from a category.
+
+=cut
 sub get_by_category_id {
 	my ($main, $category_id) = @_;
 	
@@ -125,6 +167,23 @@
 		FROM vhffs_tag WHERE category_id = ? ORDER BY label}, $category_id);
 }
 
+=cut
+
+=head2 Vhffs::Tag::get_most_popular_tags
+
+my $tags = Vhffs::Tag::get_most_popular_tags( $main, $visibility );
+
+Fetches popular tags.
+
+=over 4
+
+=item C<$vhffs>: C<Vhffs::Main> instance
+
+=item C<$visibility>: C<Vhffs::Constants> TAG_VISIBILITY_* value.
+
+=back
+
+=cut
 sub get_most_popular_tags {
 	use POSIX;	# ceil
 	
@@ -134,37 +193,52 @@
 	
 	my $dbh = $main->get_db_object();
 	
-	my $sql = 
-q{SELECT MAX(c) AS max_count FROM 
-(SELECT COUNT(*) AS c
-FROM vhffs_object_tag ot
-INNER JOIN vhffs_tag t ON t.tag_id = ot.tag_id
-INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
-WHERE c.visibility <= ?
-GROUP BY t.tag_id) AS counts};
+	my $sql = q{SELECT MAX(c) AS max_count FROM
+		(SELECT COUNT(*) AS c
+		FROM vhffs_object_tag ot
+		INNER JOIN vhffs_tag t ON t.tag_id = ot.tag_id
+		INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
+		WHERE c.visibility <= ?
+		GROUP BY t.tag_id) AS counts};
 	my $sth = $dbh->prepare($sql);
 	return undef unless($sth->execute($visibility));
 	my $max_count = $sth->fetchrow_hashref()->{max_count};
 	
-	$sql = 
-q{SELECT c.tag_category_id AS category_id, c.label AS category_label, c.description AS category_description,
-t.tag_id AS tag_id, t.label AS tag_label, t.description AS tag_description, COUNT(*) AS object_count
-FROM vhffs_tag t
-INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
-INNER JOIN vhffs_object_tag ot ON ot.tag_id = t.tag_id
-WHERE c.visibility <= ?
-GROUP BY t.tag_id, t.label, t.description, c.tag_category_id, c.label, c.description
-ORDER BY object_count DESC
-LIMIT 10};
+	$sql = q{SELECT c.tag_category_id AS category_id, c.label AS category_label, c.description AS category_description,
+		t.tag_id AS tag_id, t.label AS tag_label, t.description AS tag_description, COUNT(*) AS object_count
+		FROM vhffs_tag t
+		INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
+		INNER JOIN vhffs_object_tag ot ON ot.tag_id = t.tag_id
+		WHERE c.visibility <= ?
+		GROUP BY t.tag_id, t.label, t.description, c.tag_category_id, c.label, c.description
+		ORDER BY object_count DESC
+		LIMIT 10};
 	$sth = $main->get_db_object->prepare($sql);
 	$sth->execute($visibility) or return undef;
 	while( (my $t = $sth->fetchrow_hashref() )  ) {
 		$t->{weight} = ceil($t->{object_count} * 10 / $max_count);
 		push @$tags, $t;
 	}
-	return $tags; 
+	return $tags;
 }
 
+=cut
+
+=head2 Vhffs::Tag::get_random_tags
+
+my $tags = Vhffs::Tag::get_random_tags( $main, $visibility );
+
+Fetches ten random tags.
+
+=over 4
+
+=item C<$vhffs>: C<Vhffs::Main> instance
+
+=item C<$visibility>: C<Vhffs::Constants> TAG_VISIBILITY_* value.
+
+=back
+
+=cut
 sub get_random_tags {
 	use POSIX;	# ceil
 	
@@ -174,46 +248,45 @@
 	
 	my $dbh = $main->get_db_object();
 	
-	my $sql = 
-q{SELECT MAX(c) AS max_count FROM 
-(SELECT COUNT(*) AS c
-FROM vhffs_object_tag ot
-INNER JOIN vhffs_tag t ON t.tag_id = ot.tag_id
-INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
-WHERE c.visibility <= ?
-GROUP BY t.tag_id) AS counts};
+	my $sql = q{SELECT MAX(c) AS max_count FROM
+		(SELECT COUNT(*) AS c
+		FROM vhffs_object_tag ot
+		INNER JOIN vhffs_tag t ON t.tag_id = ot.tag_id
+		INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
+		WHERE c.visibility <= ?
+		GROUP BY t.tag_id) AS counts};
 	my $sth = $dbh->prepare($sql);
 	return undef unless($sth->execute($visibility));
 	my $max_count = $sth->fetchrow_hashref()->{max_count};
 	
-	$sql = 
-q{SELECT c.tag_category_id AS category_id, c.label AS category_label, c.description AS category_description,
-t.tag_id AS tag_id, t.label AS tag_label, t.description AS tag_description, COUNT(*) AS object_count
-FROM vhffs_tag t
-INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
-INNER JOIN vhffs_object_tag ot ON ot.tag_id = t.tag_id
-WHERE c.visibility <= ?
-GROUP BY t.tag_id, t.label, t.description, c.tag_category_id, c.label, c.description
-ORDER BY RANDOM()
-LIMIT 10};
+	$sql = q{SELECT c.tag_category_id AS category_id, c.label AS category_label, c.description AS category_description,
+		t.tag_id AS tag_id, t.label AS tag_label, t.description AS tag_description, COUNT(*) AS object_count
+		FROM vhffs_tag t
+		INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
+		INNER JOIN vhffs_object_tag ot ON ot.tag_id = t.tag_id
+		WHERE c.visibility <= ?
+		GROUP BY t.tag_id, t.label, t.description, c.tag_category_id, c.label, c.description
+		ORDER BY RANDOM()
+		LIMIT 10};
 	$sth = $main->get_db_object->prepare($sql);
 	$sth->execute($visibility) or return undef;
 	while( (my $t = $sth->fetchrow_hashref() )  ) {
 		$t->{weight} = ceil($t->{object_count} * 10 / $max_count);
 		push @$tags, $t;
 	}
-	return $tags; 
+	return $tags;
 }
 
+=cut
 
 =head2
 	Vhffs::Tag::_fetch_tags($main, $sql, @params)
 
 Fetches a tag list using C<$sql> and C<@params>.
 C<$sql> is a query having the following format
-   SELECT tag_id, label, description, updated, updater_id, category_id FROM vhffs_tag...
+	SELECT tag_id, label, description, updated, updater_id, category_id FROM vhffs_tag...
+
 =cut
-
 sub _fetch_tags {
 	my ($main, $sql, @params) = @_;
 	
@@ -231,6 +304,56 @@
 	return $tags;
 }
 
+=pod
+=head1 INSTANCE METHODS
+=cut
+
+=pod
+
+=head2 get_updater
+
+my $updater = $tag->get_updater;
+
+Returns a C<Vhffs::User> object of the user who last modified this tag.
+
+=cut
+sub get_updater {
+	my ($self) = @_;
+	
+	unless( defined $self->{updater} ) {
+		$self->{updater} = Vhffs::User::get_by_uid($self->{main}, $self->{updater_id});
+	}
+	return $self->{updater};
+}
+
+=pod
+
+=head2 get_category
+
+my $category = $tag->get_category;
+
+Returns a C<Vhffs::Tag::Category> object of the tag category.
+
+=cut
+sub get_category {
+	my ($self) = @_;
+	
+	unless( defined $self->{category} ) {
+		$self->{category} = Vhffs::Tag::Category::get_by_category_id($self->{main}, $self->{category_id});
+	}
+	
+	return $self->{category}
+}
+
+=pod
+
+=head2 delete
+
+$tag->delete;
+
+Delete a tag.
+
+=cut
 sub delete {
 	my ($self) = @_;
 
@@ -239,6 +362,15 @@
 	return $dbh->do($sql, undef, $self->{tag_id});
 }
 
+=pod
+
+=head2 save
+
+$tag->save;
+
+Commit changes of a tag to the database.
+
+=cut
 sub save {
 	my ($self) = @_;
 	
@@ -252,6 +384,8 @@
 
 package Vhffs::Object;
 
+=pod
+
 =head2 get_tags
 
     my $tags = $o->get_tags($access_level);
@@ -260,7 +394,6 @@
 all tags of the given category for this object ({tag_id, label}).
 
 =cut
-
 sub get_tags {
 	my ($o, $visibility) = @_;
 	
@@ -268,9 +401,9 @@
 	my $tags = [];
 	
 	my $sql = q{SELECT t.tag_id, t.label as tag_label, c.label as cat_label
-			FROM vhffs_tag t INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
-			INNER JOIN vhffs_object_tag ot ON ot.tag_id = t.tag_id
-			WHERE ot.object_id = ? AND visibility <= ? ORDER BY c.label, t.label};
+		FROM vhffs_tag t INNER JOIN vhffs_tag_category c ON c.tag_category_id = t.category_id
+		INNER JOIN vhffs_object_tag ot ON ot.tag_id = t.tag_id
+		WHERE ot.object_id = ? AND visibility <= ? ORDER BY c.label, t.label};
 			
 	my $sth = $dbh->prepare($sql);
 	$sth->execute($o->get_oid(), $visibility) or return undef;
@@ -295,6 +428,23 @@
 	return $tags;
 }
 
+=pod
+
+=head2 add_tag
+
+$object->add_tag( $tag, $updater, $updated );
+
+=over 4
+
+=item C<$tag>: C<Vhffs::Tag> instance
+
+=item C<$updater>: C<Vhffs::User> instance of the user who is adding this tag.
+
+=time C<$updated>: Unix timestamp.
+
+=back
+
+=cut
 sub add_tag {
 	my ($o, $tag, $updater, $updated) = @_;
 	
@@ -308,6 +458,19 @@
 		undef, $o->get_oid(), $tag->{tag_id}, $updated, $updater->get_uid());
 }
 
+=pod
+
+=head2 deleted_tag
+
+$object->delete_tag( $tag );
+
+=over 4
+
+=item C<$tag>: C<Vhffs::Tag> instance
+
+=back
+
+=cut
 sub delete_tag {
 	my ($o, $tag) = @_;