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

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

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

Modified Files:
	Management.pod 
Log Message:
inline management examples

Index: Management.pod
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract2/doc/Manual/Management.pod,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** Management.pod	13 Jun 2004 18:18:48 -0000	1.9
--- Management.pod	30 Nov 2004 01:26:32 -0000	1.10
***************
*** 29,40 ****
  tasks this was fine, but it prevented B<any> sort of web-based
  management without simply cobbling together strings to run using
! C<system>.

  =item *

! Its size also meant that it was difficult to refactor. And it was
! fairly difficult to add new tasks without doing lots of copy-and-paste
! and knowing where certain tasks (parameter parsing, etc.) were
! performed.

  =item *
--- 29,40 ----
  tasks this was fine, but it prevented B<any> sort of web-based
  management without simply cobbling together strings to run using
! C<system>. Yuck.

  =item *

! Its size (4100+ lines) also meant that it was difficult to
! refactor. And it was fairly difficult to add new tasks without doing
! lots of copy-and-paste and knowing where certain tasks (parameter
! parsing, etc.) were performed.

  =item *
***************
*** 47,51 ****
  =back

! =head2 Turnabout is fair play

  The architecture of the management framework in OI2 is exactly the
--- 47,51 ----
  =back

! =head2 Turn weaknesses into strengths

  The architecture of the management framework in OI2 is exactly the
***************
*** 101,105 ****
  =item *

! And finally, B<running the task>!

  =back
--- 101,105 ----
  =item *

! And finally, B<Running the task>!

  =back
***************
*** 188,192 ****
  can be used as necessary:

! [% INCLUDE examples/mgt_source_dir_param | indent 2 %]

  It specifies that the parameter is required and gives a generic
--- 188,198 ----
  can be used as necessary:

!  sub get_parameters {
!      my ( $self ) = @_;
!      return {
!          source_dir => $self->_get_source_dir_param(),
!          ...
!      };
! }

  It specifies that the parameter is required and gives a generic
***************
*** 253,262 ****
  C<website_dir> from L<OpenInteract2::Manage|OpenInteract2::Manage>:

! [% INCLUDE examples/mgt_parent_validate_website_dir | linenum 2 %]

  Easy enough. Now, say we want to validate a different parameter
  ourselves:

! [% INCLUDE examples/mgt_validate_game_choice | linenum 2 %]

  This ensures that the parameter value for 'game_choice' (a) exists and
--- 259,299 ----
  C<website_dir> from L<OpenInteract2::Manage|OpenInteract2::Manage>:

!  sub get_parameters {
!      my ( $self ) = @_;
!      return {
!          website_dir => {
!              description => 'a directory',
!              is_required => 'yes',
!          },
!      };
!  }
!  
!  # we're not validating anything ourselves -- no 'validate_param'
!  # subroutine defined

  Easy enough. Now, say we want to validate a different parameter
  ourselves:

!  sub get_parameters {
!      my ( $self ) = @_;
!      return {
!          game_choice => {
!              description => 'Your choice in the game',
!              is_required => 'yes',
!          },
!          ...
!      };
!  }
!   
!  sub validate_param {
!      my ( $self, $param_name, $param_value ) = @_;
!      if ( $param_name eq 'game_choice' ) {
!          unless ( $param_value =~ /^(rock|scissors|paper)$/i ) {
!              return "Value must be 'rock', 'scissors' or 'paper'";
!          }
!      }
!      return $self->SUPER::validate_param( $param_name, $param_value );
!  }
! 

  This ensures that the parameter value for 'game_choice' (a) exists and
***************
*** 274,282 ****
  a little confused if you use C<_add_status_head()>.

! B<_add_status( ( \%status, \%status, ...) )>

  Adds status message C<\%status> to those tracked by the object.

! B<_add_status_head( ( \%status, \%status, ... ) )>

  Adds status messages to the head of the list of status messages. This
--- 311,319 ----
  a little confused if you use C<_add_status_head()>.

! B<_add_status( \%status, \%status, ... )>

  Adds status message C<\%status> to those tracked by the object.

! B<_add_status_head( \%status, \%status, ... )>

  Adds status messages to the head of the list of status messages. This
***************
*** 307,311 ****
  you post. Notifying observers is simple:

! [% INCLUDE examples/mgt_notify_observers | indent 2 %]

  What goes into C<@extra_info> depends on the C<$type>. The two types
--- 344,348 ----
  you post. Notifying observers is simple:

!  $self->notify_observers( $type, @extra_info )

  What goes into C<@extra_info> depends on the C<$type>. The two types
***************
*** 322,326 ****
  differentiate -- let the user know it will take a while, etc.

! [% INCLUDE examples/mgt_run_task_notify_observers | indent 2 %]

  This is a contrived example -- if your task is very simple (like this)
--- 359,377 ----
  differentiate -- let the user know it will take a while, etc.

!  sub run_task {
!      my ( $self ) = @_;
!      $self->_do_some_simple( 'thing' );
!      $self->notify_observers( progress => 'Simple thing complete' );
!      $self->_do_some_other( @stuff );
!      $self->notify_observers( progress => 'Other stuff complete' );
!      $self->notify_observers( progress => 'Preparing complex task',
!                               { long => 'yes' } );
!      $self->_do_complex_task;
!      $self->notify_observers( progress => 'Complex task complete' );
!  
!      # This fires an implicit observation of type 'status'
!      $self->_add_status({ is_ok   => 'yes',
!                           message => 'Foobar task ok' });
!  }

  This is a contrived example -- if your task is very simple (like this)
***************
*** 337,345 ****
  'hello_world' in the website directory:

! [% INCLUDE examples/mgt_sample_task | linenum %]

  And here is how you would run your task:

! [% INCLUDE examples/mgt_sample_task_run_prog | indent 2 %]

  Since all management tasks are auto-discovered by
--- 388,464 ----
  'hello_world' in the website directory:

!  package Openinteract2::Manage::MyTask
!  
!  use strict;
!  use base qw( OpenInteract2::Manage::Website );
!  
!  sub get_name {
!      return 'hello_world';
!  }
!  
!  sub get_brief_description {
!      return "Creates a 'hello_world' file in your website directory.";
!  }
!  
!  sub get_parameters {
!      my ( $self ) = @_;
!      return { website_dir => $self->_get_website_dir_param,
!               hello_message => {
!                   description => 'Message to write to file',
!                   is_required => 'yes',
!               },
!      };
!  }
!  
!  sub run_task {
!      my ( $self ) = @_;
!      my $website_dir = $self->param( 'website_dir' );
!      $website_dir =~ s|/$||;
!      my $filename = File::Spec->catfile( $website_dir, 'hello_world' );
!      my %status = ();
!      if ( -f $filename ) {
!          $status{message} = "Could not create [$filename]: already exists";
!          $status{is_ok}   = 'no';
!          $self->_add_status( \%status );
!          return;
!      }
!      eval { open( HW, '>', $filename ) || die $! };
!      if ( $@ ) {
!          $status{message} = "Cannot write to [$filename]: $@";
!          $status{is_ok}   = 'no';
!      }
!      else {
!          print HW $self->param( 'hello_message' );
!          close( HW );
!          $status{is_ok}   = 'yes';
!          $status{message} = "File [$filename] created ok";
!      }
!      $self->_add_status( \%status );
!  }
!  
!  OpenInteract2::Manage->register_factory_type( get_name() => __PACKAGE__ );
! 
!  1;

  And here is how you would run your task:

!  #!/usr/bin/perl
!  
!  use strict;
!  use OpenInteract2::Manage;
! 
!  my $task = OpenInteract2::Manage->new( 'hello_world', {
!     website_dir => $ENV{OPENINTERACT2}
!  });
!  my @status = eval { $task->execute };
!  if ( $@ ) {
!      print "Task failed to run: $@";
!  }
!  else {
!      foreach my $s ( @status ) {
!          print "Task OK? $s->{is_ok}\n",
!                "$s->{message}\n";
!      }
!  }

  Since all management tasks are auto-discovered by
***************
*** 347,351 ****
  also run:

! [% INCLUDE examples/mgt_sample_task_run_oi2_manage | indent 2 %]

  And it'll work!
--- 466,470 ----
  also run:

!  $ oi2_manage hello_world

  And it'll work!