Dogcows Code - chaz/p5-CGI-Ex/blob - lib/CGI/Ex/App/Constants.pm

   1 package CGI::Ex::App::Constants;
   2
   3 =head1 NAME
   4
   5 CGI::Ex::App::Constants - Easier access to magic App values
   6
   7 =cut
   8
   9 use vars qw(%constants @EXPORT @EXPORT_OK %EXPORT_TAGS $VERSION);
  10 use strict;
  11 use warnings;
  12 use Exporter qw(import); # allow for goto from CGI::Ex::App
  13 use base qw(Exporter);
  14
  15 $VERSION = '2.37';
  16
  17 BEGIN {
  18 my $all = {
  19     App__allow_morph__allow_reblessing            => '1 - This will allow changing MyApp to MyApp::MyStep when on step my_step',
  20     App__allow_morph__force_reblessing            => '2 - This will force changing MyApp to MyApp::MyStep when on step my_step',
  21     App__allow_morph__no_auto_reblessing          => '0 - We will not look for another package to bless into',
  22     App__auth_args       => 'should return a hashref of args to pass to auth_obj',
  23     App__auth_obj        => 'should return a auth_obj - used when require_auth is true',
  24     App__file_print      => 'should file path, or be a scalar reference to the template to print',
  25     App__file_val        => 'should return a file path or a hash_validation hashref (default is {})',
  26     App__fill_args       => 'should return a hashref of args to pass to CGI::Ex::Fill::fill (default {})',
  27     App__fill_template   => 'void context - uses hashes to fill the template',
  28     App__finalize__failed_and_show_page           => '0 - additional processing failed so show the page',
  29     App__finalize__finished_and_move_to_next_step => '1 - default',
  30     App__finalize__finished_but_show_page         => '',
  31     App__form_name       => 'must return a name',
  32     App__generate_form   => 'return coderef to form that can generate the form based on hash_validation',
  33     App__get_valid_auth  => 'needs to return a CGI::Ex::Auth::Data object (which can be either true or false)',
  34     App__hash_base       => 'should return a hashref',
  35     App__hash_common     => 'should return a hashref',
  36     App__hash_errors     => 'should return a hashref of errors that occurred on the page (normally populated via add_error)',
  37     App__hash_fill       => 'should return a hashref of things to get filled in forms in the template',
  38     App__hash_form       => 'should return a hashref - default is $self->form - normally not overridden',
  39     App__hash_swap       => 'should return a hashref of things to process in the template',
  40     App__hash_validation => 'should return a CGI::Ex::Validate compatible hashref or {} (default empty hashref means all submitted information is always ok to finalize)',
  41     App__info_complete__fail_and_show_page        => '0 - we were not ready to finalize the data either because there was not any, or it failed validation',
  42     App__info_complete__succeed_and_run_finalize  => '1 - occurs because data is ready and is good or because there was no hash_validation to test against',
  43     App__js_validation   => 'return coderef to form that will generate javascript based validation based on hash_validation',
  44     App__morph           => 'void context - used to rebless into other package',
  45     App__morph_package   => 'return package name derivative for use when allow_morph is true (see perldoc on morph, morph_package, morph_base)',
  46     App__name_module     => 'return name of application - used when mapping to file_system (see file_print, file_val, conf_file)',
  47     App__name_step       => 'return step of current request (default is $current_step) - used for mapping to file_system',
  48     App__path_info_map   => 'return arrayref of matching arrayrefs - first one matching is used - others abort (only applies to current step)',
  49     App__path_info_map_base                       => 'return arrayref of matching arrayrefs - first one matching is used - others abort (ran before nav_loop)',
  50     App__post_loop__do_not_recurse                => '1 - can be used to abort navigation if the loop is about to recurse to default step - no additional headers will be sent',
  51     App__post_loop__recurse_loop                  => 0,
  52     App__post_navigate                            => 'void context - called at the end of navigation unless $self->{_no_post_navigate} is true',
  53     App__post_print                               => 'void context - run code after page is diplayed to user',
  54     App__post_step__abort_navigation_flow         => '1 - no additional headers will be sent',
  55     App__post_step__move_to_next_step             => 0,
  56     App__pre_loop__begin_loop                     => 0,
  57     App__pre_loop__do_not_loop                    => '1 - can be used to abort the nav_loop call early on - no additional headers will be sent',
  58     App__pre_navigate__continue                   => '0 - go ahead and navigate the request',
  59     App__pre_navigate__stop                       => '1 - can be used to abort the navigate call early on - no additional headers will be sent',
  60     App__pre_step__abort_navigation_flow          => '1 - no additional headers will be sent',
  61     App__pre_step__continue_current_step          => 0,
  62     App__prepare__fail_and_show_page              => 0,
  63     App__prepare__ok_move_to_info_complete        => '1 - default',
  64     App__prepared_print                           => 'void context - gathers hashes - then calls print',
  65     App__print                                    => 'void context - uses hashes to swap and fill file_print, then calls print_out',
  66     App__print_out                                => 'void context - prints headers and prepared content',
  67     App__ready_validate__data_not_ready_show_page => '0 - either validate_when_data was alse and it was a GET',
  68     App__ready_validate__ready_to_validate_data   => '1 - either validate_when_data was true or we received a POST',
  69     App__refine_path                              => 'void context - manipulates the path after a step.  set_ready_validate(0) if next_step is true',
  70     App__require_auth__needs_authentication       => 1,
  71     App__require_auth__no_authentication_needed   => 0,
  72     App__run_step__move_to_next_step              => 0,
  73     App__run_step__request_completed              => '1 - no additional headers will be sent',
  74     App__set_ready_validate                       => 'void context - sets ready_validate to true (fakes REQUEST_METHOD to POST OR GET)',
  75     App__skip__continue_current_step              => 0,
  76     App__skip__move_to_next_step                  => '1 - make sure the path has a next step or it will default to main',
  77     App__swap_template   => 'should return swapped template (passed $step, $file, $swap)',
  78     App__template_args   => 'should return a hashref to pass to template_obj',
  79     App__template_obj    => 'should return a Template::Alloy type object for swapping the template (passed template_args)',
  80     App__unmorph         => 'void context - re-reblesses back to the original class before morph',
  81     App__val_args        => 'should return a hashref to pass to val_obj',
  82     App__val_obj         => 'should return a CGI::Ex::Validate type object for validating the data',
  83     App__validate__data_was_ok                    => '1 - request data either passed hash_validation or hash_validation was empty - make info_complete succeed',
  84     App__validate__failed_validation              => 0,
  85     App__validate_when_data__succeed_if_data      => '1 - will be true if there is no hash_validation, or a key from hash_validation was in the form',
  86     App__validate_when_data__use_ready_validate   => 0,
  87 };
  88
  89 no strict 'refs';
  90 while (my ($method, $val) = each %$all) {
  91     my ($prefix, $tag, $name) = split /__/, $method;
  92     if (! $name) {
  93         $constants{$tag} = $val;
  94         next;
  95     }
  96     $constants{$tag}->{$name} = $val;
  97
  98     my $tags = $EXPORT_TAGS{"App__${tag}"} ||= [];
  99     push @{ $EXPORT_TAGS{"App"} }, $method;
 100     push @$tags,     $method;
 101     push @EXPORT,    $method;
 102     push @EXPORT_OK, $method;
 103
 104     $val =~ s/\s+-.*//;
 105     $val *= 1 if $val =~ /^\d+$/;
 106     *{__PACKAGE__."::$method"} = sub () { $val };
 107 }
 108
 109 }; # end of BEGIN
 110
 111 sub constants {
 112     print __PACKAGE__."\n---------------------\n";
 113     no strict 'refs';
 114     for (sort @EXPORT_OK) {
 115         print "$_ (".$_->().")\n";
 116     }
 117 }
 118
 119 sub tags {
 120     print __PACKAGE__." Tags\n---------------------\n";
 121     print "$_\n" for sort keys %EXPORT_TAGS;
 122 }
 123
 124 sub details {
 125     require Data::Dumper;
 126     local $Data::Dumper::SortKeys = 1;
 127     print Data::Dumper::Dumper(\%constants);
 128 }
 129
 130 1;
 131
 132 __END__
 133
 134 =head1 SYNOPSIS
 135
 136     use base qw(CGI::Ex::App);
 137     use CGI::Ex::App::Constants; # load all
 138     use CGI::Ex::App::Constants qw(:App); # also load all
 139     use CGI::Ex::App qw(:App); # also load all
 140
 141     __PACKAGE__->navigate;
 142
 143     sub main_run_step {
 144         my $self = shift;
 145
 146         $self->cgix->print_content_type;
 147         print "Hello world\n";
 148
 149         return App__run_step__request_completed;
 150     }
 151
 152
 153     # you can request only certain tags
 154     use CGI::Ex::App::Constants qw(:App__run_step);
 155     use CGI::Ex::App qw(:App__run_step);
 156
 157     # you can request only certain constants
 158     use CGI::Ex::App::Constants qw(App__run_step__request_completed);
 159     use CGI::Ex::App qw(App__run_step__request_completed);
 160
 161 =head1 CONSTANTS
 162
 163 To see a list of the importable tags type:
 164
 165    perl -MCGI::Ex::App::Constants -e 'CGI::Ex::App::Constants::tags()'
 166
 167 To see a list of the importable constants type:
 168
 169    perl -MCGI::Ex::App::Constants -e 'CGI::Ex::App::Constants::constants()'
 170
 171 To see a little more discussion about the hooks and other CGI::Ex::App options type:
 172
 173    perl -MCGI::Ex::App::Constants -e 'CGI::Ex::App::Constants::details()'
 174
 175 =cut