| 1 |
NAME |
| 2 |
CGI::Application::Plugin::Config::Simple - Add Config::Simple support to |
| 3 |
CGI::Application |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
in your CGI::Application based module |
| 7 |
|
| 8 |
use CGI::Application::Plugin::Config::Simple; |
| 9 |
|
| 10 |
sub cgiapp_init { |
| 11 |
my $self = shift; |
| 12 |
#set my config file |
| 13 |
$self->config_file('myapp.conf'); |
| 14 |
|
| 15 |
# |
| 16 |
#do other stuff |
| 17 |
# |
| 18 |
} |
| 19 |
|
| 20 |
#later on in a run mode |
| 21 |
sub run_mode1 { |
| 22 |
my $self = shift; |
| 23 |
|
| 24 |
#just get a single parameter from my config file |
| 25 |
my $value = $self->config_param('my_param'); |
| 26 |
|
| 27 |
#get a parameter in a block (if using ini style files) |
| 28 |
$value = $self->config_param('my_block.my_param'); |
| 29 |
|
| 30 |
#the entire config hash reference |
| 31 |
my $config_vars = $self->config_param(); |
| 32 |
|
| 33 |
#get my Config::Simple object for direct access |
| 34 |
my $config = $self->config; |
| 35 |
} |
| 36 |
|
| 37 |
DESCRIPTION |
| 38 |
This module acts as a plugin for Config::Simple to be easily used inside |
| 39 |
of a CGI::Application module. It does not provide every method available |
| 40 |
from Config::Simple but rather easy access to your configuration |
| 41 |
variables. It does however provide direct access to the underlying |
| 42 |
Config::General object created if you want to use it's full power. |
| 43 |
|
| 44 |
The module tries to make the getting and setting of configuration |
| 45 |
variables as easy as possible. Only three methods are exported into your |
| 46 |
CGI::Application module and they are described below. |
| 47 |
|
| 48 |
Before I wrote this module sometimes I would put my code that read in |
| 49 |
the configuration file into the cgiapp_init() or cgiapp_prerun() methods |
| 50 |
but then if I had a run mode that didn't need those config variables it |
| 51 |
was run anyway. This module helps to solve this is. The Config::Simple |
| 52 |
object is not created (and the config file is not read and parsed) until |
| 53 |
after your first call to config() or config_param() to either |
| 54 |
retrieve/set values, or get the Config::Simple object. This lazy loading |
| 55 |
idea came from Cees Hek's CGI::Application::Plugin::Session module. |
| 56 |
|
| 57 |
METHODS |
| 58 |
config_param() |
| 59 |
|
| 60 |
This method acts as an accessor/mutator for configuration variables |
| 61 |
coming from the configuration file. |
| 62 |
|
| 63 |
This method will behave in three different ways depending on how many |
| 64 |
parameters it is passed. If 0 parameters are passed then the entire |
| 65 |
config structure will be returned as a hash ref. If 1 parameters is |
| 66 |
passed then the value of that parameter in the config file will be |
| 67 |
returned. If more than 1 parameter is passed then it will treat them as |
| 68 |
name value pairs and will set the parameters in the config file |
| 69 |
accordingly. In this case, if we successfully set the parameters then a |
| 70 |
true value will be returned. |
| 71 |
|
| 72 |
#get the complete config hash |
| 73 |
my $config_hash = $self->config_param(); |
| 74 |
#just get one config value |
| 75 |
my $value = $self->config_param($parameter); |
| 76 |
#set multiple config values |
| 77 |
my $success = $self->config_param(param1 => $value1, param2 => $value2); |
| 78 |
|
| 79 |
This method uses Config::Simple so if you are using ini-files then you |
| 80 |
can set the values of variables inside blocks as well using the '.' |
| 81 |
notation. See Config::Simple; |
| 82 |
|
| 83 |
You must set the name of the configuration file either using the |
| 84 |
config_file() method or the CGIAPP_CONFIG_FILE environment variable |
| 85 |
before calling this method or it will 'die'. |
| 86 |
|
| 87 |
config() |
| 88 |
|
| 89 |
This method will return the underlying Config::Simple object for more |
| 90 |
direct use by your application. You must set the name of the |
| 91 |
configuration file either using the config_file() method or the |
| 92 |
CGIAPP_CONFIG_FILE environment variable before calling this method or it |
| 93 |
will 'die'. |
| 94 |
|
| 95 |
my $conf = $self->config(); |
| 96 |
|
| 97 |
config_file([$file_name]) |
| 98 |
|
| 99 |
This method acts as an accessor/mutator to either get the name of the |
| 100 |
current config file or to change/initialize it. This method must be |
| 101 |
called to initialize the name of the config file before any call can be |
| 102 |
made to either config() or config_param() unless the |
| 103 |
'CGIAPP_CONFIG_FILE' environment variable has been set. If this |
| 104 |
environment variable is set it will be used as the initial value of the |
| 105 |
config file. This is useful if we are running in a mod_perl environment |
| 106 |
when can use a statement like this in your httpd.conf file: |
| 107 |
|
| 108 |
PerlSetEnv CGIAPP_CONFIG_FILE /path/to/my/conf |
| 109 |
|
| 110 |
It is typical to set the name of the config file in the cgiapp_init() |
| 111 |
phase of your application. |
| 112 |
|
| 113 |
If a value is passed as a parameter then the config file with that name |
| 114 |
is used. It will always return the name of the current config file. |
| 115 |
|
| 116 |
#get the value of the CGIAPP_CONFIG_FILE environment variable (if there is one) |
| 117 |
#since we haven't set the config file's name with config_file() yet. |
| 118 |
my $file_name = $self->config_file(); |
| 119 |
|
| 120 |
#set the config file's name |
| 121 |
$self->config_file('myapp.conf'); |
| 122 |
|
| 123 |
#get the name of the config file |
| 124 |
$file_name = $self->config_file(); |
| 125 |
|
| 126 |
CAVEATS |
| 127 |
The CGI::Application object is implemented as a hash and we store the |
| 128 |
variables used by this module's methods inside of it as a hash named |
| 129 |
__CONFIG_SIMPLE. If you use any other CGI::Application plugins there |
| 130 |
would be problems if they also used $self->{__CONFIG_SIMPLE} but in |
| 131 |
practice this should never actually happen. |
| 132 |
|
| 133 |
AUTHOR |
| 134 |
Michael Peters <[email protected]> |
| 135 |
|
| 136 |
Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my |
| 137 |
work on this module |
| 138 |
|
| 139 |
SEE ALSO |
| 140 |
* CGI::Application |
| 141 |
* Config::Simple |
| 142 |
LICENSE |
| 143 |
This library is free software; you can redistribute it and/or modify it |
| 144 |
under the same terms as Perl itself. |
| 145 |
|