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