[Openinteract-commits] CVS: OpenInteract2/lib/OpenInteract2 Observer.pm,1.1,1.2

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

Update of /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17401

Modified Files:
	Observer.pm 
Log Message:
update docs with examples and more explanation of what an observer is




Index: Observer.pm
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2/Observer.pm,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** Observer.pm	27 Sep 2004 12:53:27 -0000	1.1
--- Observer.pm	28 Nov 2004 04:07:52 -0000	1.2
***************
*** 213,218 ****
  =head1 SYNOPSIS
  
!  # Declare a filter 'allcaps' in the server-wide file for registering
!  # observers, referring to a class somewhere in @INC
   #
   # File: $WEBSITE_DIR/conf/observer.ini
--- 213,218 ----
  =head1 SYNOPSIS
  
!  # Declare an observer 'allcaps' in the server-wide file for
!  # registering observers, referring to a class somewhere in @INC
   #
   # File: $WEBSITE_DIR/conf/observer.ini
***************
*** 221,225 ****
   allcaps = OpenInteract2::Filter::AllCaps
   
!  # You can also declare it in your package's package.conf file
   # File: pkg/mypackage-2.00/package.conf
   
--- 221,231 ----
   allcaps = OpenInteract2::Filter::AllCaps
   
!  # Associate the filter with an action in the same file
!  
!  [map]
!  allcaps = news
!  
!  # You can also declare the observer in your package's package.conf
!  # file; it's mapped the same no matter where it's declared
   # File: pkg/mypackage-2.00/package.conf
   
***************
*** 229,237 ****
   observer       allcaps   OpenInteract2::Filter::AllCaps
   
-  # Associate the filter with an action in the same file
-  
-  [map]
-  allcaps = news
-  
   # Create the filter -- see OpenInteract2::Filter::AllCaps shipped
   # with the distribution:
--- 235,238 ----
***************
*** 256,259 ****
--- 257,331 ----
  them to action objects or action classes.
  
+ Observers are registered at server startup and sit around waiting for
+ actions to post events. When an action posts an event the data is
+ passed around to all the observers watching that action. The observer
+ can react to the data if it wants or it can pass.
+ 
+ Most observers react to one or two types of events. For instance, if
+ you're using the C<delicious_tags> package there's an observer that
+ looks like this:
+ 
+  sub update {
+      my ( $class, $action, $type ) = @_;
+      return unless ( $type =~ /^post (add|update)$/ );
+      # ... tag the object ...
+  }
+ 
+ This observer only reacts to 'post add' and 'post update'
+ observations and ignores all others.
+ 
+ =head2 Observation Types
+ 
+ Actions can independently declare their own observation
+ types. However, there are a few built-in to OpenInteract classes:
+ 
+ =over 4
+ 
+ =item *
+ 
+ B<filter>: Issued after an action has generated its content but before
+ that content is cached and returned.
+ 
+ Signature: C<$action>, C<'filter'>, C<\$content>
+ 
+ =item *
+ 
+ B<cache hit>: Issued after an action has successfully loaded data from
+ the cache but before that content is returned.
+ 
+ Signature: C<$action>, C<'cache hit'>, C<\$content>
+ 
+ =item *
+ 
+ B<pre add>/B<post add>: Issued before/after an object is added by the
+ action to long-term storage. Currently used by
+ L<OpenInteract2::Action::CommonAdd>, but you can use it as well.
+ 
+ Signature: C<$action>, C<'pre add'>, C<$object>, C<\%save_options>
+ 
+ Signature: C<$action>, C<'post add'>, C<$object>
+ 
+ =item *
+ 
+ B<pre update>/B<post update>: Issued before/after an object is updated
+ by the action to long-term storage. Currently used by
+ L<OpenInteract2::Action::CommonUpdate>, but you can use it as well.
+ 
+ Signature: C<$action>, C<'pre update'>, C<$object>, C<\%old_data>, C<\%save_options>
+ 
+ Signature: C<$action>, C<'post update'>, C<$object>, C<\%old_data>
+ 
+ =item *
+ 
+ B<pre remove>/B<post remove>: Issued before/after an object is remove
+ by the action from long-term storage. Currently used by
+ L<OpenInteract2::Action::CommonRemove>, but you can use it as well.
+ 
+ Signature: C<$action>, C<'pre remove'>, C<$object>
+ 
+ Signature: C<$action>, C<'post remove'>, C<$object>
+ 
+ =back
+ 
  =head1 METHODS
  
***************
*** 304,332 ****
  Returns: nothing
  
! =head2 Configuring
  
! You can also register a particular subroutine or object instance
  
! The general configuration to declare a observer is:
  
!  [observer filtername]
   observation-type = value
  
! The observation types are 'class', 'object' and 'sub' (see
  L<Class::Observable|Class::Observable> for what these mean and how
  they are setup), so you could have:
  
!  [observer foo_obj]
   object = OpenInteract2::FooFilter
   
!  [observer foo_sub]
   sub    = OpenInteract2::FooFilter::other_sub
-  
-  [observer action]
-  foo_obj = news
-  foo_sub = page
  
! Most of the time you will use the class shortcut since it is the
! easiest.
  
  =head1 SEE ALSO
--- 376,453 ----
  Returns: nothing
  
! =head1 CONFIGURATION
  
! Configuration is split into two parts: declaring the observer and
! mapping the observer to one or more actions for it to watch.
  
! Both parts are typically done in the
! C<$WEBSITE_DIR/conf/observer.ini>, although you can also do the
! observer declaration from a package.
  
! =head2 Configuration: Declaring the Observer
! 
! Most of the time you'll register an observer name with a class. The
! following registers two observers to classes under the names 'wiki'
! and 'delicious_tag':
! 
!  [observer]
!  wiki          = OpenInteract2::Observer::Wikify
!  delicious_tag = OpenInteract2::Observer::AddDeliciousTags
! 
! This standard usage is actually a shortcut for:
! 
!  [observer wiki]
!  class = OpenInteract2::Observer::Wikify
!  
!  [observer delicious_tag]
!  class = OpenInteract2::Observer::AddDeliciousTags
! 
! Or more generically:
! 
!  [observer observer-name]
   observation-type = value
  
! In addition to assigning class observers register a particular
! subroutine or object instance. The three observation types are
! 'class', 'object' and 'sub' (see
  L<Class::Observable|Class::Observable> for what these mean and how
  they are setup), so you could have:
  
!  [observer myobject]
   object = OpenInteract2::FooFilter
   
!  [observer myroutine]
   sub    = OpenInteract2::FooFilter::other_sub
  
! Using the object is fairly rare and you should probably use the class observer for
! its simplicity.
! 
! =head2 Configuration: Mapping the Observer to an Action
! 
! Mapping an observer to an action is exclusively done in
! C<$WEBSITE_DIR/conf/observer.ini>. Under the 'map' section you assign
! an observer to one or more actions. Here as assign the observer 'wiki'
! to 'news' and 'page' and 'delicious_tag' to 'news':
! 
!  [map]
!  wiki = news
!  wiki = page
!  delicious_tag = news
! 
! Note that the mapping is ignorant of:
! 
! =over 4
! 
! =item *
! 
! B<Observer type>: The mapping doesn't care if 'wiki' is a class,
! object or subroutine.
! 
! =item *
! 
! B<Observer declaration>: The mapping also doesn't care where 'wiki'
! was declared.
! 
! =back
  
  =head1 SEE ALSO