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.