lib/Apache/MVC.pm

   1 package Apache::MVC;
   2
   3 our $VERSION = '2.05';
   4
   5 use strict;
   6 use warnings;
   7
   8 use base 'Maypole';
   9 use mod_perl;
  10
  11 use constant APACHE2 => $mod_perl::VERSION >= 1.99;
  12
  13 if (APACHE2) {
  14     require Apache2;
  15     require Apache::RequestIO;
  16     require Apache::RequestRec;
  17     require Apache::RequestUtil;
  18     require APR::URI;
  19 }
  20 else { require Apache }
  21 require Apache::Request;
  22
  23 sub get_request {
  24     my ( $self, $r ) = @_;
  25     $self->{ar} = Apache::Request->new($r);
  26 }
  27
  28 sub parse_location {
  29     my $self = shift;
  30     $self->{path} = $self->{ar}->uri;
  31     my $loc = $self->{ar}->location;
  32     no warnings 'uninitialized';
  33     $self->{path} =~ s/^($loc)?\///;
  34     $self->parse_path;
  35     $self->parse_args;
  36 }
  37
  38 sub parse_args {
  39     my $self = shift;
  40     $self->{params} = { $self->_mod_perl_args( $self->{ar} ) };
  41     $self->{query}  = { $self->_mod_perl_args( $self->{ar} ) };
  42 }
  43
  44 sub send_output {
  45     my $r = shift;
  46     $r->{ar}->content_type(
  47           $r->{content_type} =~ m/^text/
  48         ? $r->{content_type} . "; charset=" . $r->{document_encoding}
  49         : $r->{content_type}
  50     );
  51     $r->{ar}->headers_out->set(
  52         "Content-Length" => do { use bytes; length $r->{output} }
  53     );
  54     APACHE2 || $r->{ar}->send_http_header;
  55     $r->{ar}->print( $r->{output} );
  56 }
  57
  58 sub get_template_root {
  59     my $r = shift;
  60     $r->{ar}->document_root . "/" . $r->{ar}->location;
  61 }
  62
  63 sub _mod_perl_args {
  64     my ( $self, $apr ) = @_;
  65     my %args;
  66     foreach my $key ( $apr->param ) {
  67         my @values = $apr->param($key);
  68         $args{$key} = @values == 1 ? $values[0] : \@values;
  69     }
  70     return %args;
  71 }
  72
  73 1;
  74
  75 =head1 NAME
  76
  77 Apache::MVC - Apache front-end to Maypole
  78
  79 =head1 SYNOPSIS
  80
  81     package BeerDB;
  82     use base 'Apache::MVC';
  83     BeerDB->setup("dbi:mysql:beerdb");
  84     BeerDB->config->uri_base("http://your.site/");
  85     BeerDB->config->display_tables([qw[beer brewery pub style]]);
  86     # Now set up your database:
  87     # has-a relationships
  88     # untaint columns
  89
  90     1;
  91
  92 =head1 DESCRIPTION
  93
  94 Maypole is a Perl web application framework to Java's struts. It is
  95 essentially completely abstracted, and so doesn't know anything about
  96 how to talk to the outside world. C<Apache::MVC> is a mod_perl based
  97 subclass of Maypole.
  98
  99 To use it, you need to create a package which represents your entire
 100 application. In our example above, this is the C<BeerDB> package.
 101
 102 This needs to first inherit from C<Apache::MVC>, and then call setup.
 103 This will give your package an Apache-compatible C<handler> subroutine,
 104 and then pass any parameters onto the C<setup_database> method of the
 105 model class. The default model class for Maypole uses L<Class::DBI> to
 106 map a database to classes, but this can be changed by messing with the
 107 configuration. (B<Before> calling setup.)
 108
 109 Next, you should configure your application through the C<config>
 110 method. Configuration parameters at present are:
 111
 112 =over
 113
 114 =item uri_base
 115
 116 You B<must> specify this; it is the base URI of the application, which
 117 will be used to construct links.
 118
 119 =item display_tables
 120
 121 If you do not want all of the tables in the database to be accessible,
 122 then set this to a list of only the ones you want to display
 123
 124 =item rows_per_page
 125
 126 List output is paged if you set this to a positive number of rows.
 127
 128 =back
 129
 130 You should also set up relationships between your classes, such that,
 131 for instance, calling C<brewery> on a C<BeerDB::Beer> object returns an
 132 object representing its associated brewery.
 133
 134 For a full example, see the included "beer database" application.
 135
 136 =head1 INSTALLATION
 137
 138 Create a driver module like the one above.
 139
 140 Put the following in your Apache config:
 141
 142     <Location /beer>
 143         SetHandler perl-script
 144         PerlHandler BeerDB
 145     </Location>
 146
 147 Copy the templates found in F<templates/factory> into the
 148 F<beer/factory> directory off the web root. When the designers get
 149 back to you with custom templates, they are to go in
 150 F<beer/custom>. If you need to do override templates on a
 151 database-table-by-table basis, put the new template in
 152 F<beer/I<table>>.
 153
 154 This will automatically give you C<add>, C<edit>, C<list>, C<view> and
 155 C<delete> commands; for instance, a list of breweries, go to
 156
 157     http://your.site/beer/brewery/list
 158
 159 For more information about how the system works and how to extend it,
 160 see L<Maypole>.
 161
 162 =head1 Implementation
 163
 164 This class overrides a set of methods in the base Maypole class to provide it's
 165 functionality. See L<Maypole> for these:
 166
 167 =over
 168
 169 =item get_request
 170
 171 =item get_template_root
 172
 173 =item parse_args
 174
 175 =item parse_location
 176
 177 =item send_output
 178
 179 =back
 180
 181 =head1 AUTHOR
 182
 183 Simon Cozens, C<simon@cpan.org>
 184 Marcus Ramberg, C<marcus@thefeed.no>
 185 Screwed up by Sebastian Riedel, C<sri@oook.de>
 186
 187 =head1 LICENSE
 188
 189 You may distribute this code under the same terms as Perl itself.