1CGI::Application::StandUasredr::CCoonntfriigb(u3t)ed PerClGID:o:cAupmpelnitcaattiioonn::Standard::Config(3)
2
3
4
5Last updated:  Sat Feb 18 23:42:29 EST 2006
6

NAME

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

RATIONALE

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

SYNOPSIS

19   For Average Users
20       Simply load the config plugin before other modules that might use it:
21
22         use CGI::Application::Plugin::ConfigAuto;
23         use CGI::Application::Plugin::Session;
24
25   For Configuration plugin authors
26       Configuration plugin authors only need to follow the standards
27       documented below.
28
29   For other plugin authors who wish to rely on the standard
30       Plugin authors who want to possibly use this standard can do so by
31       simply using this module:
32
33         package CGI::Application::Plugin::Session;
34         use CGI::Application::Standard::Config;
35
36       If a standards complaint config module hasn't already been loaded a
37       stub for config() will be added which will safely return "undef".
38
39       Example use by another plugin
40
41       Here code first tries to get configuration details first from a config
42       file, then from options passed to a plugin-specific config method, and
43       finally applies defaults if no configuration options are found.
44
45        my $session_options = $self->config('Session_options')
46                                             || $self->session_config()
47                                             || $self->session_defaults;
48

Standard Interface Definition

50       The following defines a minimum standard for configuration plugins to
51       meet.
52
53       Config plugins are free to provide to additional functionality.
54
55       Configuration plugins are also encourage to explicity document that
56       they are using "CGI::Application::Standard::Config".
57
58       If there are existing methods that follow the standard but have
59       different names, you can use this example to always export your method:
60
61         sub import {
62           my $app = caller;
63           no strict 'refs';
64           my $full_name = $app . '::config';
65           # Change cfg to your config()-compliant method name
66           *$full_name = \&cfg;
67           CGI::Application::Plugin::YourNameHere->export_to_level(1,@_);
68         }
69
70   $self->std_config
71       This method should be exported by default to simply declare that you
72       meet the standard report which version of the standard you meet. This
73       simple implementation is recommended:
74
75        sub std_config { return 1; }
76
77   $self->config
78       The intended use is to load to read-only configuration details once
79       from a config file at start up time.
80
81       This service is provided by plugins (list below). They must support at
82       at least this syntax:
83
84        my $value = $self->config('key');
85
86       By default, config() simply returns undef, making it safe for other
87       plugins to directly to check if "$self-"config('key')> returns the
88       value it needs.
89
90       config() must be exported by default.
91
92       For applications that need little configuration, config() is not
93       necessary-- using "PARAMS" in an instance script should suffice.
94
95       Also, the param() is the appropriate method to use to set a
96       configuration value at run time.
97
98       Configuration plugins that provide at least this basic API include:
99
100       CGI::Application::Plugin::ConfigAuto.
101
102       Standard config variables
103
104       Users are encouraged to use these standard config variable names, to
105       ease compatibility between plugins:
106
107        ROOT_URI - A URI corresponding to the project root (http://foo.com/proj )
108        ROOT_DIR - a file system path to the same location ( /home/joe/www/proj )
109
110       All-caps are used to denote that config variables are essentially
111       global constants.
112
113       Why URI and not URL? The wikipedia explains:
114
115         The contemporary point of view among the working group that oversees URIs is
116         that the terms URL and URN are context-dependent aspects of URI and rarely
117         need to be distinguished. Furthermore, the term URL is increasingly becoming
118         obsolete, as it is rarely necessary to differentiate between URLs and URIs,
119         in general.
120

Standard Version

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

AUTHOR

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

129       Copyright (C) 2008, Mark Stosberg.  All rights reserved.
130
131       This library is free software; you can redistribute it and/or modify it
132       under the same terms as Perl itself.
133
134
135
136perl v5.36.0                      2023-01-C2G0I::Application::Standard::Config(3)
Impressum