CGI::Ex 2.24

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

diff --git a/lib/CGI/Ex/App.pod b/lib/CGI/Ex/App.pod
index 3b93a78383b9d490976b7f1e6456d9442c5c2cfe..2967cbe3972d4bdf5caa4aff09db3c0c9978b5e3 100644 (file)
--- a/lib/CGI/Ex/App.pod
+++ b/lib/CGI/Ex/App.pod
@@ -31,7 +31,7 @@ Well, you should put your content in an external file...
 
     __PACKAGE__->navigate;
 
 
     __PACKAGE__->navigate;
 

-    sub base_dir_abs { '/var/www/templates' }
+    sub template_path { '/var/www/templates' }

 
 
     -------- File: /var/www/templates/my_cgi/main.html --------
 
 
     -------- File: /var/www/templates/my_cgi/main.html --------


@@ -49,7 +49,7 @@ How about if we want to add substitutions...
 
     __PACKAGE__->navigate;
 
 
     __PACKAGE__->navigate;
 

-    sub base_dir_abs { '/var/www/templates' }
+    sub template_path { '/var/www/templates' }

 
     sub main_hash_swap {
         my $self = shift;
 
     sub main_hash_swap {
         my $self = shift;


@@ -76,7 +76,7 @@ How about a form with validation (inluding javascript validation)...
 
     __PACKAGE__->navigate;
 
 
     __PACKAGE__->navigate;
 

-    sub base_dir_abs { '/var/www/templates' }
+    sub template_path { '/var/www/templates' }

 
     sub main_hash_swap { {date => sub { scalar localtime }} }
 
 
     sub main_hash_swap { {date => sub { scalar localtime }} }
 


@@ -208,7 +208,7 @@ The nav_loop method will run as follows:
                 # exits nav_loop if true
 
             ->morph
                 # 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
                 # check ->allow_nested_morph
                 # ->morph_package (hook - get the package to bless into)
                 # ->fixup_after_morph if morph_package exists


@@ -256,11 +256,12 @@ during the run_step hook.
 
         ->info_complete (hook - ran if prepare was true)
             ->ready_validate (hook)
 
         ->info_complete (hook - ran if prepare was true)
             ->ready_validate (hook)

+                ->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)
                 # 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
                        ->base_dir_rel
                        ->name_module
                        ->name_step


@@ -591,13 +592,14 @@ are also documented more in the HOOKS AND METHODS section.
 
 =over 4
 
 
 =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
 
 
 =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
 
 
 =item name_module
 


@@ -632,7 +634,7 @@ a contrived example.  The following is a hypothetical layout for your templates:
 
 In this example we would most likely set values as follows:
 
 
 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
 
     base_dir_rel  content
     name_module   my_app
 


@@ -648,7 +650,7 @@ Continuing with the example and assuming that name of the step that
 the user has requested is "step1" then the following values would be
 returned:
 
 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
     base_dir_rel  content
     name_module   my_app
     name_step     step1


@@ -662,13 +664,13 @@ The call to the template engine would look something like
 the following:
 
     my $t = $self->template_obj({
 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
     });
 
     $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.
 
 The call to the validation engine would pass the absolute
 filename that is returned by file_val.


@@ -677,7 +679,7 @@ The name_module and name_step methods can return filenames with
 additional directories included.  The previous example could
 also have been setup using the following values:
 
 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
 
     base_dir_rel
     name_module   content/my_app
 


@@ -980,7 +982,7 @@ The following is the alphabetical list of methods and hooks.
 
 =over 4
 
 
 =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
 
 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


@@ -1027,7 +1029,8 @@ steps to the end of the current path.
 
 =item auth_args (method)
 
 
 =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.
 It is augmented with arguments that integrate it into CGI::Ex::App.
 
 See the get_valid_auth method and the CGI::Ex::Auth documentation.


@@ -1050,14 +1053,19 @@ was successful - so this data can be defined but false.
 
 See the get_valid_auth method.
 
 
 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)
 
 =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.
 
 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:
 
 For example, to pass multiple paths, you would use something
 similar to the following:


@@ -1066,27 +1074,29 @@ similar to the following:
         return ['/my/path/one', '/some/other/path'];
     }
 
         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.
 
 
 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 "".
 
 =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.
 
 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.
 
 
 See the section on FINDING TEMPLATES for further discussion.
 


@@ -1122,6 +1132,64 @@ The following items will be cleared:
     hash_swap
     hash_common
 
     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.
 =item current_step (method)
 
 Returns the current step that the nav_loop is functioning on.


@@ -1220,6 +1288,12 @@ hooks for the current and remaining steps.  It is used to allow the
 unmorphed before returning.  Also - the post_navigate method will
 still be called.
 
 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.
 =item ext_print (method)
 
 Added as suffix to "name_step" during the default file_print hook.


@@ -1265,15 +1339,15 @@ Returns a filename of the content to be used in the default print
 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
 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
+".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.
 
 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'
 
     # ->file_print('this_step')
     # would return 'content/recipe/this_step.html'


@@ -1286,12 +1360,13 @@ the data for the application in a single location.
 
 =item file_val (hook)
 
 
 =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.
 
 
 The file should be readable by CGI::Ex::Validate::get_validation.
 


@@ -1540,6 +1615,16 @@ Called by the default new method.  Allows for any object
 initilizations that may need to take place.  Default action does
 nothing.
 
 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
 =item insert_path (method)
 
 Arguments are the steps to insert.  Can be called any time.  Inserts


@@ -1635,6 +1720,14 @@ jumping (the path is modified so that the path history is not destroyed
 
 Returns the last step of the path.  Can be used to jump to the last step.
 
 
 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 morph (method)
 
 Allows for temporarily "becoming" another object type for the


@@ -1977,16 +2070,27 @@ List the step previous to this one.  Will return '' if there is no previous step
 
 =item print (hook)
 
 
 =item print (hook)
 

-Take the information generated by prepared_print, format it, and print
-it out.  Default incarnation uses CGI::Ex::Template (a subclass of
-Template::Alloy) 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
 
 
 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.
 =item ready_validate (hook)
 
 Should return true if enough information is present to run validate.


@@ -1999,6 +2103,13 @@ 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.
 

+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
 =item refine_path (hook)
 
 Called at the end of nav_loop.  Passed a single value indicating


@@ -2175,8 +2286,11 @@ This method is not normally used.
 =item set_ready_validate (hook and method)
 
 Sets that the validation is ready (or not) to validate.  Should set the value
 =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;
 
     sub set_ready_validate {
         my $self = shift;


@@ -2229,7 +2343,7 @@ 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
 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
+template_path (which will be used to initialize INCLUDE_PATH by

 default).
 
 The default method will create a template object by calling the
 default).
 
 The default method will create a template object by calling the


@@ -2255,7 +2369,7 @@ method as follows:
 
         my $t = HTML::Template->new(source => $file,
                                     type   => $type,
 
         my $t = HTML::Template->new(source => $file,
                                     type   => $type,

-                                    path   => $self->base_dir_abs,
+                                    path   => $self->template_path,

                                     die_on_bad_params => 0,
                                     );
 
                                     die_on_bad_params => 0,
                                     );
 


@@ -2277,7 +2391,7 @@ For a listing of the available syntaxes, see the current L<Template::Alloy> docu
 
 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
 
 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 (a subclass of Template::Alloy)
 value is not already set.
 
 The returned hashref can contain any arguments that CGI::Ex::Template (a subclass of Template::Alloy)


@@ -2295,7 +2409,7 @@ See the L<Template::Alloy> documentation for a listing of all possible configura
 =item template_obj (method)
 
 Called from swap_template.  It is passed the result of template_args
 =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
+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:
 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:


@@ -2307,6 +2421,11 @@ similar to the following:
         return Template->new($args);
     }
 
         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
 =item unmorph (method)
 
 Allows for returning an object back to its previous blessed state if


@@ -2358,6 +2477,14 @@ path.  A validation item of:
 
 would append 'bar' and 'baz' to the path should all validation succeed.
 
 
 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
 =item verify_user (method)
 
 Installed as a hook to CGI::Ex::App during get_valid_auth.  Should return


@@ -2513,7 +2640,7 @@ CGI::Ex::App is differrent in that it:
 
 The following example shows the creation of a basic recipe
 database.  It requires the use of DBD::SQLite, but that is all.
 
 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
 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


@@ -2553,7 +2680,7 @@ the core logic of the application.
         debug shift->dump_history;
     }
 
         debug shift->dump_history;
     }
 

-    sub base_dir_abs { '/var/www/templates' }
+    sub template_path { '/var/www/templates' }

 
     sub base_dir_rel { 'content' }
 
 
     sub base_dir_rel { 'content' }