use vars qw($VERSION);
BEGIN {
- $VERSION = '2.00';
+ $VERSION = '2.01';
Time::HiRes->import('time') if eval {require Time::HiRes};
}
sub init {}
+sub destroy {}
+
###----------------------------------------------------------------###
sub navigate {
$self->{'_time'} = time;
+ $self->destroy;
+
return $self;
}
$self->morph($step);
### run the guts of the step
- my $status = $self->run_hook('run_step', $step);
-
- $self->unmorph($step);
+ my $handled = $self->run_hook('run_step', $step);
### Allow for the run_step to intercept.
### A true status means the run_step took over navigation.
- return if $status;
+ if ($handled) {
+ $self->unmorph($step);
+ return;
+ }
+
+ ### if there are no future steps - allow for this step to designate one to follow
+ my $is_at_end = $self->{'path_i'} >= $#$path ? 1 : 0;
+ $self->run_hook('refine_path', $step, $is_at_end);
+
+ $self->unmorph($step);
}
### allow for one exit point after the loop
sub previous_step {
my $self = shift;
- croak "previous_step is readonly" if $#_ != -1;
return $self->step_by_path_index( ($self->{'path_i'} || 0) - 1 );
}
sub current_step {
my $self = shift;
- croak "current_step is readonly" if $#_ != -1;
return $self->step_by_path_index( ($self->{'path_i'} || 0) );
}
-sub next_step {
+sub next_step { # method and hook
my $self = shift;
- croak "next_step is readonly" if $#_ != -1;
return $self->step_by_path_index( ($self->{'path_i'} || 0) + 1 );
}
sub last_step {
my $self = shift;
- croak "last_step is readonly" if $#_ != -1;
return $self->step_by_path_index( $#{ $self->path } );
}
sub first_step {
my $self = shift;
- croak "first_step is readonly" if $#_ != -1;
return $self->step_by_path_index( 0 );
}
croak "Could not find a method named ${step}_${hook} or ${hook}";
}
-
### record history
my $hist = {
step => $step,
}
sub morph {
- my $self = shift;
- my $step = shift || return;
- return if ! (my $allow = $self->allow_morph($step));
+ my $self = shift;
+ my $step = shift || return;
+ my $allow = $self->allow_morph($step) || return;
### place to store the lineage
my $lin = $self->{'__morph_lineage'} ||= [];
meth => 'morph',
found => 'morph',
time => time,
- elapsed => 0,
+ elapsed => 0,
+ response => 0
};
push @{ $self->history }, $hist;
if (ref($allow) && ! $allow->{$step}) { # hash - but no step - record for unbless
$hist->{'found'} .= " (not allowed to morph to that step)";
- return;
+ return 0;
}
### make sure we haven't already been reblessed
|| (ref($allow) && ! $allow->{$step}) # hash - but no step
)) {
$hist->{'found'} .= $allow ? " (not allowed to nested_morph to that step)" : " (nested_morph disabled)";
- return; # just return - don't die so that we can morph early
+ return 0; # just return - don't die so that we can morph early
}
### if we are not already that package - bless us there
}
}
+ $hist->{'response'} = 1;
+ return 1;
}
sub unmorph {
meth => 'unmorph',
found => 'unmorph',
time => time,
- elapsed => 0,
+ elapsed => 0,
+ response => 0,
};
push @{ $self->history }, $hist;
$hist->{'found'} .= " (already isa $cur)";
}
+ $hist->{'response'} = 1;
return $self;
}
return 0;
}
+sub refine_path {
+ my ($self, $step, $is_at_end) = @_;
+ return 0 if ! $is_at_end; # if we aren't at the end of the path, don't do anything
+
+ my $next_step = $self->run_hook('next_step', $step) || return 0;
+ $self->run_hook('set_ready_validate', $step, 0);
+ $self->append_path($next_step);
+ return 1;
+}
+
sub prepared_print {
my $self = shift;
my $step = shift;
}
sub info_complete {
- my $self = shift;
- my $step = shift;
-
+ my ($self, $step) = @_;
return 0 if ! $self->run_hook('ready_validate', $step);
- return 0 if ! $self->run_hook('validate', $step);
+ return 0 if ! $self->run_hook('validate', $step, $self->form);
return 1;
}
sub ready_validate {
- my $self = shift;
- my $step = shift;
-
+ my ($self, $step) = @_;
return ($ENV{'REQUEST_METHOD'} && $ENV{'REQUEST_METHOD'} eq 'POST') ? 1 : 0;
}
-sub set_ready_validate {
- my ($self, $ready) = @_;
- $ENV{'REQUEST_METHOD'} = ($ready) ? 'POST' : 'GET';
+sub set_ready_validate { # hook and method
+ my $self = shift;
+ my ($step, $is_ready) = (@_ == 2) ? @_ : (undef, shift);
+ $ENV{'REQUEST_METHOD'} = ($is_ready) ? 'POST' : 'GET';
+ return $is_ready;
}
sub validate {
- my $self = shift;
- my $step = shift;
- my $form = shift || $self->form;
+ my ($self, $step, $form) = @_;
+
my $hash = $self->run_hook('hash_validation', $step);
my $what_was_validated = [];
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
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
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 {
->post_navigate
}
# dying errors will run the ->handle_error method
+
+ ->destroy
}
+=head2 nav_loop
+
The nav_loop method will run as follows:
nav_loop {
->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
} 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.
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
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.
+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
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.
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;
- if (shift) {
+ my ($step, $is_ready) = (@_ == 2) ? @_ : (undef, shift);
+ if ($is_ready) {
$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."
+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 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,
projects / chaz / p5-CGI-Ex / commitdiff
