CGI::Ex 2.01

[chaz/p5-CGI-Ex] / lib / CGI / Ex / App.pod

diff --git a/lib/CGI/Ex/App.pod b/lib/CGI/Ex/App.pod
index 7e6fe25fd021521eef7f4dc74194bde3b42f126c..e7c827d038e110c1cc0c719af8b968a0d473c1f2 100644 (file)
--- a/lib/CGI/Ex/App.pod
+++ b/lib/CGI/Ex/App.pod
@@ -158,7 +158,7 @@ Now we need to invoke the process:
     exit;
 
 Note: the "exit" isn't necessary - but it is kind of nice to infer
     exit;
 
 Note: the "exit" isn't necessary - but it is kind of nice to infer

-that program flow doesn't go beyond the ->navigate call.
+that process flow doesn't go beyond the ->navigate call.

 
 The navigate routine is now going to try and "run" through a series of
 steps.  Navigate will call the ->path method which should return an
 
 The navigate routine is now going to try and "run" through a series of
 steps.  Navigate will call the ->path method which should return an


@@ -290,7 +290,7 @@ ready to validate so it prints out the template page.
 For more of a real world example, it would be good to read the sample recipe db
 application included at the end of this document.
 
 For more of a real world example, it would be good to read the sample recipe db
 application included at the end of this document.
 

-=head1 DEFAULT PROGRAM FLOW
+=head1 DEFAULT PROCESS FLOW

 
 The following pseudo-code describes the process flow
 of the CGI::Ex::App framework.  Several portions of the flow
 
 The following pseudo-code describes the process flow
 of the CGI::Ex::App framework.  Several portions of the flow


@@ -300,6 +300,8 @@ like a lot to follow, but if the process is broken down into the
 discrete operations of step iteration, data validation, and template
 printing the flow feels more natural.
 
 discrete operations of step iteration, data validation, and template
 printing the flow feels more natural.
 

+=head2 navigate
+

 The process starts off by calling ->navigate.
 
     navigate {
 The process starts off by calling ->navigate.
 
     navigate {


@@ -309,8 +311,12 @@ The process starts off by calling ->navigate.
             ->post_navigate
         }
         # dying errors will run the ->handle_error method
             ->post_navigate
         }
         # dying errors will run the ->handle_error method

+
+        ->destroy

     }
 
     }
 

+=head2 nav_loop
+

 The nav_loop method will run as follows:
 
     nav_loop {
 The nav_loop method will run as follows:
 
     nav_loop {


@@ -333,6 +339,11 @@ The nav_loop method will run as follows:
 
             ->run_step (hook)
 
 
             ->run_step (hook)
 

+            ->refine_path (hook)
+                # only called if run_step returned false (page not printed)
+                ->next_step (hook) # find next step and add to path
+                ->set_ready_validate(0) (hook)
+

             ->unmorph
                 # only called if morph worked
                 # ->fixup_before_unmorph if blessed to current package
             ->unmorph
                 # only called if morph worked
                 # ->fixup_before_unmorph if blessed to current package


@@ -350,6 +361,8 @@ The nav_loop method will run as follows:
 
     } end of nav_loop
 
 
     } end of nav_loop
 

+=head2 run_step (hook)
+

 For each step of the path the following methods will be run
 during the run_step hook.
 
 For each step of the path the following methods will be run
 during the run_step hook.
 


@@ -540,6 +553,12 @@ If nav_loop runs of the end of the path (runs out of steps), this
 method is called, the step is added to the path, and nav_loop calls
 itself recursively.
 
 method is called, the step is added to the path, and nav_loop calls
 itself recursively.
 

+=item destroy (method)
+
+Called at the end of navigate after all other actions have run.  Can
+be used for undoing things done in the ->init method called during
+the ->new method.
+

 =item dump_history (method)
 
 Show simplified trace information of which steps were called, the
 =item dump_history (method)
 
 Show simplified trace information of which steps were called, the


@@ -1161,11 +1180,18 @@ object has been blessed to allow for any other initilizations.
 
     my $app = MyApp->new({name_module => 'my_app'});
 
 
     my $app = MyApp->new({name_module => 'my_app'});
 

-=item next_step (method)
+=item next_step (hook and method)

 
 Returns the next step in the path.  If there is no next step, it
 returns the default_step.
 
 
 Returns the next step in the path.  If there is no next step, it
 returns the default_step.
 

+It can be used as a method to return the next step in the path
+to pass to a method such as ->jump.
+
+It is also used as a hook by the refine_path hook.  If there is no
+more steps, it will call the next_step hook to try and find a step to
+append to the path.
+

 =item path (method)
 
 Return an arrayref (modifiable) of the steps in the path.  For each
 =item path (method)
 
 Return an arrayref (modifiable) of the steps in the path.  For each


@@ -1291,6 +1317,23 @@ and check for its presence - such as the following:
 Changing the behavior of ready_validate can help in making wizard type
 applications.
 
 Changing the behavior of ready_validate can help in making wizard type
 applications.
 

+=item refine_path (hook)
+
+Called at the end of nav_loop.  Passed a single value indicating
+if there are currently more steps in the path.
+
+The default implementation returns if there are still more steps
+in the path.  Otherwise, it calls the next_step hook and appends
+it to the path with the append_path method, and then calls
+the set_ready_validate hook and passes it 0.
+
+This allows you to simply put
+
+    sub edit_next_step { '_edit_success' }
+
+In your code and it will automatically do the right thing and
+go to the _edit_success step.
+

 =item recurse_limit (method)
 
 Default 15.  Maximum number of times to allow nav_loop to call itself.
 =item recurse_limit (method)
 
 Default 15.  Maximum number of times to allow nav_loop to call itself.


@@ -1388,25 +1431,38 @@ begins.  This will set the path arrayref to the passed steps.
 
 This method is not normally used.
 
 
 This method is not normally used.
 

-=item set_ready_validate (method)
+=item set_ready_validate (hook and method)

 
 

-Sets that the validation is ready to validate.  Should set the value
+Sets that the validation is ready (or not) to validate.  Should set the value

 checked by the hook ready_validate.  The following would complement the
 processing flag above:
 
     sub set_ready_validate {
         my $self = shift;
 checked by the hook ready_validate.  The following would complement the
 processing flag above:
 
     sub set_ready_validate {
         my $self = shift;

-        if (shift) {
+        my ($step, $is_ready) = (@_ == 2) ? @_ : (undef, shift);
+        if ($is_ready) {

             $self->form->{'processing'} = 1;
         } else {
             delete $self->form->{'processing'};
         }
             $self->form->{'processing'} = 1;
         } else {
             delete $self->form->{'processing'};
         }

+        return $is_ready;

     }
 
 Note that for this example the form key "processing" was deleted.  This
 is so that the call to fill in any html forms won't swap in a value of
 zero for form elements named "processing."
 
     }
 
 Note that for this example the form key "processing" was deleted.  This
 is so that the call to fill in any html forms won't swap in a value of
 zero for form elements named "processing."
 

+Also note that this method may be called as a hook as in
+
+    $self->run_hook('set_ready_validate', $step, 0)
+    # OR
+    $self->set_ready_validate($step, 0);
+
+Or it can take a single argument and should set the ready status
+regardless of the step as in:
+
+    $self->set_ready_validate(0);
+

 =item skip (hook)
 
 Ran at the beginning of the loop before prepare, info_complete, and
 =item skip (hook)
 
 Ran at the beginning of the loop before prepare, info_complete, and


@@ -1474,16 +1530,17 @@ the data before running finalize.
 
 =item validate (hook)
 
 
 =item validate (hook)
 

-Runs validation on the information posted in $self->form.  Uses
-CGI::Ex::Validate for the default validation.  Calls the hook
-hash_validation to load validation information.  Should return true if
-the form passed validation and false otherwise.  Errors are stored as
-a hash in $self->{hash_errors} via method add_errors and can be
-checked for at a later time with method has_errors (if the default
-validate was used).
-
-There are many ways and types to validate the data.  Please see the L<CGI::Ex::Validate>
-module.
+Passed the form from $self->form.  Runs validation on the information
+contained in the passed form.  Uses CGI::Ex::Validate for the default
+validation.  Calls the hook hash_validation to load validation hashref
+(an empty hash means to pass validation).  Should return true if the
+form passed validation and false otherwise.  Errors are stored as a
+hash in $self->{hash_errors} via method add_errors and can be checked
+for at a later time with method has_errors (if the default validate
+was used).
+
+There are many ways and types to validate the data.  Please see the
+L<CGI::Ex::Validate> module.

 
 Upon success, it will look through all of the items which were
 validated, if any of them contain the keys append_path, insert_path,
 
 Upon success, it will look through all of the items which were
 validated, if any of them contain the keys append_path, insert_path,