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