NAME

       CGI::Application::Plugin::Config::Simple - Add Config::Simple support to CGI::Application

SYNOPSIS

       in your CGI::Application based module

               use CGI::Application::Plugin::Config::Simple;

           sub cgiapp_init {
                 my $self = shift;
                 #set my config file
                 $self->config_file('myapp.conf');

                 #
                 #do other stuff
                 #
               }

               #later on in a run mode
               sub run_mode1 {
                 my $self = shift;

                 #just get a single parameter from my config file
                 my $value = $self->config_param('my_param');

                 #get a parameter in a block (if using ini style files)
                 $value = $self->config_param('my_block.my_param');

                 #the entire config hash reference
                 my $config_vars = $self->config_param();

                 #get my Config::Simple object for direct access
                 my $config = $self->config;
               }

DESCRIPTION

       This module acts as a plugin for Config::Simple to be easily used inside of a
       CGI::Application module. It does not provide every method available from Config::Simple
       but rather easy access to your configuration variables. It does however provide direct
       access to the underlying Config::General object created if you want to use it's full
       power.

       The module tries to make the getting and setting of configuration variables as easy as
       possible. Only three methods are exported into your CGI::Application module and they are
       described below.

       Before I wrote this module sometimes I would put my code that read in the configuration
       file into the cgiapp_init() or cgiapp_prerun() methods but then if I had a run mode that
       didn't need those config variables it was run anyway. This module helps to solve this is.
       The Config::Simple object is not created (and the config file is not read and parsed)
       until after your first call to config() or config_param() to either retrieve/set values,
       or get the Config::Simple object. This lazy loading idea came from Cees Hek's
       CGI::Application::Plugin::Session module.

METHODS

   config_param()
       This method acts as an accessor/mutator for configuration variables coming from the
       configuration file.

       This method will behave in three different ways depending on how many parameters it is
       passed. If 0 parameters are passed then the entire config structure will be returned as a
       hash ref. If 1 parameters is passed then the value of that parameter in the config file
       will be returned. If more than 1 parameter is passed then it will treat them as name value
       pairs and will set the parameters in the config file accordingly. In this case, if we
       successfully set the parameters then a true value will be returned.

               #get the complete config hash
               my $config_hash = $self->config_param();
               #just get one config value
               my $value = $self->config_param($parameter);
               #set multiple config values
               my $success = $self->config_param(param1 => $value1, param2 => $value2);

       This method uses Config::Simple so if you are using ini-files then you can set the values
       of variables inside blocks as well using the '.' notation. See Config::Simple;

       You must set the name of the configuration file either using the config_file() method or
       the CGIAPP_CONFIG_FILE environment variable before calling this method or it will 'die'.

   config()
       This method will return the underlying Config::Simple object for more direct use by your
       application. You must set the name of the configuration file either using the
       config_file() method or the CGIAPP_CONFIG_FILE environment variable before calling this
       method or it will 'die'.

               my $conf = $self->config();

   config_file([$file_name])
       This method acts as an accessor/mutator to either get the name of the current config file
       or to change/initialize it. This method must be called to initialize the name of the
       config file before any call can be made to either config() or config_param() unless the
       'CGIAPP_CONFIG_FILE' environment variable has been set. If this environment variable is
       set it will be used as the initial value of the config file. This is useful if we are
       running in a mod_perl environment when can use a statement like this in your httpd.conf
       file:

               PerlSetEnv  CGIAPP_CONFIG_FILE  /path/to/my/conf

       It is typical to set the name of the config file in the cgiapp_init() phase of your
       application.

       If a value is passed as a parameter then the config file with that name is used. It will
       always return the name of the current config file.

               #get the value of the CGIAPP_CONFIG_FILE environment variable (if there is one)
               #since we haven't set the config file's name with config_file() yet.
               my $file_name = $self->config_file();

               #set the config file's name
               $self->config_file('myapp.conf');

               #get the name of the config file
               $file_name = $self->config_file();

CAVEATS

       The CGI::Application object is implemented as a hash and we store the variables used by
       this module's methods inside of it as a hash named __CONFIG_SIMPLE. If you use any other
       CGI::Application plugins there would be problems if they also used
       $self->{__CONFIG_SIMPLE} but in practice this should never actually happen.

AUTHOR

       Michael Peters <mpeters@plusthree.com>

       Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my work on this module

SEE ALSO

       •       CGI::Application

       •       Config::Simple

LICENSE

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

perl v5.14.2                                2011-11-CGI::Application::Plugin::Config::Simple(3pm)