=head1 SYNOPSIS
+A basic example:
+
+ -------- File: /cgi-bin/my_cgi --------
+
#!/usr/bin/perl -w
use strict;
exit;
sub main_file_print {
- return \ "Hello World";
+ return \ "Hello World!";
+ }
+
+Well, you should put your content in an external file...
+
+ -------- File: /cgi-bin/my_cgi --------
+
+ #!/usr/bin/perl -w
+
+ use strict;
+ use base qw(CGI::Ex::App);
+
+ __PACKAGE__->navigate;
+
+ sub template_path { '/var/www/templates' }
+
+
+ -------- File: /var/www/templates/my_cgi/main.html --------
+
+ Hello World!
+
+How about if we want to add substitutions...
+
+ -------- File: /cgi-bin/my_cgi --------
+
+ #!/usr/bin/perl -w
+
+ use strict;
+ use base qw(CGI::Ex::App);
+
+ __PACKAGE__->navigate;
+
+ sub template_path { '/var/www/templates' }
+
+ sub main_hash_swap {
+ my $self = shift;
+ return {
+ greeting => 'Hello',
+ date => sub { scalar localtime },
+ };
}
-There is a longer "SYNOPSIS" after the process flow discussion.
+
+ -------- File: /var/www/templates/my_cgi/main.html --------
+
+ [% greeting %] World! ([% date %])
+
+
+How about a form with validation (inluding javascript validation)...
+
+ -------- File: /cgi-bin/my_cgi --------
+
+ #!/usr/bin/perl -w
+
+ use strict;
+ use base qw(CGI::Ex::App);
+
+ __PACKAGE__->navigate;
+
+ sub template_path { '/var/www/templates' }
+
+ sub main_hash_swap { {date => sub { scalar localtime }} }
+
+ sub main_hash_fill {
+ return {
+ guess => 50,
+ };
+ }
+
+ sub main_hash_validation {
+ return {
+ guess => {
+ required => 1,
+ compare1 => '<= 100',
+ compare1_error => 'Please enter a value less than 101',
+ compare2 => '> 0',
+ compare2_error => 'Please enter a value greater than 0',
+ },
+ };
+ }
+
+ sub main_finalize {
+ my $self = shift;
+ my $form = $self->form;
+
+ $self->add_to_form({was_correct => ($form->{'guess'} == 23)});
+
+ return 0; # indicate to show the page without trying to move along
+ }
+
+
+ -------- File: /var/www/templates/my_cgi/main.html --------
+
+ <h2>Hello World! ([% date %])</h2>
+
+ [% IF was_correct %]
+ <b>Correct!</b> - The number was [% guess %].<br>
+ [% ELSIF guess %]
+ <b>Incorrect</b> - The number was not [% guess %].<br>
+ [% END %]
+
+ <form name="[% form_name %]" method="post">
+
+ Enter a number between 1 and 100: <input type="text" name="guess"><br>
+ <span id="guess_error" style="color:red">[% guess_error %]</span><br>
+
+ <input type="submit">
+ </form>
+
+ [% js_validation %]
+
+
+There are infinite possibilities. There is a longer "SYNOPSIS" after
+the process flow discussion and more examples near the end of this
+document. It is interesting to note that there have been no databases
+so far. It is very, very difficult to find a single database
+abstraction that fits every model. CGI::Ex::App is Controller/Viewer
+that is somewhat Model agnostic and doesn't come with any default
+database abstraction.
=head1 DESCRIPTION
foreach step of path {
+ ->require_auth (hook)
+ # exits nav_loop if true
+
->morph
- # check ->allow_morph
+ # check ->allow_morph (hook)
# check ->allow_nested_morph
# ->morph_package (hook - get the package to bless into)
# ->fixup_after_morph if morph_package exists
run_step {
->pre_step (hook)
- # exits nav_loop if true
+ # skips this step if true and exit nav_loop
->skip (hook)
- # skips this step if true (stays in nav_loop)
+ # skips this step if true and stays in nav_loop
->prepare (hook - defaults to true)
->info_complete (hook - ran if prepare was true)
->ready_validate (hook)
- return false if ! ready_validate
+ ->validate_when_data (hook)
+ # returns false from info_complete if ! ready_validate
->validate (hook - uses CGI::Ex::Validate to validate form info)
->hash_validation (hook)
->file_val (hook)
- ->base_dir_abs
+ ->vob_path (defaults to template_path)
->base_dir_rel
->name_module
->name_step
->ext_val
- returns true if validate is true or if nothing to validate
+ # returns true if validate is true or if nothing to validate
->finalize (hook - defaults to true - ran if prepare and info_complete were true)
# Assuming /cgi-bin/my_app is the program being run
- URI: /cgi-bin/my_app
+ URI: /cgi-bin/my_app
STEP: main
FORM: {}
WHY: No other information is passed. The path method is
called which eventually calls ->default_step which
defaults to "main"
- URI: /cgi-bin/my_app?foo=bar
+ URI: /cgi-bin/my_app?foo=bar
STEP: main
FORM: {foo => "bar"}
WHY: Same as previous example except that QUERY_STRING
information was passed and placed in form.
- URI: /cgi-bin/my_app?step=my_step
+ URI: /cgi-bin/my_app?step=my_step
STEP: my_step
FORM: {step => "my_step"}
WHY: The path method is called which looks in $self->form
for the key ->step_key (which defaults to "step").
- URI: /cgi-bin/my_app?step=my_step&foo=bar
+ URI: /cgi-bin/my_app?step=my_step&foo=bar
STEP: my_step
FORM: {foo => "bar", step => "my_step"}
- WHY: Same as before but has other parameters were passed.
+ WHY: Same as before but another parameter was passed.
- URI: /cgi-bin/my_app/my_step
+ URI: /cgi-bin/my_app/my_step
STEP: my_step
FORM: {step => "my_step"}
WHY: The path method is called which called path_info_map_base
$self->form->{$self->step_key} for the initial step. See
the path_info_map_base method for more information.
- URI: /cgi-bin/my_app/my_step?foo=bar
+ URI: /cgi-bin/my_app/my_step?foo=bar
STEP: my_step
FORM: {foo => "bar", step => "my_step"}
WHY: Same as before but other parameters were passed.
- URI: /cgi-bin/my_app/my_step?step=other_step
+ URI: /cgi-bin/my_app/my_step?step=other_step
STEP: other_step
FORM: {step => "other_step"}
WHY: The same procedure took place, but when the PATH_INFO
];
}
- URI: /cgi-bin/my_app/my_step/bar
+ URI: /cgi-bin/my_app/my_step/bar
STEP: my_step
FORM: {foo => "bar"}
WHY: The step was matched as in previous examples using
and the corresponding matched value was placed into
the form using the keys specified following the regex.
- URI: /cgi-bin/my_app/my_step/bar/1234
+ URI: /cgi-bin/my_app/my_step/bar/1234
STEP: my_step
FORM: {foo => "bar", id => "1234"}
WHY: Same as the previous example, except that the first
order that will match the most data. The third regex
would also match this PATH_INFO.
- URI: /cgi-bin/my_app/my_step/some/other/type/of/data
+ URI: /cgi-bin/my_app/my_step/some/other/type/of/data
STEP: my_step
FORM: {anything_else => 'some/other/type/of/data'}
WHY: Same as the previous example, except that the third
regex matched.
- URI: /cgi-bin/my_app/my_step/bar?bling=blang
+ URI: /cgi-bin/my_app/my_step/bar?bling=blang
STEP: my_step
FORM: {foo => "bar", bling => "blang"}
- WHY: Same as the first step, but additional QUERY_STRING
+ WHY: Same as the first sample, but additional QUERY_STRING
information was passed.
- URI: /cgi-bin/my_app/my_step/one%20two?bar=three%20four
+ URI: /cgi-bin/my_app/my_step/one%20two?bar=three%20four
STEP: my_step
FORM: {anything_else => "one two", bar => "three four"}
WHY: The third path_info_map regex matched. Note that the
The default hash_validation hook returns an empty hashref. This means that passed
in data is all valid and the script will automatically call the step's finalize method.
-The following shows how to some contrived validation to a step called "my_step".
+The following shows how to add some contrived validation to a step called "my_step".
sub my_step_hash_validation {
return {
};
}
-You could also return the fields from the hash_common hook and they would be available
-in both the template swapping as well as form filling.
+You could also return the fields from the hash_common hook and they
+would be available in both the template swapping as well as form
+filling.
-See the hash_base, hash_common, hash_form, hash_swap, hash_errors, swap_template, and
-template_args hooks for more information.
+See the hash_base, hash_common, hash_form, hash_swap, hash_errors,
+swap_template, and template_args hooks for more information.
-The default template engine used is CGI::Ex::Template which is Template::Toolkit compatible.
-See the CGI::Ex::Template or Template::Toolkit documentation for the types of data
-that can be passed, and for the syntax that can be used.
+The default template engine used is CGI::Ex::Template which is now a subclass
+of Template::Alloy. The default interface used is TT which is the
+Template::Toolkit interface. Template::Alloy allows for using TT documents,
+HTML::Template documents, HTML::Template::Expr documents, Text::Tmpl documents,
+or Velocity (VTL) documents. See the L<Template::Alloy> documentation
+for more information.
=head1 ADDING ADDITIONAL FORM FILL VARIABLES
The default file_print hook will look for content on your file system,
but it can also be completely overridden to return a reference to a
-scalar containing the contents of your file. Actually it can return
-anything that CGI::Ex::Template (Template::Toolkit compatible) will
+scalar containing the contents of your file (beginning with version 2.14
+string references can be cached which makes templates passed this way
+"first class" citizens). Actually it can return
+anything that Template::Alloy (Template::Toolkit compatible) will
treat as input. This templated html is displayed to the user during
any step that enters the "print" phase.
=over 4
-=item base_dir_abs
+=item template_path
-Absolute path or arrayref of paths to the base templates directory. Default "".
+Absolute path or arrayref of paths to the base templates directory. Defaults to
+base_dir_abs which defaults to ['.'].
=item base_dir_rel
-Relative path inside of the base_dir_abs directory where content can be found. Default "".
+Relative path inside of the template_path directory where content can be found. Default "".
=item name_module
In this example we would most likely set values as follows:
- base_dir_abs /home/user/templates
+ template_path /home/user/templates
base_dir_rel content
name_module my_app
the user has requested is "step1" then the following values would be
returned:
- base_dir_abs /home/user/templates
+ template_path /home/user/templates
base_dir_rel content
name_module my_app
name_step step1
the following:
my $t = $self->template_obj({
- INCLUDE_PATH => $self->base_dir_abs,
+ INCLUDE_PATH => $self->template_path, # defaults to base_dir_abs
});
$t->process($self->file_print($step), \%vars);
The template engine would then look for the relative file
-inside of the absolute paths (from base_dir_abs).
+inside of the absolute paths (from template_path).
The call to the validation engine would pass the absolute
filename that is returned by file_val.
additional directories included. The previous example could
also have been setup using the following values:
- base_dir_abs /home/user/templates
+ template_path /home/user/templates
base_dir_rel
name_module content/my_app
separate files. Though CGI::Ex::App will work "out of the box" as
shown it is more probable that any platform using it will customize
the various hooks to their own tastes (for example, switching print to
-use a templating system other than CGI::Ex::Template).
+use a templating system other than Template::Alloy).
=head1 SYNOPSIS STEP BY STEP
=over 4
-=item allow_morph (method)
+=item allow_morph (hook)
Should return true if this step is allowed to "morph" the current App
object into another package. Default is false. It is passed a single
=item auth_args (method)
-Should return a hashref that will be passed to the new method of CGI::Ex::Auth.
+Should return a hashref that will be passed to the auth_obj method
+which should return a CGI::Ex::Auth compatible object.
It is augmented with arguments that integrate it into CGI::Ex::App.
See the get_valid_auth method and the CGI::Ex::Auth documentation.
See the get_valid_auth method.
+=item auth_obj (method)
+
+Passed auth_args. Should return a CGI::Ex::Auth compatible object. Default
+is to call CGI::Ex::Auth->new with the passed args.
+
=item base_dir_abs (method)
-Used as the absolute base directory to find template files and validation files.
+Used as the absolute base directory to find template, validation and conf files.
It may return a single value or an arrayref of values, or a coderef that
returns an arrayref or coderef of values. You may pass base_dir_abs
as a parameter in the arguments passed to the "new" method.
-Default value is "".
+Default value is ['.'].
For example, to pass multiple paths, you would use something
similar to the following:
return ['/my/path/one', '/some/other/path'];
}
-The base_dir_abs value is used along with the base_dir_rel, name_module,
-name_step, ext_print and ext_values for determining the values
-returned by the default file_print and file_val hooks. See those methods
-for further discussion.
+The base_dir_abs value is used by template_path along with the
+base_dir_rel, name_module, name_step, ext_print and ext_values for
+determining the values returned by the default file_print and file_val
+hooks. See those methods for further discussion.
See the section on FINDING TEMPLATES for further discussion.
+The base_dir_abs method is also used as the default value for conf_path and vob_path.
+
=item base_dir_rel (method)
Added as a relative base directory to content under the base_dir_abs directory.
Default value is "".
-The base_dir_abs method is used as top level where template includes may
-pull from, while the base_dir_rel is directory relative to the base_dir_abs
+The template_path method is used as top level where template includes may
+pull from, while the base_dir_rel is directory relative to the template_path
where the content files will be stored.
A value for base_dir_rel may passed as a parameter in the arguments passed
to the new method.
-See the base_dir_abs method for more discussion.
+See the template_path and base_dir_abs methods for more discussion.
See the section on FINDING TEMPLATES for further discussion.
path
path_i
history
- __morph_lineage_start_index
- __morph_lineage
+ _morph_lineage_start_index
+ _morph_lineage
hash_errors
hash_fill
hash_swap
hash_common
+=item conf (method)
+
+Used by default in init_from_conf if load_conf returns true.
+Will try to read the file returned by the conf_file method
+using the object returned by conf_obj using that object's read
+method. If conf_validation returns a non-empty hashref, the
+conf hash will be validated using $self->vob->validate (see the
+validate method).
+
+This method may be used for other purposes as well (including when
+load_conf is false)..
+
+Caches results in $self->{'conf'}.
+
+If the conf_file can't be found, the method will die unless
+conf_die_on_fail returns 0 (defaults to true).
+
+=item conf_args
+
+Used by conf_obj.
+
+Defaults to $self->{'conf_args'} which defaults to {}. Will have
+paths => $self->conf_path added before passing to CGI::Ex::Conf->new.
+
+=item conf_file (method)
+
+Used by conf for finding the configuration file to load. Defaults
+to $self->{'conf_file'} which defaults $self->name_module with the extention
+returned by $self->ext_conf added on. For example, if name_module
+returns "my_app" and ext_conf returns "ini" the value returned will
+be "my_app.ini".
+
+The value returned can absolute. If the value will be searched for
+in the paths passed to conf_obj.
+
+The ext_conf may be any of those extentions understood by CGI::Ex::Conf.
+
+=item conf_obj
+
+Used by the conf method to load the file returned by conf_file. Defaults
+to conf_obj which defaults to loading args from conf_args, adding in paths
+returned by conf_path, and calling CGI::Ex::Conf->new.
+
+Any object that provides a read method that returns a hashref can be used.
+
+=item conf_path
+
+Defaults to $self->{'conf_path'} which defaults to base_dir_abs. Should be
+a path or an arrayref of paths to look the configuration file returned by
+conf_file when that file is not absolute.
+
+=item conf_validation
+
+Used by default conf method.
+Defaults to an empty hashref. If non-empty hashref is passed, the
+hashref returned by conf_obj->read will be validated using the hashref
+returned by conf_validation.
+
=item current_step (method)
Returns the current step that the nav_loop is functioning on.
debug: admin/Recipe.pm line 14
shift->dump_history = [
"Elapsed: 0.00562",
+ "view - require_auth - require_auth - 0.00001 - 0",
"view - run_step - run_step - 0.00488 - 1",
" view - pre_step - pre_step - 0.00003 - 0",
" view - skip - view_skip - 0.00004 - 0",
" view - post_print - post_print - 0.00003 - 0"
];
+=item error_step (method)
+
+Defaults to "__error". The name of a step to run should a dying error
+be caught by the default handle_error method. See the handle_error method.
+
=item exit_nav_loop (method)
This method should not normally used but there is no problem with
unmorphed before returning. Also - the post_navigate method will
still be called.
+=item ext_conf
+
+Used by the default conf_file method. Defaults to $self->{'ext_conf'} which
+defaults to 'pl' meaning that the read configuration file should return a
+valid perl hashref.
+
=item ext_print (method)
Added as suffix to "name_step" during the default file_print hook.
See the section on FINDING TEMPLATES for further discussion.
-=item first_step (method)
-
-Returns the first step of the path. Note that first_step may not be the same
-thing as default_step if the path was overridden.
-
-=item form (method)
-
-Returns a hashref of the items passed to the CGI. Returns
-$self->{form} which defaults to CGI::Ex::get_form.
-
-=item handle_error (method)
-
-If anything dies during execution, handle_error will be called with
-the error that had happened. Default action is to die with that error.
-
-=item history (method)
-
-Returns an arrayref which contains trace history of which hooks of
-which steps were ran. Useful for seeing what happened. In general -
-each line of the history will show the current step, the hook
-requested, and which hook was actually called.
-
-The dump_history method shows a short condensed version of this
-history which makes it easier to see what path was followed.
-
-In general, the arrayref is free for anything to push onto which will
-help in tracking other occurrences in the program as well.
-
-=item init (method)
-
-Called by the default new method. Allows for any object
-initilizations that may need to take place. Default action does
-nothing.
-
=item fill_args (hook)
Returns a hashref of args that will be passed to the CGI::Ex::Fill::fill.
hook. Adds method base_dir_rel to hook name_module, and name_step and
adds on the default file extension found in $self->ext_print which
defaults to the property $self->{ext_print} which will default to
-".html". Should return a filename relative to base_dir_abs that can be
-swapped using CGI::Ex::Template, or should be a scalar reference to
+".html". Should return a filename relative to template_path that can be
+swapped using Template::Alloy, or should be a scalar reference to
the template content that can be swapped. This will be used by the
hook print.
- sub base_dir_abs { '/var/www/templates' }
- sub base_dir_rel { 'content' }
- sub name_module { 'recipe' }
- sub ext_print { 'html' } # default
+ sub template_path { '/var/www/templates' }
+ sub base_dir_rel { 'content' }
+ sub name_module { 'recipe' }
+ sub ext_print { 'html' } # default
# ->file_print('this_step')
# would return 'content/recipe/this_step.html'
=item file_val (hook)
-Returns a filename containing the validation. Performs the same
-as file_print, but uses ext_val to get the extension, and it adds
-base_dir_abs onto the returned value (file_print is relative to
-base_dir_abs, while file_val is fully qualified with base_dir_abs).
-If base_dir_abs returns an arrayref of paths, then each path is
-checked for the existence of the file.
+Returns a filename containing the validation. Performs the same as
+file_print, but uses ext_val to get the extension, and it adds
+vob_path (which defaults to template_path which defaults to
+base_dir_abs) onto the returned value (file_print is relative to
+template_path, while file_val is fully qualified with vob_path). If
+vob_path returns an arrayref of paths, then each path is checked for
+the existence of the file.
The file should be readable by CGI::Ex::Validate::get_validation.
This hook is only necessary if the hash_validation hook has not been
overridden.
-
+5B
This method an also return a hashref containing the validation - but
then you may have wanted to override the hash_validation hook.
See the run_hook method and the morph method for more details.
+=item first_step (method)
+
+Returns the first step of the path. Note that first_step may not be the same
+thing as default_step if the path was overridden.
+
=item forbidden_step (method)
Defaults to "__forbidden". The name of a step to run should the current
step name be invalid, or if a step found by the default path method
is invalid. See the path method.
+=item form (method)
+
+Returns a hashref of the items passed to the CGI. Returns
+$self->{form} which defaults to CGI::Ex::get_form.
+
=item form_name (hook)
Return the name of the form to attach the js validation to. Used by
=item get_valid_auth (method)
-If require_auth is true at either the application level or at the
-step level, get_valid_auth will be called.
+If require_auth hook returns true on any given step then get_valid_auth will be called.
It will call auth_args to get some default args to pass to
CGI::Ex::Auth->new. It augments the args with sensible defaults that
be done via the auth_args hash. See the auth_args method and
CGI::Ex::Auth perldoc for more information.
+=item handle_error (method)
+
+If anything dies during execution, handle_error will be called with
+the error that had happened. Default action is to try running the
+step returned by the error_step method.
+
=item hash_base (hook)
A hash of base items to be merged with hash_form - such as pulldown
returned or if the get_validation fails, an empty hash will be returned.
Validation is implemented by ->vob which loads a CGI::Ex::Validate object.
+=item history (method)
+
+Returns an arrayref which contains trace history of which hooks of
+which steps were ran. Useful for seeing what happened. In general -
+each line of the history will show the current step, the hook
+requested, and which hook was actually called.
+
+The dump_history method shows a short condensed version of this
+history which makes it easier to see what path was followed.
+
+In general, the arrayref is free for anything to push onto which will
+help in tracking other occurrences in the program as well.
+
=item info_complete (hook)
Calls the ready_validate hook to see if data is ready to validate. If
sure the data is ready and valid. Will not be run unless
prepare returns true (default).
+=item init (method)
+
+Called by the default new method. Allows for any object
+initilizations that may need to take place. Default action does
+nothing.
+
+=item init_from_conf (method)
+
+Called by the default new method. If load_conf is true, then the
+conf method will be called and the keys returned will be added to
+the $self object.
+
+This method is called after the init method. If you need to further
+fix up values added during init_from_conf, you can use the pre_navigate
+method.
+
=item insert_path (method)
Arguments are the steps to insert. Can be called any time. Inserts
Returns the last step of the path. Can be used to jump to the last step.
+=item load_conf (method)
+
+Defaults to ->{load_conf} which defaults to false. If true, will
+allow keys returned by the conf method to be added to $self during
+the init_from_conf method.
+
+Enabling this method allows for out-of-the-box file based configuration.
+
=item morph (method)
Allows for temporarily "becoming" another object type for the
=item navigate_authenticated (method)
-Same as the method navigate but sets require_auth(1) before
-running. See the require_auth method.
+Same as the method navigate but calls ->require_auth(1) before
+running. It will only work if the navigate_authenticated method
+has not been overwritten. See the require_auth method.
=item new (class method)
=item print (hook)
-Take the information generated by prepared_print, format it, and print it out.
-Default incarnation uses CGI::Ex::Template which is compatible with
-Template::Toolkit. Arguments are: step name (used to call the
-file_print hook), swap hashref (passed to call swap_template), and
-fill hashref (passed to fill_template).
+Take the information generated by prepared_print, format it using
+swap_template, fill it using fill_template and print it out using
+print_out. Default incarnation uses CGI::Ex::Template (a subclass of
+Template::Alloy) which is compatible with Template::Toolkit to do the
+swapping. Arguments are: step name (used to call the file_print
+hook), swap hashref (passed to call swap_template), and fill hashref
+(passed to fill_template).
During the print call, the file_print hook is called which should
return a filename or a scalar reference to the template content is
+=item print_out (hook)
+
+Called with the finished document. Should print out the appropriate headers.
+The default method calls $self->cgix->print_content_type and then
+prints the content.
+
+The print_content_type is passed $self->mimetype (which defaults to
+$self->{'mimetype'} which defaults to 'text/html') and $self->charset
+(which defaults to $self->{'charset'} which defaults to '').
+
=item ready_validate (hook)
Should return true if enough information is present to run validate.
Changing the behavior of ready_validate can help in making wizard type
applications.
+You can also use the validate_when_data hook to change the behavior of
+ready_validate. If valiate_when_data returns true, then
+ready_validate will look for keys in the form matching keys that are
+in hash_validation - if they exist ready_validate will be true. If
+there are no hash_validation keys, ready_validate uses its default
+behavior.
+
=item refine_path (hook)
Called at the end of nav_loop. Passed a single value indicating
Arguments are the steps used to replace. Can be called any time.
Replaces the remaining steps (if any) of the current path.
-=item require_auth (method)
+=item require_auth (hook)
-Default undef. Can return either a true value or a hashref of step names.
+Defaults to self->{require_auth} which defaults to undef.
+If called as a method and passed a single value of 1, 0, or undef it will
+set the value of $self->{require_auth} to that value. If set to a true
+value then any subsequent step will require authentication (unless its
+hook has been overwritten).
-If a hashref of stepnames is returned, authentication will be turned on
-at the step level. In this mode if any step is accessed, the get_valid_auth
-method will be called. If it fails, then the nav_loop will be stopped
-(the post_navigate method will be called - use the is_authed method to perform
-different functions). Any step of the path not in the hash will not require
-authentication. For example, to add authentication to add authentication
-to the add, edit and delete steps you could do:
+Any of the following ways can be used to require authentication on
+every step.
- sub require_auth { {add => 1, edit => 1, delete => 1} }
+=over 4
-If a non-hash true value is returned from the require_auth method then
-authentication will take place before the pre_navigation or the nav_loop methods.
-If authentication fails the navigation process is exited (the post_navigate
-method will not be called).
+=item
sub require_auth { 1 }
-Alternatively you can also could do either of the following:
+=item
__PACKAGE__->navigate_authenticated; # instead of __PACKAGE__->navigate;
- # OR
+=item
+
+ __PACKAGE__->new({require_auth => 1}->navigate;
+
+=item
sub init { shift->require_auth(1) }
- # OR
+=back
- __PACKAGE__->new({require_auth => 1}->navigate;
+Because it is called as a hook, the current step is passed as the
+first argument. If the hook returns false, no authentication will be
+required on this step. If the hook returns a true, non-hashref value,
+authentication will be required via the get_valid_auth method. If the
+method returns a hashref of stepnames to require authentication on,
+the step will require authentication via the get_valid_auth method if
+the current step is in the hashref. If authentication is required and
+succeeds, the step will proceed. If authentication is required and
+fails at the step level the current step will be aborted,
+authentication will be asked for (the post_navigate method will still
+be called).
+
+For example you could add authentication to the add, edit, and delete
+steps in any of the following ways:
-If get_valid_auth returns true, in either case, the is_authed method will
-return true and the auth_data will contain the authenticated user's data.
-If it returns false, auth_data may possibly contain a defined but false
-data object with details as to why authentication failed.
+=over 4
-See the get_valid_auth method.
+=item
+
+ sub require_auth { {add => 1, edit => 1, delete => 1} }
+
+=item
+
+ sub add_require_auth { 1 }
+ sub edit_require_auth { 1 }
+ sub delete_require_auth { 1 }
+
+=item
+
+ sub require_auth {
+ my ($self, $step) = @_;
+ return 1 if $step && $step =~ /^(add|edit|delete)$/;
+ return 0;
+ }
+
+=back
+
+If however you wanted to require authentication on all but one or two methods
+(such as requiring authentication on all but a forgot_password step) you could do
+either of the following:
+
+=over 4
+
+=item
+
+ sub require_auth {
+ my ($self, $step) = @_;
+ return 0 if $step && $step eq 'forgot_password';
+ return 1; # require auth on all other steps
+ }
+
+=item
+
+ sub require_auth { 1 } # turn it on for all steps
+
+ sub forgot_password_require_auth { 0 } # turn it off
+
+=back
+
+See the get_valid_auth method for what occurs should authentication be required.
+
+There is one key difference from the 2.14 version of App. In 2.14 and
+previous versions, the pre_navigate and post_navigate methods would
+not be called if require_auth returned a true non-hashref value. In
+version 2.15 and later, the 2.15 pre_navigate and post_navigate
+methods are always called - even if authentication fails. Also in 2.15
+and later, the method is called as a hook meaning the step is passed in.
=item run_hook (method)
=item set_ready_validate (hook and method)
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:
+checked by the hook ready_validate. Has no affect if validate_when_data
+flag is set.
+
+The following would complement the "processing" flag example given in
+ready_validate description:
sub set_ready_validate {
my $self = shift;
=item swap_template (hook)
-Takes the template and hash of variables prepared in print, and processes them
-through the current template engine (default engine is CGI::Ex::Template).
+Takes the template and hash of variables prepared in print, and
+processes them through the current template engine (default engine is
+CGI::Ex::Template a subclass of Template::Alloy).
-Arguments are the template and the swap hashref. The template can be either a
-scalar reference to the actual content, or the filename of the content. If the
-filename is specified - it should be relative to base_dir_abs (which will be
-used to initialize INCLUDE_PATH by default).
+Arguments are the template and the swap hashref. The template can be
+either a scalar reference to the actual content, or the filename of
+the content. If the filename is specified - it should be relative to
+template_path (which will be used to initialize INCLUDE_PATH by
+default).
-The default method will create a template object by calling the template_args hook
-and passing the returned hashref to the template_obj method. The default template_obj method
-returns a CGI::Ex::Template object, but could easily be swapped to use a Template::Toolkit
-based object. If a non-Template::Toolkit compatible object is to be used, then
-the swap_template hook can be overridden to use another templating engine.
+The default method will create a template object by calling the
+template_args hook and passing the returned hashref to the
+template_obj method. The default template_obj method returns a
+CGI::Ex::Template object, but could easily be swapped to use a
+Template::Toolkit based object. If a non-Template::Toolkit compatible
+object is to be used, then the swap_template hook can be overridden to
+use another templating engine.
For example to use the HTML::Template engine you could override the swap_template
method as follows:
my $t = HTML::Template->new(source => $file,
type => $type,
- path => $self->base_dir_abs,
+ path => $self->template_path,
die_on_bad_params => 0,
);
return $t->output;
}
+As of version 2.13 of CGI::Ex::Template you could also simply do the
+following to parse the templates using HTML::Template::Expr syntax.
+
+ sub template_args {
+ return {SYNTAX => 'hte'};
+ }
+
+For a listing of the available syntaxes, see the current L<Template::Alloy> documentation.
+
=item template_args (hook)
Returns a hashref of args that will be passed to the "new" method of CGI::Ex::Template.
The method is normally called from the swap_template hook. The swap_template hook
-will add a value for INCLUDE_PATH which is set equal to base_dir_abs, if the INCLUDE_PATH
+will add a value for INCLUDE_PATH which is set equal to template_path, if the INCLUDE_PATH
value is not already set.
-The returned hashref can contain any arguments that CGI::Ex::Template would understand.
+The returned hashref can contain any arguments that CGI::Ex::Template (a subclass of Template::Alloy)
+would understand.
sub template_args {
return {
};
}
+See the L<Template::Alloy> documentation for a listing of all possible configuration arguments.
+
=item template_obj (method)
-Called from swap_template. It is passed the result of template_args that have
-had a default INCLUDE_PATH added. The default implementation uses CGI::Ex::Template
-but can easily be changed to use Template::Toolkit by using code similar to the following:
+Called from swap_template. It is passed the result of template_args
+that have had a default INCLUDE_PATH added via template_path. The default
+implementation uses CGI::Ex::Template (a subclass of Template::Alloy)
+but can easily be changed to use Template::Toolkit by using code
+similar to the following:
use Template;
return Template->new($args);
}
+=item template_path (method)
+
+Defaults to $self->{'template_path'} which defaults to base_dir_abs. Used by
+the template_obj method.
+
=item unmorph (method)
Allows for returning an object back to its previous blessed state if
would append 'bar' and 'baz' to the path should all validation succeed.
+=item validate_when_data (hook)
+
+Defaults to "validate_when_data" property which defaults to false. Called
+during the ready_validate hook. If returns true, ready_validate will look
+for keys in the form matching keys that are in hash_validation - if they exist
+ready_validate will be true. If there are no hash_validation keys, ready_validate
+uses its default behavior.
+
=item verify_user (method)
Installed as a hook to CGI::Ex::App during get_valid_auth. Should return
Seemingly the most well know of application builders.
CGI::Ex::App is different in that it:
- * Uses Template::Toolkit compatible CGI::Ex::Template by default
+ * Uses Template::Toolkit compatible CGI::Ex::Template (a
+ subclass of Template::Alloy) by default.
CGI::Ex::App can easily use another toolkit by simply
overriding the ->swap_template method.
CGI::Application uses HTML::Template.
The following example shows the creation of a basic recipe
database. It requires the use of DBD::SQLite, but that is all.
-Once you have configured the db_file and base_dir_abs methods
+Once you have configured the db_file and template_path methods
of the "recipe" file, you will have a working script that
does CRUD for the recipe table. The observant reader may ask - why
not use Catalyst or Ruby on Rails? The observant programmer will
debug shift->dump_history;
}
- sub base_dir_abs { '/var/www/templates' }
+ sub template_path { '/var/www/templates' }
sub base_dir_rel { 'content' }
return 0;
}
- my $s = "UPDATE recipe SET title = ?, ingredients = ?, directions = ? WHERE id = ?";
+ $s = "UPDATE recipe SET title = ?, ingredients = ?, directions = ? WHERE id = ?";
$self->dbh->do($s, {}, $form->{'title'},
$form->{'ingredients'},
$form->{'directions'},
sub require_auth { {add => 1, edit => 1, delete => 1} }
+We could also enable authentication by using individual hooks as in:
+
+ sub add_require_auth { 1 }
+ sub edit_require_auth { 1 }
+ sub delete_require_auth { 1 }
+
+Or we could require authentication on everything - but let a few steps in:
+
+ sub require_auth { 1 } # turn authentication on for all
+ sub main_require_auth { 0 } # turn it off for main and view
+ sub view_require_auth { 0 }
+
That's it. The add, edit, and delete steps will now require authentication.
See the require_auth, get_valid_auth, and auth_args methods for more information.
Also see the L<CGI::Ex::Auth> perldoc.
The following corporation and individuals contributed in some part to
the original versions.
- Bizhosting.com - giving a problem that fit basic design patterns.
+ Bizhosting.com - giving a problem that fit basic design patterns.
- Earl Cahill - pushing the idea of more generic frameworks.
+ Earl Cahill - pushing the idea of more generic frameworks.
- Adam Erickson - design feedback, bugfixing, feature suggestions.
+ Adam Erickson - design feedback, bugfixing, feature suggestions.
- James Lance - design feedback, bugfixing, feature suggestions.
-
-=head1 AUTHOR
+ James Lance - design feedback, bugfixing, feature suggestions.
-Paul Seamons <paul at seamons dot com>
+ Krassimir Berov - feedback and some warnings issues with POD examples.
=head1 LICENSE
This module may be distributed under the same terms as Perl itself.
+=head1 AUTHOR
+
+Paul Seamons <perl at seamons dot com>
+
=cut
projects / chaz / p5-CGI-Ex / blobdiff