[Openinteract-commits] CVS: OpenInteract2/extra_packages/delicious_tags/doc delicious_tags.pod,1.4,1.5

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

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

Modified Files:
	delicious_tags.pod 
Log Message:
docs, docs and more docs



Index: delicious_tags.pod
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract2/extra_packages/delicious_tags/doc/delicious_tags.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** delicious_tags.pod	25 Nov 2004 13:50:32 -0000	1.4
--- delicious_tags.pod	27 Nov 2004 17:10:55 -0000	1.5
***************
*** 98,103 ****
       print "  - $tag_and_count->{tag}: $tag_and_count->{count}\n";
   }
! 
! 
   # In your template you can add a box to display the current item's
   # tags:
--- 98,102 ----
       print "  - $tag_and_count->{tag}: $tag_and_count->{count}\n";
   }
!  
   # In your template you can add a box to display the current item's
   # tags:
***************
*** 112,120 ****
  
  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
--- 111,227 ----
  
  An earlier version of this same idea was available in the OpenInteract
! 1.x package C<object_link> but it was much heavier and much 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
! any other features, just tags.
! 
! =head2 Tag interaction overview
! 
! The class L<OpenInteract2::DeliciousTaggableObject> is used for
! getting data into and out of the system. If you mark your SPOPS object with:
! 
!  is_taggable = yes
! 
! then its methods will be available from every object in that
! class. Otherwise you need to use the methods prefixed with 'c_'
! (class).
! 
! =head2 Getting tags into the system
! 
! The best way is to use the action observer
! L<OpenInteract2::Observer::AddDeliciousTags>. Once it's configured as
! discussed in L<SYNOPSIS> it will sit back and watch all 'post add' and
! 'post update' action observations. When it catches one it will look
! for the object added or updated and its asssociated tag data; if both
! are found the observer will tag that object.
! 
! You make the object available in the action parameter 'object' or
! 'c_object'. And you make your object's tags available via either the
! request parameter 'tags' (typically coming in through GET/POST) or the
! action parameter 'tags'.
! 
! While you'll typically use the request parameter to input the tags so
! the user can edit the tags with the object, you might use some sort of
! textual analysis program to pull tags out of the object's content. To
! accomplish this in your action you might have:
! 
!  sub update {
!      my ( $self ) = @_;
!      ...
!      eval { $my_object->save() };
!      if ( $@ ) { oi_error ... }
! 
!      # if save ok...
!      my @tags = $my_object->analyze_content();
! 
!      # ...save tags as arrayref...
!      $self->param( 'tags' => \@tags );
!  
!      # ...or as space-separated string
!      $self->param( 'tag' => join( ' ', @tags ) );
!  
!      # Store tags...
! 
!      # ...if class for '$my_object' marked with 'is_taggable = yes':
!      $my_object->add_tags( @tags );
!  
!      # ...if not so marked
!      OpenInteract2::DeliciousTaggableObject::add_tags( $my_object, @tags );
! 
!      # ...or if $my_object is not an SPOPS object
!      OpenInteract2::DeliciousTaggableObject->c_add_tags(
!              'My Type',
!              $my_object->id,
!              '/my_object/display/?id=" . $my_object->id,
!              $my_object->name . ': ' . $my_object->description,
!              @tags
!      );
!      ...
! 
! =head2 Getting tags out of the system
! 
! You can grab all tags with:
! 
!  my $tag_class = CTX->lookup_object( 'delicious_tag' );
!  
!  my $all_tags = $tag_class->fetch_all_tags;
!  print "All tags in system: ", join( ', ', @{ $all_tags } );
!  
! You can also grab the corresponding counts with:
! 
!  my $all_tags_and_counts = $tag_class->fetch_all_tags_with_count;
!  print "All tags in system:\n";
!  foreach my $tag_and_count ( @{ $all_tags_and_counts } ) {
!      print "$tag_and_count->[0]: $tag_and_count->[1]\n";
!  }
! 
! If you prefer to use a hashref for each returned tag + count:
! 
!  my $all_tags_and_counts = $tag_class->fetch_all_tags_with_count( {} );
!  print "All tags in system:\n";
!  foreach my $tag_and_count ( @{ $all_tags_and_counts } ) {
!      print "$tag_and_count->{tag}: $tag_and_count->{count}\n";
!  }
! 
! =head2 Getting tagged objects out of the system
! 
! You can get a description of all objects with a particular tag:
! 
!  my $tag_class = CTX->lookup_object( 'delicious_tag' );
! 
!  # Find all the items tagged with 'linux'
!  my $items = $tag_class->fetch_tag_objects( 'linux' );
!  foreach my $item ( @{ $items } ) {
!     print "Item type: $item->{object_type} with ID $item->{object_id}\n",
!           "     Name: $item->{name}\n",
!           "      URL: $item->{url}\n";
!  }
! 
!  # Find all the items tagged with 'linux' or 'win32'
!  my $items = $tag_class->fetch_tag_objects( [ 'linux', 'win32' ] );
!  
!  # Find all the items tagged with 'linux' or 'win32' that aren't of the 'blog' type
!  my $items = $tag_class->fetch_tag_objects( [ 'linux', 'win32' ], 'blog' );
  
  =head1 OBJECTS
***************
*** 122,132 ****
  L<delicious_tag>
  
  =head1 ACTIONS
  
  B<related_tags_box>
  
! Box to display the tags (and the number of other objects tagged by
! them) related to a particular object. You need to pass in an 'object'
! or 'c_object' for it to work:
  
   [% OI.box_add( 'related_tags_box', object = news ) %]
--- 229,250 ----
  L<delicious_tag>
  
+ See L<OpenInteract2::DeliciousTag> for information on the additional methods.
+ 
  =head1 ACTIONS
  
+ B<all_tags_box>
+ 
+ Box to display all tags with the count for each.
+ 
+ Example in template:
+ 
+  [% OI.box_add( 'all_tags_box' ) %]
+ 
  B<related_tags_box>
  
! Box to display the tags and count related to a particular object. You
! need to pass in an 'object' or 'c_object' for it to work:
! 
! Example in template:
  
   [% OI.box_add( 'related_tags_box', object = news ) %]
***************
*** 135,139 ****
  
  Component to display items given a particular tag. You can invoke this
! anywhere:
  
   <p>
--- 253,257 ----
  
  Component to display items given a particular tag. You can invoke this
! anywhere, such as:
  
   <p>
***************
*** 143,148 ****
  B<tags>
  
! Currently has single task 'show_tagged_items' which displays a
! full-page version of the 'tagged_items' action.
  
  =head1 OBSERVERS
--- 261,266 ----
  B<tags>
  
! Currently has single URL-accessible task 'show_tagged_items' which
! displays a full-page version of the 'tagged_items' action.
  
  =head1 OBSERVERS