lib/Apache/MVC.pm

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