view release on metacpan or  search on metacpan

lib/App/devguide.pod  view on Meta::CPAN

=head2 App->context()

If the "contextClass" variable is in the argument hash, it is used.
Otherwise, if the "app" program is running in the CGI context
(HTTP_USER_AGENT environment variable is set) or at the
command line, the App::Context::CGI class
will be assumed.

The code for the selected class is loaded and a $context
of the appropriate class is instantiated.
For the CGI context, the App::Context::CGI->new()
method is called, and the arguments of the context() method
call (%main::conf, in this case) are passed on to it.

=head2 App::Context::CGI->new()

The constructor (new()) for App::Context::CGI is actually provided
by its parent class, App::Context.

If the "configClass" was not specified in the arguments
(%main::conf, in this case), App::Config::File is assumed.
It is instantiated, once again passing on the hash of initialization args,
and the result is stored in $self->{config};

Then the App::Context::CGI->init() method is called to
complete the $context constructor.  A CGI object is created
and added to the %args to be passed on to Session instantiation.

If the "sessionClass" was not specified in the arguments,
App::Session::HTMLHidden is assumed.
It is instantiated, once again passing on the hash of initialization args,
and the result is stored in $self->{session};

=head2 App::Config::File->new()

The constructor (new()) for App::Config::File is actually provided
by its grand-parent class, App::Reference.
It creates a reference by calling App::Config::File->create(),
blesses it into the class, calls init()
(App::Reference->init()) which does nothing,
and then returns the constructed Config::File object.

The Config::File->create() method loads data from a configuration
file and returns the reference to a hash.  But first it has to find
the file and deserialize it.

If the "configFile" was not specified in the arguments
(%main::conf, in this case), the following files are searched for in
order.  (If the script were renamed to "foo", it would look for "foo"
variants of the files instead of "app" variants of the files.)

   1. app.pl           2. config.pl
   3. app.xml          4. config.xml
   5. app.ini          6. config.ini
   7. app.properties   8. config.properties
   9. app.perl        10. config.perl
  11. app.conf        12. config.conf

By convention, "config.pl" is the config file for App CGI scripts.
However, the first file that is found is assumed to be the relevant config file.
If no config file is found or if it cannot be opened, an exception is thrown.
Otherwise, the text is read in from the file and deserialized into
a hash reference.

If the "configSerializerClass" was not specified in the arguments
(%main::conf, in this case), the file suffix for the config file
is used to determine the Serializer class to use for deserialization.

  pl          # use "eval" instead of a serializer
  perl        # App::Serializer::Dumper (like "pl" but use a serializer)
  xml         # App::Serializer::XMLSimple
  ini         # App::Serializer::Ini
  properties  # App::Serializer::Properties
  conf        # App::Serializer::Properties
  stor        # App::Serializer::Storable

If the file is a .pl file, no serializer is implied.  It is just eval'ed.
(It must have "$var =" as the first non-whitespace text in the file,
where "var" is any variable name.)

If a Serializer is specified or implied, a serializer is instantiated
and the config file data is deserialized into a hash reference.

The resulting hash reference is returned and stored in $context->{config}.

=head2 App::Context::CGI->init()

The init() method is where the CGI object is created, parsing the
environment variables and STDIN which are
part of the CGI runtime environment.

For debugging purposes, a "debugmode" variable is checked in the 
%args (i.e. %main::conf) to see if
special processing with the CGI object should be performed.
If "debugmode" is "record", the CGI objects and the %ENV hash will
be saved to files ("debug.vars" and "debug.env", respectively).
If "debugmode" is "replay", the current %ENV and CGI will be
cleared and loaded from the files from a previously recorded request.

Another sort of debugging is initialized if the "debug"
variable is supplied in the %args.  This turns on a global debug
flag ($App::DEBUG) and sets the debug scope
(which classes or methods should produce debug output).

To support migration of code, the CGI object can also be passed into
the App->context() method as an argument, and it will be used rather
than trying to create a new one.  However, this is not the execution
path being described here.

=head2 App::Session::HTMLHidden->new()

The constructor (new()) for App::Session::HTMLHidden is actually provided
by its grand-parent class, App::Reference.
It creates a hash reference by calling App::Reference->create(),
blesses it into the class, calls init()
(App::Session::HTMLHidden->init()),
and then returns the constructed Session::HTMLHidden object.

The init() method looks at the CGI variables in the request
and restores the session state information from the variable
named "app.sessiondata" (and "app.sessiondata[2..n]").