[Openinteract-commits] CVS: OpenInteract2/doc/Manual Caching.pod,1.10,1.11

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

Update of /cvsroot/openinteract/OpenInteract2/doc/Manual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv13419

Modified Files:
	Caching.pod 
Log Message:
add notes about 'cache hit' observation; move the admin caching section up near the side-effects one




Index: Caching.pod
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract2/doc/Manual/Caching.pod,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** Caching.pod	28 Nov 2004 00:38:23 -0000	1.10
--- Caching.pod	28 Nov 2004 00:58:00 -0000	1.11
***************
*** 49,52 ****
--- 49,100 ----
  =back
  
+ =head2 Avoiding Side-Effects
+ 
+ First, you have to ensure that the action producing the content you're
+ caching has no side-effects. Otherwise the first invocation will work
+ properly the every subsequent one will fail because it does not
+ produce the side-effects you're looking for.
+ 
+ Here are some examples of what we mean by side-effects:
+ 
+ =over 4
+ 
+ =item *
+ 
+ The action actually modifies an object. (Hopefully this is obvious!)
+ Because the action never gets run the object will never be modified.
+ 
+ =item *
+ 
+ The action increments a counter in a database every time an object is
+ viewed. Again, the action will never be run so the counter won't be
+ incremented.
+ 
+ =item *
+ 
+ The template used by the action adds a box to the page. Since the
+ action isn't run the template isn't invoked and the command to add the
+ box won't be executed.
+ 
+ =back
+ 
+ These are poor candidates for caching. You might still be able to
+ cache the content with creative action observer uses, but you should
+ tread cautiously and understand what you're doing.
+ 
+ =head2 Admins: Another Time Not to Cache
+ 
+ If you're an admin user you frequently see functionality that normal
+ users do not see: B<Edit> or B<Remove> links next to an object, etc.
+ You do not want to cache this content, since users shouldn't see this
+ information. (Normal users modifying the object shouldn't be an issue,
+ since security should take care of it.)
+ 
+ As a result, any user defined as an administrator will not view or save
+ cached content. "Defined as an administrator" means that a call to the
+ following will return true:
+ 
+  my $is_admin = CTX->request->auth_is_admin;
+ 
  =head2 Global Configuration
  
***************
*** 322,338 ****
  the content will be regenerated anew.
  
! =head2 When Not to Cache
  
! If you're an admin user you frequently see functionality that normal
! users do not see: B<Edit> or B<Remove> links next to an object, etc.
! You do not want to cache this content, since users shouldn't see this
! information. (Normal users modifying the object shouldn't be an issue,
! since security should take care of it.)
  
! As a result, any user defined as an administrator will not view or save
! cached content. "Defined as an administrator" means that a call to the
! following will return true:
  
!  my $is_admin = CTX->request->auth_is_admin;
  
  =head1 TEMPLATE CACHING
--- 370,392 ----
  the content will be regenerated anew.
  
! =head2 Filtering Cached Content
  
! As mentioned in L<OpenInteract2::Action> under 'Built-In
! Observations', the base action class filters content B<before> it's
! cached. So when you pull up cached content you're seeing the effects
! of those filters.
  
! Action observers also have an opportunity to modify or react to cached
! content. Whenever L<OpenInteract2::Action> gets a cache hit it issues
! an observation 'cache hit'. Your observer can listen for this and
! modify the content (since it's passed as a scalar reference) as
! necessary:
  
!  # Translate all upper-case "PERL" references to "Perl"
!  sub update {
!      my ( $class, $action, $type, $content ) = @_;
!      return unless ( $type eq 'cache hit' );
!      $$content =~ s/PERL/Perl/g;
!  }
  
  =head1 TEMPLATE CACHING