http://my.server.name/cgi-bin/hello-world.cgi/
you'll get the "Hello world!" string output to your browser. For more complex
-examples and non-CGI deployment, see below. To get help with Web::Simple,
+examples and non-CGI deployment, see below. To get help with L<Web::Simple>,
please connect to the irc.perl.org IRC network and join #web-simple.
=head1 DESCRIPTION
-The philosophy of L<Web::Simple> is to keep to an absolute bare minimum, for
+The philosophy of L<Web::Simple> is to keep to an absolute bare minimum for
everything. It is not designed to be used for large scale applications;
the L<Catalyst> web framework already works very nicely for that and is
a far more mature, well supported piece of software.
want to not have to think about complexities of deployment, then L<Web::Simple>
might be just the thing for you.
-The only public interface the Web::Simple module itself provides is an
-import based one:
+The only public interface the L<Web::Simple> module itself provides is an
+C<import> based one:
use Web::Simple 'NameOfApplication';
-This setups up your package (in this case "NameOfApplication" is your package)
+This sets up your package (in this case "NameOfApplication" is your package)
so that it inherits from L<Web::Simple::Application> and imports L<strictures>,
as well as installs a C<PSGI_ENV> constant for convenience, as well as some
other subroutines.
-Importing L<strictures> will automatically make you code use the C<strict> and
+Importing L<strictures> will automatically make your code use the C<strict> and
C<warnings> pragma, so you can skip the usual:
use strict;
extends 'Web::Simple::Application';
}
+So you can use L<Moo> features in your application, such as creating attributes
+using the C<has> subroutine, etc. Please see the documentation for L<Moo> for
+more information.
+
It also exports the following subroutines for use in dispatchers:
response_filter { ... };
=head1 DISPATCH STRATEGY
-L<Web::Simple> dispite being straightforward to use, has a powerful system
+L<Web::Simple> despite being straightforward to use, has a powerful system
for matching all sorts of incoming URLs to one or more subroutines. These
subroutines can be simple actions to take for a given URL, or something
more complicated, including entire L<Plack> applications, L<Plack::Middleware>
sub (/foo/...) {
-will match /foo/ on the beginning of the path -and- strip it, much like
-.html strips the extension. This is designed to be used to construct
-nested dispatch structures, but can also prove useful for having e.g. an
-optional language specification at the start of a path.
+Will match /foo/ on the beginning of the path -and- strip it. This is designed
+to be used to construct nested dispatch structures, but can also prove useful
+for having e.g. an optional language specification at the start of a path.
Note that the '...' is a "maybe something here, maybe not" so the above
specification will match like this:
sub (.html) {
-will match and strip .html from the path (assuming the subroutine itself
-returns something, of course). This is normally used for rendering - e.g.
+will match .html from the path (assuming the subroutine itself returns
+something, of course). This is normally used for rendering - e.g.
sub (.html) {
response_filter { $self->render_html($_[1]) }
sub (.*) {
-will match any extension and supplies the stripped extension as a match
-argument.
+will match any extension and supplies the extension as a match argument.
=head3 Query and body parameter matches
=head1 COPYRIGHT
-Copyright (c) 2009 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
+Copyright (c) 2010 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
as listed above.
=head1 LICENSE
=head1 NAME
-Web::Simple::Application - A base class for your Web-Simple applications
+Web::Simple::Application - A base class for your Web-Simple application
=head1 DESCRIPTION
=head1 METHODS
-This class exposes the follow public methods.
+This class exposes the following public methods.
=head2 default_config
-Provide configuration information to your application, for example:
+Merges with the C<config> initializer to provide configuration information for
+your application. For example:
sub default_config {
(
);
}
-Now, C<$self> will have an attribute C<config> which will be set to a HashRef
+Now, the C<config> attribute of C<$self> will be set to a HashRef
containing keys 'title' and 'posts_dir'.
+If you construct your application like:
+
+ MyWebSimpleApp::Web->new(config=>{environment=>'dev'})
+
+then C<config> will have a C<environment> key with a value of 'dev'.
+
=head2 run_if_script
-In the case where you wish to run you L<Web::Simple> based application as a
+In the case where you wish to run your L<Web::Simple> based application as a
stand alone CGI application, you can simple do:
## my_web_simple_app.pl
HelloWorld->run_if_script;
+Additionally, you can treat the above script as though it were a standard PSGI
+application file (*.psgi). For example you can start up up with C<plackup>
+
+ plackup my_web_simple_app.pl
+
+Which means you can write a L<Web::Simple> application as a plain old CGI
+application and seemlessly migrate to a L<Plack> based solution when you are
+ready for that.
+
+Lastly, L</run_if_script> will automatically detect and support a Fast CGI
+environment.
+
=head2 to_psgi_app
Given a L<Web::Simple> application root namespace, return it in a form suitable
use MyWebSimpleApp::Web;
MyWebSimpleApp::Web->to_psgi_app;
+This means if you want to provide a 'default' set of middleware, one option is
+to modify this method:
+
+ use Web::Simple 'HelloWorld';
+ use Plack::Builder;
+
+ {
+ package HelloWorld;
+
+
+ around 'to_psgi_app', sub {
+ my ($orig, $self) = (shift, shift);
+ my $app = $self->$orig(@_);
+ builder {
+ enable ...; ## whatever middleware you want
+ $app;
+ };
+ };
+ }
+
As always, mix and match the pieces you actually need and remember the
L<Web::Simple> philosophy of trying to keep it as minimal and simple as possible.
=head1 COPYRIGHT
-Copyright (c) 2009 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
+Copyright (c) 2010 the Web::Simple L</AUTHOR> and L</CONTRIBUTORS>
as listed above.
=head1 LICENSE
projects / catagits/Web-Simple.git / commitdiff