X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=lib%2FCGI%2FEx%2FApp.pod;h=8194920dcae1aa3e228bb8f382b82568ee0c06bc;hb=a2f50b1efd2bc986617e1de5f5a0bfd8a2953b0e;hp=6fe97464e0e828e7d241fff509c46dcfe814ffd8;hpb=419d9570723c210429e2be23875160f57dd36156;p=chaz%2Fp5-CGI-Ex diff --git a/lib/CGI/Ex/App.pod b/lib/CGI/Ex/App.pod index 6fe9746..8194920 100644 --- 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; - sub base_dir_abs { '/var/www/templates' } + sub template_path { '/var/www/templates' } -------- File: /var/www/templates/my_cgi/main.html -------- @@ -49,7 +49,7 @@ How about if we want to add substitutions... __PACKAGE__->navigate; - sub base_dir_abs { '/var/www/templates' } + sub template_path { '/var/www/templates' } sub main_hash_swap { my $self = shift; @@ -76,7 +76,7 @@ How about a form with validation (inluding javascript validation)... __PACKAGE__->navigate; - sub base_dir_abs { '/var/www/templates' } + sub template_path { '/var/www/templates' } sub main_hash_swap { {date => sub { scalar localtime }} } @@ -132,8 +132,10 @@ How about a form with validation (inluding javascript 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. CGI::Ex::App is Controller/Viewer that is somewhat Model -agnostic. +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 @@ -206,7 +208,7 @@ The nav_loop method will run as follows: # 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 @@ -245,25 +247,25 @@ during the run_step hook. 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 + # 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) @@ -589,13 +591,14 @@ are also documented more in the HOOKS AND METHODS section. =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 @@ -630,7 +633,7 @@ a contrived example. The following is a hypothetical layout for your templates: 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 @@ -646,7 +649,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: - base_dir_abs /home/user/templates + template_path /home/user/templates base_dir_rel content name_module my_app name_step step1 @@ -660,13 +663,13 @@ The call to the template engine would look something like 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. @@ -675,7 +678,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: - base_dir_abs /home/user/templates + template_path /home/user/templates base_dir_rel name_module content/my_app @@ -978,7 +981,7 @@ The following is the alphabetical list of methods and hooks. =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 @@ -1025,7 +1028,8 @@ steps to the end of the current path. =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. @@ -1048,14 +1052,19 @@ was successful - so this data can be defined but false. 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: @@ -1064,27 +1073,29 @@ 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. @@ -1113,13 +1124,71 @@ The following items will be cleared: 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. @@ -1202,6 +1271,11 @@ called is "view". " 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 @@ -1213,6 +1287,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. +=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. @@ -1235,40 +1315,6 @@ then the file "foo.val" will be searched for. 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. @@ -1292,15 +1338,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 -".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. - 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' @@ -1313,18 +1359,19 @@ the data for the application in a single location. =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. @@ -1368,12 +1415,22 @@ override the base package (it is still OK to use the full method name 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 @@ -1433,6 +1490,12 @@ Full customization of the login process and the login template can 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 @@ -1525,6 +1588,19 @@ pass it to CGI::Ex::Validate::get_validation. If no file_val is 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 @@ -1532,6 +1608,22 @@ so it calls the validate hook to validate the data. Should make 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 @@ -1627,6 +1719,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. +=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 @@ -1969,16 +2069,27 @@ List the step previous to this one. Will return '' if there is no previous step =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 +=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. @@ -2221,7 +2332,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 -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 @@ -2247,7 +2358,7 @@ 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, ); @@ -2269,7 +2380,7 @@ For a listing of the available syntaxes, see the current L 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 -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) @@ -2287,7 +2398,7 @@ See the L documentation for a listing of all possible configura =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: @@ -2299,6 +2410,11 @@ similar to the following: 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 @@ -2505,7 +2621,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. -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 @@ -2545,7 +2661,7 @@ the core logic of the application. debug shift->dump_history; } - sub base_dir_abs { '/var/www/templates' } + sub template_path { '/var/www/templates' } sub base_dir_rel { 'content' } @@ -3079,12 +3195,12 @@ the original versions. Krassimir Berov - feedback and some warnings issues with POD examples. -=head1 AUTHOR - -Paul Seamons - =head1 LICENSE This module may be distributed under the same terms as Perl itself. +=head1 AUTHOR + +Paul Seamons + =cut