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

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

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

Modified Files:
	Caching.pod 
Log Message:
update docs for caching, inlining all the INCLUDE items (they'll be removed in a second...)




Index: Caching.pod
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract2/doc/Manual/Caching.pod,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** Caching.pod	17 Feb 2004 04:30:11 -0000	1.9
--- Caching.pod	28 Nov 2004 00:38:23 -0000	1.10
***************
*** 30,35 ****
  
  Content caching is still fairly young in OpenInteract, and it's not
! appropriate (or useful) for all purposes. It's best when used on pages
! that contain a lot of data or require a good deal of processing.
  
  =head2 Global Configuration
--- 30,51 ----
  
  Content caching is still fairly young in OpenInteract, and it's not
! appropriate (or useful) for all purposes. It's best when used on
! content that:
! 
! =over 4
! 
! =item *
! 
! doesn't have any side-effects, and 
! 
! =item *
! 
! contain a lot of data and/or
! 
! =item *
! 
! require a good deal of processing.
! 
! =back
  
  =head2 Global Configuration
***************
*** 46,51 ****
  =item *
  
! C<cache.cleanup>: If true we delete and recreate the cache
! directory every time the server starts up. This is recommended.
  
  =item *
--- 62,68 ----
  =item *
  
! C<cache.cleanup>: If true we delete and recreate the cache directory
! every time the server starts up. This is recommended unless you're
! sure what's being cached and for how long.
  
  =item *
***************
*** 61,67 ****
  =item *
  
! C<cache.default_expire>: number of seconds used for the
! cached content expiration. You can override this on a case-by-case
! basis.
  
  =item *
--- 78,83 ----
  =item *
  
! C<cache.default_expire>: number of seconds used for the cached content
! expiration. You can override this on a case-by-case basis.
  
  =item *
***************
*** 83,87 ****
  two. The first (or zeroth) is that you must subclass
  L<OpenInteract2::Action|OpenInteract2::Action>. You almost certainly
! already do this, so it's not much a requirement.
  
  The real requirement: caching must be configured in your action using
--- 99,103 ----
  two. The first (or zeroth) is that you must subclass
  L<OpenInteract2::Action|OpenInteract2::Action>. You almost certainly
! already do this, so it's not much of a requirement.
  
  The real requirement: caching must be configured in your action using
***************
*** 101,114 ****
  action. Here's an example:
  
! [% INCLUDE examples/caching_parameter_single | indent(4) %]
  
  Here we've told the caching system to associate content from the
  'latest' task with the variable 'num_items'. So when we get a request:
  
! [% INCLUDE examples/caching_request_simple | indent(4) %]
! 
  We'll create a unique cache key like the following:
  
! [% INCLUDE examples/caching_key_simple | indent(4) %]
  
  and use this to get and set the cached content. (The actual key may
--- 117,131 ----
  action. Here's an example:
  
!  [news cache_param]
!  latest     = num_items
  
  Here we've told the caching system to associate content from the
  'latest' task with the variable 'num_items'. So when we get a request:
  
!  /news/latest/?num_items=10
!  
  We'll create a unique cache key like the following:
  
!  news;latest;num_items=10
  
  and use this to get and set the cached content. (The actual key may
***************
*** 119,127 ****
  news items are retrieved:
  
! [% INCLUDE examples/caching_parameter_double | indent(4) %]
  
  And a corresponding key might look like:
  
! [% INCLUDE examples/caching_key_double | indent(4) %]
  
  Now the cached content depends on 'num_items' and 'country'. All of
--- 136,146 ----
  news items are retrieved:
  
!  [news cache_param]
!  latest     = num_items
!  latest     = country
  
  And a corresponding key might look like:
  
!  news;latest;country=USA;num_items=10
  
  Now the cached content depends on 'num_items' and 'country'. All of
***************
*** 129,133 ****
  remain totally separate from one another:
  
! [% INCLUDE examples/caching_request_double_permute | indent(4) %]
  
  =head2 Controlling Cache Expirations
--- 148,156 ----
  remain totally separate from one another:
  
!  /news/latest/?num_items=10
!  /news/latest/?num_items=15
!  /news/latest/?num_items=10&country=USA
!  /news/latest/?num_items=10&country=France
!  /news/latest/?num_items=15&country=USA
  
  =head2 Controlling Cache Expirations
***************
*** 136,145 ****
  C<cache_expire> section of the action:
  
! [% INCLUDE examples/caching_expire_config | indent(4) %]
  
! The values are in seconds. Here we've said the content generated by
! the 'latest' and 'home' tasks should be cached for 10 minutes, and the
! 'display' task for one hour. You can manually delete cache entries
! using the C<clear_cache()> action method.
  
  Notice that we included an extra task here, 'home'. It has no
--- 159,173 ----
  C<cache_expire> section of the action:
  
!  [news cache_expire]
!  latest     = 600
!  display    = 1h
!  home       = 10m
  
! Unadorned values, such as 'latest' are in seconds. You can also use a
! character after the number to indicate minutes (m), hours (h) or days
! (d). Here we've said the content generated by the 'latest' and 'home'
! tasks should be cached for 10 minutes, and the 'display' task for one
! hour. You can manually delete cache entries using the C<clear_cache()>
! action method.
  
  Notice that we included an extra task here, 'home'. It has no
***************
*** 147,152 ****
  C<cache_param>.
  
! If you don't list your task in C<cache_expire> content generated by
! it will not be cached.
  
  =head2 Specifying Cache Parameters
--- 175,190 ----
  C<cache_param>.
  
! If you don't list your task in C<cache_expire> content generated by it
! will not be cached unless tell OI you want the same value to be
! applied to all tasks. For this you just assign a single value to
! 'cache_expire':
! 
!  [news]
!  class = OpenInteract2::Action::News
!  ...
!  cache_expire = 10m
! 
! This tells OI to use a cache expiration of 10 minutes for all tasks in
! the 'news' action.
  
  =head2 Specifying Cache Parameters
***************
*** 165,170 ****
  parameters. Normally you'll depend on GET/POST parameters passed from
  the user. We already have access to those through the
! L<OpenInteract2::Request|OpenInteract2::Request> object, so we go
! ahead and use them if necessary.
  
  Additionally there are a couple of implicit parameters you can use to
--- 203,208 ----
  parameters. Normally you'll depend on GET/POST parameters passed from
  the user. We already have access to those through the
! L<OpenInteract2::Request> object, so we go ahead and use them if
! necessary.
  
  Additionally there are a couple of implicit parameters you can use to
***************
*** 217,221 ****
  Ah, but what happens if someone passes in a news object directly?
  
! [% INCLUDE examples/caching_perl_call_needing_init | indent(4) %]
  
  Now our automatic parameter discovery won't work. This is where the
--- 255,267 ----
  Ah, but what happens if someone passes in a news object directly?
  
!  sub _calling_display_task {
!      my ( $self ) = @_;
!      my $fakenews = $self->_create_news_object( type => 'onion' );
!      my $display_action = CTX->lookup_action( 'news' );
!      return $display_action->execute({
!          task => 'display',
!          news => $fakenews
!      });
!  }
  
  Now our automatic parameter discovery won't work. This is where the
***************
*** 223,227 ****
  can have:
  
! [% INCLUDE examples/caching_perl_params_init | indent(4) %]
  
  And everything will work!
--- 269,280 ----
  can have:
  
!  sub initialize_cache_params {
!      my ( $self ) = @_;
!      my %params = ();
!      if ( my $news = $self->param( 'news' ) ) {
!          $params{news_id} = $news->id;
!      }
!      return \%params;
!  }
  
  And everything will work!
***************
*** 240,244 ****
  an example:
  
! [% INCLUDE examples/caching_clear_cache_usage | indent(4) %]    
  
  So when the 'list' method is called after a successful C<update()> on
--- 293,320 ----
  an example:
  
!  sub update {
!      my ( $self ) = @_;
!      my $request = CTX->request;
!      my $thingy_id = $self->param( 'thingy_id' )
!                      || $request->param( 'thingy_id' );
!      my $thingy = eval {
!          CTX->lookup_object( 'thingy' )->fetch( $thingy_id );
!      };
!      if ( $@ ) { ... }
!      $thingy->{foo} = $request->param( 'foo' );
!      eval { $thingy->save };
!      if ( $@ ) {
!          $self->param_add( error_msg => "Cannot save thingy: $@" );
!          return $self->execute({
!              task   => 'display_form',
!              thingy => $thingy
!          });
!      }
!      else {
!          $self->clear_cache();
!          $self->param_add({ status_msg => "Thingy updated ok" });
!          return $self->execute({ task => 'list' });
!      }
!  }
  
  So when the 'list' method is called after a successful C<update()> on
***************
*** 258,262 ****
  following will return true:
  
! [% INCLUDE examples/caching_admin_check | indent(4) %]
  
  =head1 TEMPLATE CACHING
--- 334,338 ----
  following will return true:
  
!  my $is_admin = CTX->request->auth_is_admin;
  
  =head1 TEMPLATE CACHING
***************
*** 295,305 ****
  If you set this to 0 then caching will be disabled. This is useful
  when you're doing debugging on your site, but it can make things
! noticably slower if you have lots of requests, where 'lots' means
! 'more than a handful'.
! 
! =item *
! 
! C<dir.cache_tt>: The directory where we store the compiled templates
! in the filesystem. This is normally C<$WEBSITE_DIR/cache/tt>
  
  =item *
--- 371,376 ----
  If you set this to 0 then caching will be disabled. This is useful
  when you're doing debugging on your site, but it can make things
! noticably slower if you have lots of requests. (Note: 'lots' means
! 'more than a handful'.)
  
  =item *
***************
*** 311,317 ****
  =item *
  
! C<content_generator.TT.compile_cleanup>: If set to a true value, we
! clean out the template compile directory when the Apache server starts
! up.
  
  =item *
--- 382,388 ----
  =item *
  
! C<content_generator.TT.compile_dir>: The directory where we store the
! compiled templates in the filesystem. This is normally C<cache/tt>,
! which gets resolved at runtime to C<$WEBSITE_DIR/cache/tt>.
  
  =item *
***************
*** 320,323 ****
--- 391,400 ----
  template is compiled to the filesystem.
  
+ =item *
+ 
+ C<content_generator.TT.compile_cleanup>: If set to a true value, we
+ clean out the template compile directory when the Apache server starts
+ up.
+ 
  =back
  
***************
*** 325,329 ****
  the C<OI2.TEMPLATE> logging key to 'DEBUG':
  
! [% INCLUDE examples/caching_template_logging | indent(4) %]
  
  Be warned: this produces a prodigious amount of messages.
--- 402,410 ----
  the C<OI2.TEMPLATE> logging key to 'DEBUG':
  
!  Old value:
!   log4perl.logger.OI2.TEMPLATE   = WARN
!  
!  New value:
!   log4perl.logger.OI2.TEMPLATE   = DEBUG
  
  Be warned: this produces a prodigious amount of messages.