view release on metacpan or  search on metacpan

Path.pm  view on Meta::CPAN

CGI::Ex::Validate by default.  See the L<CGI::Ex::Validate> for details.  You need to put a js_validation tag on 
your page to get the validation.  The form name is MYFORM by default, but can be changed by setting $self->{form_name}.

=head1 generate_form

The goal is that the programmer just look at $self->form for form or session information.  
To help facilitate this goal, I use the following

  $self->this_form           - form from the current hit
  $self->{session_only} = [] - things that get deleted from this_form and get inserted from the session
  $self->{session_wins} = [] - this_form wins by default, set this if you want something just from the session

The code then sets the form with the following line

  $self->{form} = {%{$self->session}, %{$this_form}, %{$form}};

=head1 Session management

CGI::Path uses Apache::Session::File by default for session management.  If you use this default you will need to write the following methods

  session_dir      - returns the directory where the session files will go
  session_lock_dir - returns the directory where the session lock files will go

One failing of Apache::Session::File is it not working so hot over NFS.  Sorry, patches were not readily accepted.

=head1 magic_fill

magic_fill is written to help aid in rapid development.  It is a simple, space-delimited file of key/value pairs, like so

  address                       123 Fake Street
  email,email_address,from      cpan@spack.net

I split on the first white space, then split on commas for the key names.  In the above example, I would end up with a ref like this

  {
    address       => '123 Fake Street',
    email         => 'cpan@spack.net',
    email_address => 'cpan@spack.net',
    from          => 'cpan@spack.net',
  }

Once I have a ref, those values will get filled into forms as pages are displayed.  Makes it nice to fill forms with dummy data and test the
flow of your script.

magic_fill is turned off by default.  The method allow_magic_fill determines if magic_fill is on.  By default, allow_magic_fill just looks at
$self->{allow_magic_fill} and returns true or false accordingly.  magic_fill_filename points to the location of your file.

When you new up your CGI::Path object you just need to do something like the following

my $self = CGI::Path->new({
  allow_magic_fill      => 1,
  magic_fill_filename   => "/path/to/magic_fill_file",
});

You can use variable values using the magic_fill_interpolation_hash.  By default, you can use Template::Toolkit tags, like so

currenttime            [% localtime %]

Currently, the following are included by default in the magic_fill_interpolation_hash

  script    - a good guess at the name of your script
  _script   - the stuff after the last _ in the above script
  localtime - scalar (localtime),
  time      - time,

I also include %ENV

Two other keys are not available by default, based on micro seconds namely

  micro      - join(".", &Time::HiRes::gettimeofday()), which really tries to get you a unique value
  micro_part - (&Time::HiRes::gettimeofday())[1];, which is just the micro seconds

To make these swaps available you need to set $self->{allow_magic_micro} to a true value.

=head1 allow_history

At least partly due to the sometimes complicated nature of paths, I have found it difficult to debug what is 
actually going on during navigation.  The history features of CGI::Path aim to try and make things a little 
easier to follow.  The goal is for each step to get added to the history and get spit out to a popup window,
showing in hopefully easy to read fashion, what happened that led to the step being printed.

To turn on the history features, the allow_history method needs to return true.  The default method checks to see
that both $self->{allow_history} and $self->form->{$self->{history_key}} are true.  The default history_key is named
history.   When CGI::Path finds that history is allowed $self->{history_key} gets saved to the session, which means
the history window will pop up for each step so long as you stay in the session, and don't stop allowing history.

This is a rather new feature and I have now likely missed adding history to a few steps.  Please let me know where
other history might be useful.

=head1 OBJECT KEYS

Here is a listing of some keys in the object, listed with default values.

  ### turn on keeping history, $self->form->{$self->{history_key}} also needs to be true
  allow_history         => 0,
  ### history_key is the key from the form to turn on history
  history_key           => 'history',

  ### turn on magic fill
  allow_magic_fill      => 0,
  ### turn on micro seconds, which requires Time::HiRes
  allow_magic_micro     => 0,
  ### full path to the magic_fill file
  magic_fill_filename   => '',

  ### if a given page doesn't exist, create it using create_page method
  create_page           => 0,

  ### form_name is used for javascript
  form_name             => 'MYFORM',

  ### extension for htm files
  htm_extension         => 'htm',
  ### extension for validation files 
  val_extension         => 'val',

  ### if the user submits an empty form, keep the session
  keep_no_form_session  => 0,

  ### 'fake keys', stuff that gets skipped from the session
  not_a_real_key        => [qw(_begin_time _http_referer _printed_pages _session_id _submit _validated)],