GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  JIFTY::CONFIG (3)

.ds Aq ’

NAME

Jifty::Config - the configuration handler for Jifty

CONTENTS

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 <B>don’t messB> 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 CW$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 <B>importantB> 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:
o validation

For example check if file or module exists.

o canonicalization

For example turn relative paths into absolute or translate all possible variants of an option into a canonical structure

o generation

For example generate often used constructions based on other options, user of your app can even don’t know about them

o config upgrades

Jifty has ConfigVersion option you may want to implement something like that in your apps

Sub-classing is definitely not for:
o default values

You have so many files to allow users of your app and you to override defaults.

o 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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 JIFTY::CONFIG (3) 2010-12-10

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.