[Openinteract-commits] CVS: OpenInteract2/extra_packages/delicious_tags/doc delicious_tags.pod,NONE,1.1

[Chris W. <la...@us...>]

Update of /cvsroot/openinteract/OpenInteract2/extra_packages/delicious_tags/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18386/delicious_tags/doc

Added Files:
	delicious_tags.pod 
Log Message:
intial import of delicious_tags package

--- NEW FILE: delicious_tags.pod ---
=head1 NAME

delicious_tags - Tag generic objects

=head1 SYNOPSIS

 # Mark an action ('myaction') with the delicious observer; this means
 # it will attach tags found in the request variable 'delicious_tags'
 # to the object found in the action parameter 'object' or 'c_object'
 # (this is done automatically for you if you're using the Common
 # actions)
 
 # in $WEBSITE_DIR/conf/observer.ini
 
 [observer]
 delicious = OpenInteract2::Observer::DeliciousTag
 
 [map]
 delicious = myaction

 
 # Mark an object ('myobject') as taggable with delicious tags; this
 # will add a few methods to the base object
 
 # in $PKG_DIR/conf/spops_myobject.ini
 
 [myobject]
 class = OpenInteract2::Foo
 ...
 is_taggable = yes

 # Once marked as taggable you can execute methods:
 
 # Find tags attached to object
 
 my $tags = $myobject->fetch_my_tags;
 print "Object tagged with: ", join( ', ', @{ $tags } );
 
 my $tags_with_count = $myobject->fetch_my_tags_with_count;
 print "Object tagged with:\n";
 foreach my $tag_and_count( @{ $tags_with_count } ) {
     print "  - $tag_and_count->[0]: $tag_and_count->[1]\n";
 }
  
 # Find other objects with any of the same tags as this one
 my $related_info = $myobject->fetch_related_object_info;

 # Find other objects with the tag 'sometag'
 my $related_info = $myobject->fetch_related_object_info( 'sometag' );

 # Find other objects with the tags 'sometag' or 'someothertag'
 my $related_info = $myobject->fetch_related_object_info( 'sometag', 'someothertag' );
 
 print "Object related to:\n";
 foreach my $info ( @{ $related_info } ) {
     my $url = OpenInteract2::URL->create( $info->{url}, {}, 1 );
     print "  - $info->{title} ($info->{type})\n",
           "    Tag: $info->{tag}; URL: $url\n"; 
 }


 # These are class methods we cleverly disguise as being called from
 # an object without state because it's less typing...
 
 my $tagger = OpenInteract2::DeliciousTag->new;
 
 # Fetch available tags
 
 my $tags = $tagger->fetch_all_tags;
 print "Available tags: ", join( ', ', @{ $tags } );
 
 # Fetch available tags with the number of objects in each
 my $tags_and_counts = $tagger->fetch_all_tags_with_count;
 foreach my $tag_and_count( @{ $tags_with_count } ) {
     print "$tag_and_count->[0]: $tag_and_count->[1]\n";
 }

 # You can also fetch as an arrayref of hashrefs
 my $tags_and_counts = $tagger->fetch_all_tags_with_count( {} );
 foreach my $tag_and_count( @{ $tags_with_count } ) {
     print "$tag_and_count->{tag}: $tag_and_count->{count}\n";
 }

 # Fetch a count by tag
 my $count = $tagger->fetch_count( 'sometag' );
 print "Number of objects with tag 'sometag': $count\n";
 
 # Find related tags -- this will find all other tags attached to
 # objects attached to this tag
 my $tags = $tagger->fetch_related_tags( 'sometag' );
 print "Other tags related to 'sometag': ", join( ', ', @{ $tags } );
 
 # Similarly, find tag and count for related tags
 print "Also related to 'sometag':\n";
 my $tags = $tagger->fetch_related_tags_with_count( 'sometag' );
 foreach my $tag_and_count( @{ $tags_with_count } ) {
     print "  - $tag_and_count->{tag}: $tag_and_count->{count}\n";
 }

=head1 DESCRIPTION

This module allows you to add arbitrary textual tags to objects. It is
a simple copy of the ideas at L<http://del.icio.us/>, a social
bookmarking system.

An earlier version of this same idea was available in the OpenInteract
1.x package C<object_link> but it was much heavier and less
flexible. The beauty of these tags is that you can create them
whenever you want -- there's no separate table of 'tags' you need to
maintain -- and they're just simple text. There's no weighting or
anything like that.

=head1 OBJECTS

L<delicious_tag>

=head1 ACTIONS

No actions defined in this package.

=head1 RULESETS

No rulesets defined in this package.

=head1 BUGS 

None known.

=head1 AUTHORS

Chris Winters E<lt>ch...@cw...E<gt>