X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fp5-CGI-Ex;a=blobdiff_plain;f=lib%2FCGI%2FEx%2FApp.pod;h=2967cbe3972d4bdf5caa4aff09db3c0c9978b5e3;hp=3b93a78383b9d490976b7f1e6456d9442c5c2cfe;hb=ed00221d27dfab1e82ec2ea040ab4c399a91c545;hpb=ba92ea5b36cbcd9c03016491dfb06dfc74baf409 diff --git a/lib/CGI/Ex/App.pod b/lib/CGI/Ex/App.pod index 3b93a78..2967cbe 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 }} } @@ -208,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 @@ -256,11 +256,12 @@ during the run_step 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) - ->base_dir_abs + ->vob_path (defaults to template_path) ->base_dir_rel ->name_module ->name_step @@ -591,13 +592,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 @@ -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: - base_dir_abs /home/user/templates + template_path /home/user/templates 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: - base_dir_abs /home/user/templates + template_path /home/user/templates 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({ - 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. @@ -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: - base_dir_abs /home/user/templates + template_path /home/user/templates base_dir_rel name_module content/my_app @@ -980,7 +982,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 @@ -1027,7 +1029,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. @@ -1050,14 +1053,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: @@ -1066,27 +1074,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. @@ -1122,6 +1132,64 @@ The following items will be cleared: 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. @@ -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. +=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. @@ -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 -".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' @@ -1286,12 +1360,13 @@ 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. @@ -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. +=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 @@ -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. +=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 @@ -1977,16 +2070,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. @@ -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. +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 @@ -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 -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; @@ -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 -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 @@ -2255,7 +2369,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, ); @@ -2277,7 +2391,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) @@ -2295,7 +2409,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: @@ -2307,6 +2421,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 @@ -2358,6 +2477,14 @@ path. A validation item of: 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 @@ -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. -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 @@ -2553,7 +2680,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' }