NAME

       CGI::Application::Standard::Config -- Define a standard configuration API for
       CGI::Application

RATIONALE

       This module defines a minimum standard interface that configuration plugins for
       CGI::Application should meet.  Having such a standard allows other plugin authors to rely
       on basic configuration functionality without coding exceptions for several configuration
       modules, or giving up on such integration.

SYNOPSIS

   For Average Users
       Simply load the config plugin before other modules that might use it:

         use CGI::Application::Plugin::ConfigAuto;
         use CGI::Application::Plugin::Session;

   For Configuration plugin authors
       Configuration plugin authors only need to follow the standards documented below.

   For other plugin authors who wish to rely on the standard
       Plugin authors who want to possibly use this standard can do so by simply using this
       module:

         package CGI::Application::Plugin::Session;
         use CGI::Application::Standard::Config;

       If a standards complaint config module hasn't already been loaded a stub for config() will
       be added which will safely return "undef".

       Example use by another plugin

       Here code first tries to get configuration details first from a config file, then from
       options passed to a plugin-specific config method, and finally applies defaults if no
       configuration options are found.

        my $session_options = $self->config('Session_options')
                                             || $self->session_config()
                                             || $self->session_defaults;

Standard Interface Definition

       The following defines a minimum standard for configuration plugins to meet.

       Config plugins are free to provide to additional functionality.

       Configuration plugins are also encourage to explicitly document that they are using
       "CGI::Application::Standard::Config".

       If there are existing methods that follow the standard but have different names, you can
       use this example to always export your method:

         sub import {
           my $app = caller;
           no strict 'refs';
           my $full_name = $app . '::config';
           # Change cfg to your config()-compliant method name
           *$full_name = \&cfg;
           CGI::Application::Plugin::YourNameHere->export_to_level(1,@_);
         }

   $self->std_config
       This method should be exported by default to simply declare that you  meet the standard
       report which version of the standard you meet. This simple implementation is recommended:

        sub std_config { return 1; }

   $self->config
       The intended use is to load to read-only configuration details once from a config file at
       start up time.

       This service is provided by plugins (list below). They must support at at least this
       syntax:

        my $value = $self->config('key');

       By default, "config()" simply returns undef, making it safe for other plugins to directly
       to check if "$self-"config('key')> returns the value it needs.

       config() must be exported by default.

       For applications that need little configuration, config() is not necessary-- using
       "PARAMS" in an instance script should suffice.

       Also, the "param()" is the appropriate method to use to set a configuration value at run
       time.

       Configuration plugins that provide at least this basic API include:

       CGI::Application::Plugin::ConfigAuto.

       Standard config variables

       Users are encouraged to use these standard config variable names, to ease compatibility
       between plugins:

        ROOT_URI - A URI corresponding to the project root (http://foo.com/proj )
        ROOT_DIR - a file system path to the same location ( /home/joe/www/proj )

       All-caps are used to denote that config variables are essentially global constants.

       Why URI and not URL? The wikipedia explains:

         The contemporary point of view among the working group that oversees URIs is
         that the terms URL and URN are context-dependent aspects of URI and rarely
         need to be distinguished. Furthermore, the term URL is increasingly becoming
         obsolete, as it is rarely necessary to differentiate between URLs and URIs,
         in general.

Standard Version

       This is 1.0 of the CGI::Application config() standard.

AUTHOR

       Written by Mark Stosberg <mark@summersault.com> with input from the CGI::Application
       community.

COPYRIGHT and LICENSE

       Copyright (C) 2008, Mark Stosberg.  All rights reserved.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.