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
|
