]> git.decadent.org.uk Git - maypole.git/blob - lib/Maypole/Application.pm
DFV model tested and working, new additional method in Maypole::Config, new warn...
[maypole.git] / lib / Maypole / Application.pm
1 package Maypole::Application;
2
3 use strict;
4 use warnings;
5
6 use UNIVERSAL::require;
7 use Maypole;
8 use Maypole::Config;
9
10 our $VERSION = '2.11';
11
12 sub import {
13     shift; # not interested in this - we manipulate the caller's @ISA directly
14     my @plugins = @_;
15     my $caller = caller(0);
16     
17     my $frontend = 'Apache::MVC' if $ENV{MOD_PERL};
18     
19     $frontend = 'Maypole::HTTPD::Frontend' if $ENV{MAYPOLE_HTTPD};
20     
21     my $masonx;
22     if ( grep { /^MasonX$/ } @plugins )
23     {
24         $masonx++;
25         @plugins = grep { ! /^MasonX$/ } @plugins;
26         $frontend = 'MasonX::Maypole';
27     }
28     
29     $frontend ||= 'CGI::Maypole';
30     
31     $frontend->require or die "Loading $frontend frontend failed: $@";
32
33     my $autosetup=0;
34     my $autoinit=0;
35     my @plugin_modules;
36
37     foreach (@plugins) 
38     {
39         if    (/^\-Setup$/) { $autosetup++; }
40         elsif (/^\-Init$/)  { $autoinit++ }
41         elsif (/^\-Debug(\d*)$/) {
42             my $d = $1 || 1;
43             no strict 'refs';
44             *{"$caller\::debug"} = sub { $d };
45             warn "Debugging (level $d) enabled for $caller";
46         }
47         elsif (/^-.*$/) { warn "Unknown flag: $_" }
48         else {
49             my $plugin = "Maypole::Plugin::$_";
50             if ($plugin->require) {
51                 push @plugin_modules, "Maypole::Plugin::$_";
52                 warn "Loaded plugin: $plugin for $caller"
53                     if $caller->can('debug') && $caller->debug;
54             } else {
55                 die qq(Loading plugin "$plugin" for $caller failed: )
56                     . $UNIVERSAL::require::ERROR;
57             }
58         }
59     }
60     
61     no strict 'refs';
62     push @{"${caller}::ISA"}, @plugin_modules, $frontend;
63     $caller->config(Maypole::Config->new);
64     $caller->config->masonx({}) if $masonx;
65     $caller->setup() if $autosetup;
66     $caller->init() if $autosetup && $autoinit;
67 }
68
69 1;
70
71 =head1 NAME
72
73 Maypole::Application - Universal Maypole Frontend
74
75 =head1 SYNOPSIS
76
77     use Maypole::Application;
78
79     use Maypole::Application qw(Config::YAML);
80
81     use Maypole::Application qw(-Debug Config::YAML -Setup);
82
83     use Maypole::Application qw(Config::YAML Loader -Setup -Debug);
84
85     use Maypole::Application qw(-Debug2 MasonX AutoUntaint);
86
87 =head1 DESCRIPTION
88
89 This is a universal frontend for mod_perl1, mod_perl2, HTML::Mason and CGI.
90
91 Automatically determines the appropriate frontend for your environment (unless
92 you want to use L<MasonX::Maypole>, in which case include C<MasonX> in the
93 arguments).
94
95 Loads plugins supplied in the C<use> statement. 
96
97 Responds to flags supplied in the C<use> statement. 
98
99 Initializes the application's configuration object. 
100
101 You can omit the Maypole::Plugin:: prefix from plugins. So
102 Maypole::Plugin::Config::YAML becomes Config::YAML.
103
104     use Maypole::Application qw(Config::YAML);
105
106 You can also set special flags like -Setup, -Debug and -Init.
107
108     use Maypole::Application qw(-Debug Config::YAML -Setup);
109
110 The position of plugins in the chain is important, because they are
111 loaded/executed in the same order they appear.
112
113 =head1 FRONTEND
114
115 Under mod_perl (1 or 2), selects L<Apache::MVC>. 
116
117 Otherwise, selects L<CGI::Maypole>.
118
119 If C<MasonX> is specified, sets L<MasonX::Maypole> as the frontend. This
120 currently also requires a mod_perl environment.
121
122 =head1 FLAGS
123
124 =over
125
126 =item -Setup
127
128     use Maypole::Application qw(-Setup);
129
130 is equivalent to
131
132     use Maypole::Application;
133     MyApp->setup;
134
135 Note that no options are passed to C<setup()>. You must ensure that the
136 required model config parameters are set in C<MyApp-E<gt>config>. See
137 L<Maypole::Config> for more information.
138
139 =item -Init
140
141     use Maypole::Application qw(-Setup -Init);
142     
143 is equivalent to
144
145     use Maypole::Application;
146     MyApp->setup;
147     MyApp->init;
148     
149 Note that the C<-Setup> flag is required for the C<-Init> flag to work.
150
151 In persistent environments (e.g. C<mod_perl>), it is useful to call C<init> 
152 once in the parent server, rather than at the beginning of the first request
153 to each child server, in order to share the view code loaded during C<init>. 
154 Note that you must supply all the config data to your app before calling 
155 C<setup> and C<init>, probably by using one of the C<Maypole::Plugin::Config::*> 
156 plugins.
157
158 =item -Debug
159
160     use Maypole::Application qw(-Debug);
161
162 is equivalent to
163
164     use Maypole::Application;
165     sub debug { 1 }
166
167 You can specify a higher debug level by saying C<-Debug2> etc. 
168
169 =back
170
171 =head1 AUTHOR
172
173 Sebastian Riedel, C<sri@oook.de>
174 Idea by Marcus Ramberg, C<marcus@thefeed.no>
175
176 =head1 LICENSE
177
178 You may distribute this code under the same terms as Perl itself.
179
180 =cut