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=59c5e21a35c0cafaadfb295c59beaddf588b8901;hb=ed00221d27dfab1e82ec2ea040ab4c399a91c545;hpb=b6e904ff7b346908d0662aae9a9c5f7d976dd85e diff --git a/lib/CGI/Ex/App.pod b/lib/CGI/Ex/App.pod index 59c5e21..2967cbe 100644 --- a/lib/CGI/Ex/App.pod +++ b/lib/CGI/Ex/App.pod @@ -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,6 +256,7 @@ 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) @@ -981,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 @@ -1028,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. @@ -1051,6 +1053,11 @@ 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, validation and conf files. @@ -1139,24 +1146,28 @@ 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->conf_ext added on. For example, if name_module -returns "my_app" and conf_ext returns "ini" the value returned will +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 conf_ext may be any of those extentions understood by CGI::Ex::Conf. - -=item conf_ext - -Used by the default conf_file method. Defaults to $self->{'conf_ext'} which -defaults to 'pl' meaning that the read configuration file should return a -valid perl hashref. +The ext_conf may be any of those extentions understood by CGI::Ex::Conf. =item conf_obj @@ -1172,13 +1183,6 @@ 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_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_validation Used by default conf method. @@ -1284,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. @@ -2093,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 @@ -2269,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; @@ -2457,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