Provided by: libjifty-perl_1.10518+dfsg-3ubuntu1_all 
NAME
Jifty::Config - the configuration handler for Jifty
SYNOPSIS
# in your application
my $app_name = Jifty->config->framework('ApplicationName');
my $frobber = Jifty->config->app('PreferredFrobnicator');
# sub classing
package MyApp::Config;
use base 'Jifty::Config';
sub post_load {
my $self = shift;
my $stash = $self->stash; # full config in a hash
... do something with options ...
$self->stash( $stash ); # save config
}
1;
DESCRIPTION
This class is automatically loaded during Jifty startup. It contains the configuration information loaded
from the config.yml file (generally stored in the etc directory of your application, but see "load" for
the details). This configuration file is stored in YAML format.
This configuration file contains two major sections named "framework" and "application". The framework
section contains Jifty-specific configuration options and the application section contains whatever
configuration options you want to use with your application. (I.e., if there's any configuration
information your application needs to know at startup, this is a good place to put it.)
Usually you don't need to know anything about this class except app and framework methods and about
various config files and order in which they are loaded what described in "load".
ACCESSING CONFIG
framework VARIABLE
Get the framework configuration variable "VARIABLE".
Jifty->config->framework('ApplicationName')
app VARIABLE
Get the application configuration variable "VARIABLE".
Jifty->config->framework('MyOption');
contextual_get CONTEXT VARIABLE
Gets the configuration variable in the context "CONTEXT". The "CONTEXT" is a slash-separated list of hash
keys. For example, the following might return "SQLite":
contextual_get('/framework/Database', 'Driver')
LOADING
new PARAMHASH
In general, you never need to call this, just use:
Jifty->config
in your application.
This class method instantiates a new "Jifty::Config" object.
PARAMHASH currently takes a single option
load_config
This boolean defaults to true. If true, "load" will be called upon initialization. Using this object
without loading prevents sub-classing and only makes sense if you want to generate default config for
a new jifty application or something like that.
load
Loads all config files for your application and initializes application level sub-class.
Called from new, takes no arguments, returns nothing interesting, but do the following:
Application config
Jifty first loads the main configuration file for the application, looking for the "JIFTY_CONFIG"
environment variable or "etc/config.yml" under the application's base directory.
Vendor config
It uses the main configuration file to find a vendor configuration file -- if it doesn't find a framework
variable named 'VendorConfig', it will use the "JIFTY_VENDOR_CONFIG" environment variable.
Site config
After loading the vendor configuration file (if it exists), the framework will look for a site
configuration file, specified in either the framework's "SiteConfig" or the "JIFTY_SITE_CONFIG"
environment variable. (Usually in "etc/site_config.yml".)
Test config(s)
After loading the site configuration file (if it exists), the framework will look for a test
configuration file, specified in either the framework's "TestConfig" or the "JIFTY_TEST_CONFIG"
environment variable.
Note that the test config may be drawn from several files if you use Jifty::Test. See the documentation
of Jifty::Test::load_test_configs.
Options clobbering
Values in the test configuration will clobber the site configuration. Values in the site configuration
file clobber those in the vendor configuration file. Values in the vendor configuration file clobber
those in the application configuration file. (See "WHY SO MANY FILES" for a deeper search for truth on
this matter.)
Guess defaults
Once we're all done loading from files, several defaults are assumed based on the name of the application
-- see "guess".
Reblessing into application's sub-class
OK, config is ready. Rebless this object into "YourApp::Config" class and call "post_load" hook, so you
can do some tricks detailed in "SUB-CLASSING".
Another hook
After we have the config file, we call the coderef in $Jifty::Config::postload, if it exists. This last
bit is generally used by the test harness to do a little extra work.
SPECIAL PER-VALUE PROCESSING
If a value begins and ends with "%" (e.g., "%bin/foo%"), converts it with "Jifty::Util/absolute_path" to
an absolute path. This is typically unnecessary, but helpful for configuration variables such as
"MailerArgs" that only sometimes specify files.
merge NEW, [FALLBACK]
Merges the given "NEW" hashref into the stash, with values taking precedence over pre-existing ones from
"FALLBACK", which defaults to "stash". This also deals with special cases (MailerArgs, Handlers.View)
where array reference contents should be replaced, not concatenated.
post_load
Helper hook for "SUB-CLASSING" and post processing config. At this point does nothing by default. That
may be changed so do something like:
sub post_load {
my $self = shift;
$self->post_load( @_ );
...
}
load_file PATH
Loads a YAML configuration file and returns a hashref to that file's data.
OTHER METHODS
stash
It's documented only for "SUB-CLASSING".
Returns the current config as a hash reference (see below). Plenty of code considers Jifty's config as a
static thing, so don't mess with it in run-time.
{
framework => {
...
},
application => {
...
},
}
This method as well can be used to set a new config:
$config->stash( $new_stash );
guess
Attempts to guess (and return) a configuration hash based solely on what we already know. (Often, in the
complete absence of a configuration file). It uses the name of the directory containing the Jifty binary
as a default for "ApplicationName" if it can't find one.
initial_config
Returns a default guessed config for a new application.
See Jifty::Script::App.
update_config $CONFIG
Takes an application's configuration as a hashref. Right now, it just sets up plugins that match an
older jifty version's defaults
defaults
We have a couple default values that shouldn't be included in the "guessed" config, as that routine is
used when initializing a new application. Generally, these are platform-specific file locations.
SUB-CLASSING
Template for sub-classing you can find in "SYNOPSIS".
Application config may have ApplicationClass or ApplicationName options, so it's important to understand
that your class goes into game later. Read </load> to understand when "YourApp::Config" class is loaded.
Use "stash" method to get and/or change config.
"post_load" hook usually is all you want to (can :) ) sub class. Other methods most probably called
before your class can operate.
Sub-classing may be useful for:
• validation
For example check if file or module exists.
• canonicalization
For example turn relative paths into absolute or translate all possible variants of an option into a
canonical structure
• generation
For example generate often used constructions based on other options, user of your app can even don't
know about them
• config upgrades
Jifty has ConfigVersion option you may want to implement something like that in your apps
Sub-classing is definitely not for:
• default values
You have so many files to allow users of your app and you to override defaults.
• anything else but configuration
WHY SO MANY FILES
The Jifty configuration can be loaded from many locations. This breakdown allows for configuration files
to be layered on top of each other for advanced deployments.
This section hopes to explain the intended purpose of each configuration file.
APPLICATION
The first configuration file loaded is the application configuration. This file provides the basis for
the rest of the configuration loaded. The purpose of this file is for storing the primary application-
specific configuration and defaults.
This can be used as the sole configuration file on a simple deployment. In a complex environment,
however, this file may be considered read-only to be overridden by other files, allowing the later files
to customize the configuration at each level.
VENDOR
The vendor configuration file is loaded and overrides settings in the application configuration. This is
an intermediate level in the configuration. It overrides any defaults specified in the application
configuration, but is itself overridden by the site configuration.
This provides an additional layer of abstraction for truly complicated deployments. A developer may
provide a particular Jifty application (such as the Wifty wiki available from Best Practical Solutions)
for download. A system administrator may have a standard set of configuration overrides to use on several
different deployments that can be set using the vendor configuration, which can then be further
overridden by each deployment using a site configuration. Several installations of the application might
even share the vendor configuration file.
SITE
The site configuration allows for specific overrides of the application and vendor configuration. For
example, a particular Jifty application might define all the application defaults in the application
configuration file. Then, each administrator that has downloaded that application and is installing it
locally might customize the configuration for a particular deployment using this configuration file,
while leaving the application defaults intact (and, thus, still available for later reference). This can
even override the vendor file containing a standard set of overrides.
SEE ALSO
Jifty
AUTHOR
Various folks at BestPractical Solutions, LLC.
LICENSE
Jifty is Copyright 2005-2010 Best Practical Solutions, LLC. Jifty is distributed under the same terms as
Perl itself.
perl v5.14.2 2010-12-10 Jifty::Config(3pm)