X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=lib%2FCGI%2FEx%2FApp.pod;h=59c5e21a35c0cafaadfb295c59beaddf588b8901;hb=b6e904ff7b346908d0662aae9a9c5f7d976dd85e;hp=0188cdc40e6c0d38d508384a491d956f05fd4094;hpb=aa030874456c91d688e6c9b25e82d2bf9575ea6f;p=chaz%2Fp5-CGI-Ex diff --git a/lib/CGI/Ex/App.pod b/lib/CGI/Ex/App.pod index 0188cdc..59c5e21 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 @@ -202,6 +204,9 @@ The nav_loop method will run as follows: foreach step of path { + ->require_auth (hook) + # exits nav_loop if true + ->morph # check ->allow_morph # check ->allow_nested_morph @@ -242,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) @@ -314,31 +319,31 @@ The default out of the box configuration will map URIs to steps as follows: # 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 @@ -348,12 +353,12 @@ The default out of the box configuration will map URIs to steps as follows: $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 @@ -371,7 +376,7 @@ that the following method is installed in your script. ]; } - 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 @@ -381,7 +386,7 @@ that the following method is installed in your script. 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 @@ -391,19 +396,19 @@ that the following method is installed in your script. 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 @@ -440,7 +445,7 @@ for more information about the many ways you can validate your data. 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 { @@ -564,7 +569,9 @@ validation files). 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 +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. @@ -584,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 @@ -625,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 @@ -641,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 @@ -655,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. @@ -670,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 @@ -1045,12 +1053,12 @@ See the get_valid_auth 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. -Default value is "". +Default value is ['.']. For example, to pass multiple paths, you would use something similar to the following: @@ -1059,27 +1067,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. @@ -1108,13 +1118,74 @@ 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'}. + +=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 +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. + +=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_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. +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. @@ -1171,6 +1242,7 @@ called is "view". 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", @@ -1196,6 +1268,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 @@ -1229,40 +1306,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. @@ -1286,15 +1329,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' @@ -1307,18 +1350,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. @@ -1362,12 +1406,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 @@ -1382,8 +1436,7 @@ to the authentication object during the get_valid_auth method. =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 @@ -1428,6 +1481,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 @@ -1520,6 +1579,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 @@ -1527,6 +1599,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 @@ -1622,6 +1710,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 @@ -1772,8 +1868,9 @@ This starts the process flow for the path and its steps. =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) @@ -1963,16 +2060,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. @@ -2022,45 +2130,104 @@ had been successfully validated and acted upon. 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) @@ -2156,7 +2323,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 @@ -2182,7 +2349,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, ); @@ -2204,7 +2371,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) @@ -2222,7 +2389,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: @@ -2234,6 +2401,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 @@ -2440,7 +2612,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 @@ -2480,7 +2652,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' } @@ -2601,7 +2773,7 @@ the core logic of the application. 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'}, @@ -2983,6 +3155,18 @@ will cause all steps to require validation): 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 perldoc. @@ -2992,20 +3176,22 @@ Also see the L 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. + James Lance - design feedback, bugfixing, feature suggestions. -=head1 AUTHOR - -Paul Seamons + 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 + =cut