Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Jifty::Config(3)      User Contributed Perl Documentation     Jifty::Config(3)

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:

       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.

MERGING	RULES
       Values from files loaded	later take precedence; that is,	Jifty's
       defaults	are overridden by the application configuration	file, then the
       vendor configuration file, then the site	configuration file.  At	each
       step, the new values are	merged into the	old values using Hash::Merge.
       Specifically, arrays which exist	in both	old and	new data structures
       are appended, and hashes	are merged.

       Some special rules apply, however:

       o   If a	key in a hash ends in "!", the normal merging rules do not
	   apply; it simply overrides the equivalent non-"!" key's value.

       o   Plugins from	one file are merged into the plugin configuration from
	   previous files if their plugin classes match.  That is, if both
	   config.yml and site_config.yml define a
	   Jifty::Plugin::CompressedCSSandJS, rather than causing _two_	such
	   plugins to be instantiated, the site_config.yml's plugin
	   configuration keys will override those of config.yml.

	   This	rule is	only special because the "Plugins" key in Jifty's
	   config is an	arrayref, not a	hashref	on plugin class	name, to allow
	   for both template and dispatcher ordering, as well as the
	   possibility of repeated plugins.

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.24.1			  2013-02-19		      Jifty::Config(3)

NAME | SYNOPSIS | DESCRIPTION | ACCESSING CONFIG | LOADING | OTHER METHODS | SUB-CLASSING | WHY SO MANY FILES | MERGING RULES | SEE ALSO | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Jifty::Config&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help