File Coverage

blib/lib/Maypole.pm

Criterion	Covered	Total	%
statement	3	3	100.0
branch			n/a
condition			n/a
subroutine	1	1	100.0
pod			n/a
total	4	4	100.0

package Maypole;
use base qw(Class::Accessor::Fast Class::Data::Inheritable);
use UNIVERSAL::require;
use strict;
use warnings;
use Data::Dumper;
use Maypole::Config;
use Maypole::Constants;
use Maypole::Headers;
use URI();
use URI::QueryParam;
use NEXT;
use File::MMagic::XS qw(:compat);

our $VERSION = '2.13';
our $mmagic = File::MMagic::XS->new();

# proposed privacy conventions:
# - no leading underscore     - public to custom application code and plugins
# - single leading underscore - private to the main Maypole stack - *not*
#     including plugins
# - double leading underscore - private to the current package

=head1 NAME

Maypole - MVC web application framework

=head1 SYNOPSIS

The canonical example used in the Maypole documentation is the beer database:

    package BeerDB;
    use strict;
    use warnings;

    # choose a frontend, initialise the config object, and load a plugin
    use Maypole::Application qw/Relationship/;

    # set everything up
    __PACKAGE__->setup("dbi:SQLite:t/beerdb.db");

    # get the empty config object created by Maypole::Application
    my $config = __PACKAGE__->config;

    # basic settings
    $config->uri_base("http://localhost/beerdb");
    $config->template_root("/path/to/templates");
    $config->rows_per_page(10);
    $config->display_tables([qw/beer brewery pub style/]);

    # table relationships
    $config->relationships([
        "a brewery produces beers",
        "a style defines beers",
        "a pub has beers on handpumps",
        ]);

    # validation
    BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] );
    BeerDB::Pub->untaint_columns( printable => [qw/name notes url/] );
    BeerDB::Style->untaint_columns( printable => [qw/name notes/] );
    BeerDB::Beer->untaint_columns(
        printable => [qw/abv name price notes/],
        integer => [qw/style brewery score/],
        date => [ qw/date/],
    );

    # note : set up model before calling this method
    BeerDB::Beer->required_columns([qw/name/]);

    1;

=head1 DESCRIPTION

This documents the Maypole request object. See the L, for a
detailed guide to using Maypole.

Maypole is a Perl web application framework similar to Java's struts. It is
essentially completely abstracted, and so doesn't know anything about
how to talk to the outside world.

To use it, you need to create a driver package which represents your entire
application. This is the C package used as an example in the manual.

This needs to first use L which will make your package
inherit from the appropriate platform driver such as C or
C. Then, the driver calls C. This sets up the model classes
and configures your application. The default model class for Maypole uses
L to map a database to classes, but this can be changed by altering
configuration (B calling setup.)


=head1 DOCUMENTATION AND SUPPORT

Note that some details in some of these resources may be out of date.

=over 4

=item The Maypole Manual

The primary documentation is the Maypole manual. This lives in the
C pod documents included with the distribution.

=item Embedded POD

Individual packages within the distribution contain (more or less) detailed
reference documentation for their API.

=item Mailing lists

There are two mailing lists - maypole-devel and maypole-users - see
http://maypole.perl.org/?MailingList

=item The Maypole Wiki

The Maypole wiki provides a useful store of extra documentation -
http://maypole.perl.org

In particular, there's a FAQ (http://maypole.perl.org/?FAQ) and a cookbook
(http://maypole.perl.org/?Cookbook). Again, certain information on these pages
may be out of date.

=item Web applications with Maypole

A tutorial written by Simon Cozens for YAPC::EU 2005 -
http://www.aarontrevena.co.uk/opensource/maypole/maypole-tutorial.pdf [228KB].

=item A Database-Driven Web Application in 18 Lines of Code

By Paul Barry, published in Linux Journal, March 2005.

http://www.linuxjournal.com/article/7937

"From zero to Web-based database application in eight easy steps".

Maypole won a 2005 Linux Journal Editor's Choice Award
(http://www.linuxjournal.com/article/8293) after featuring in this article.

=item Build Web apps with Maypole

By Simon Cozens, on IBM's DeveloperWorks website, May 2004.

http://www-128.ibm.com/developerworks/linux/library/l-maypole/

=item Rapid Web Application Deployment with Maypole

By Simon Cozens, on O'Reilly's Perl website, April 2004.

http://www.perl.com/pub/a/2004/04/15/maypole.html

=item Authentication

Some notes written by Simon Cozens. A little bit out of date, but still
very useful: http://www.aarontrevena.co.uk/opensource/maypole/authentication.html

=item CheatSheet

There's a refcard for the Maypole (and Class::DBI) APIs on the wiki -
http://maypole.perl.org/?CheatSheet. Probably a little out of date now - it's a
wiki, so feel free to fix any errors!

=item Plugins and add-ons

There are a large and growing number of plugins and other add-on modules
available on CPAN - http://search.cpan.org/search?query=maypole&mode=module

=item del.icio.us

You can find a range of useful Maypole links, particularly to several thoughtful
blog entries, starting here: http://del.icio.us/search/?all=maypole

=item CPAN ratings

There are a couple of short reviews here:
http://cpanratings.perl.org/dist/Maypole

=back

=cut

__PACKAGE__->mk_classdata($_) for qw( config init_done view_object model_classes_loaded);

__PACKAGE__->mk_accessors(
    qw( params query objects model_class template_args output path
        args action template error document_encoding content_type table
        headers_in headers_out stash status parent build_form_elements
        user session)
);

__PACKAGE__->config( Maypole::Config->new({additional => { }, request_options => { }, view_options => { },}) );

__PACKAGE__->init_done(0);

__PACKAGE__->model_classes_loaded(0);

=head1 HOOKABLE METHODS

As a framework, Maypole provides a number of B - methods that are
intended to be overridden. Some of these methods come with useful default
behaviour, others do nothing by default. Hooks include:

    Class methods
    -------------
    debug
    setup
    setup_model
    load_model_subclass
    init

    Instance methods
    ----------------
    start_request_hook
    is_model_applicable
    get_session
    authenticate
    exception
    additional_data
    preprocess_path

=head1 CLASS METHODS

=over 4

=item debug

    sub My::App::debug {1}

Returns the debugging flag. Override this in your application class to
enable/disable debugging.

You can also set the C flag via L.

Some packages respond to higher debug levels, try increasing it to 2 or 3.


=cut

sub debug { 0 }

=item config

Returns the L object

=item setup

   My::App->setup($data_source, $user, $password, \%attr);

Initialise the Maypole application and plugins and model classes.
Your application should call this B setting up configuration data via
L<"config">.

It calls the hook  C to setup the model. The %attr hash contains
options and arguments used to set up the model. See the particular model's
documentation. However here is the most usage of setup where
Maypole::Model::CDBI is the base class.

 My::App->setup($data_source, $user, $password,
       {  options => {  # These are DB connection options
               AutoCommit => 0,
               RaiseError => 1,
               ...
          },
          # These are Class::DBI::Loader arguments.
          relationships  => 1,
          ...
       }
 );

Also, see  L.

=cut


sub setup
{
    my $class = shift;

    $class->setup_model(@_);
}

=item setup_model

Called by C. This method builds the Maypole model hierarchy.

A likely target for over-riding, if you need to build a customised model.

This method also ensures any code in custom model classes is loaded, so you
don't need to load them in the driver.

=cut

sub setup_model {
  my $class = shift;
  $class = ref $class if ref $class;
  my $config = $class->config;
  $config->model || $config->model('Maypole::Model::CDBI');
  $config->model->require or die sprintf
    "Couldn't load the model class %s: %s", $config->model, $@;

  # among other things, this populates $config->classes
  $config->model->setup_database($config, $class, @_);

  $config->model->add_model_superclass($config);

  # Load custom model code, if it exists - nb this must happen after the
  # adding the model superclass, to allow code attributes to work, but before adopt(),
  # in case adopt() calls overridden methods on $subclass
  foreach my $subclass ( @{ $config->classes } ) {
    $class->load_model_subclass($subclass) unless ($class->model_classes_loaded());
    $config->model->adopt($subclass) if $config->model->can("adopt");
  }

}

=item load_model_subclass($subclass)

This method is called from C. It attempts to load the
C<$subclass> package, if one exists. So if you make a customized C
package, you don't need to explicitly load it.

If automatic loading causes problems, Override load_model_subclass in your driver.

sub load_model_subclass {};

Or perhaps during development, if you don't want to load up custom classes, you
can override this method and load them manually.

=cut

sub load_model_subclass {
  my ($class, $subclass) = @_;

  my $config = $class->config;

  # Load any external files for the model base class or subclasses
  # (e.g. BeerDB/DBI.pm or BeerDB/Beer.pm) based on code borrowed from
  # Maypole::Plugin::Loader and Class::DBI.
  if ( $subclass->require ) {
    warn "Loaded external module for '$subclass'\n" if $class->debug > 1;
  } else {
    (my $filename = $subclass) =~ s!::!/!g;
    die "Loading '$subclass' failed: $@\n"
      unless $@ =~ /Can\'t locate \Q$filename\E\.pm/;
    warn "No external module for '$subclass'"
      if $class->debug > 1;
  }
}

=item init

Loads the view class and instantiates the view object.

You should not call this directly, but you may wish to override this to add
application-specific initialisation - see L.

=cut

sub init
{
    my $class  = shift;
    my $config = $class->config;
    $config->view || $config->view("Maypole::View::TT");
    $config->view->require;
    die "Couldn't load the view class " . $config->view . ": $@" if $@;
    $config->display_tables
      || $config->display_tables( $class->config->tables );
    $class->view_object( $class->config->view->new );
    $class->init_done(1);
}

=item new

Constructs a very minimal new Maypole request object.

=cut

sub new
{
    my ($class) = @_;
    my $self = bless {
        config        => $class->config,
    }, $class;

    $self->stash({});
    $self->params({});
    $self->query({});
    $self->template_args({});
    $self->args([]);
    $self->objects([]);
    return $self;
}

=item view_object

Get/set the Maypole::View object

=back

=head1 INSTANCE METHODS

=head2 Workflow

=over 4

=item handler

This method sets up the class if it's not done yet, sets some defaults and
leaves the dirty work to C.

=cut

# handler() has a method attribute so that mod_perl will invoke
# BeerDB->handler() as a method rather than a plain function
# BeerDB::handler() and so this inherited implementation will be
# found. See e.g. "Practical mod_perl" by Bekman & Cholet for
# more information
sub handler : method  {
  # See Maypole::Workflow before trying to understand this.
  my ($class, $req) = @_;

  $class->init unless $class->init_done;

  my $self = $class->new;

  # initialise the request
  $self->headers_out(Maypole::Headers->new);
  $self->get_request($req);

  $self->parse_location;

  # hook useful for declining static requests e.g. images, or perhaps for
  # sanitizing request parameters
  $self->status(Maypole::Constants::OK()); # set the default
  $self->__call_hook('start_request_hook');
  return $self->status unless $self->status == Maypole::Constants::OK();
  die "status undefined after start_request_hook()" unless defined
    $self->status;

  my $session = $self->get_session;
  $self->session($self->{session} || $session);
  my $user = $self->get_user;
  $self->user($self->{user} || $user);

  my $status = $self->handler_guts;
  return $status unless $status == OK;
  # TODO: require send_output to return a status code
  $self->send_output;
  return $status;
}

=item component

  Run Maypole sub-requests as a component of the request

  [% request.component("/beer/view_as_component/20") %]

  Allows you to integrate the results of a Maypole request into an existing
request. You'll need to set up actions and templates
which return fragments of HTML rather than entire pages, but once you've
done that, you can use the C method of the Maypole request object
to call those actions. You may pass a query string in the usual URL style.

You should not fully qualify the Maypole URLs.

Note: any HTTP POST or URL parameters passed to the parent are not passed to the
component sub-request, only what is included in the url passed as an argument
to the method

=cut

sub component {
    my ( $r, $path ) = @_;
    my $self = bless { parent => $r, config => $r->{config}, } , ref $r;
    $self->stash({});
    $self->params({});
    $self->query({});
    $self->template_args({});
    $self->args([]);
    $self->objects([]);

    $self->session($self->get_session);
    $self->user($self->get_user);

    my $url = URI->new($path);
    $self->{path} = $url->path;
    $self->parse_path;
    $self->params( $url->query_form_hash );
    $self->handler_guts;
    return $self->output;
}

sub get_template_root {
    my $self = shift;
    my $r    = shift;
    return $r->parent->get_template_root if $r->{parent};
    return $self->NEXT::DISTINCT::get_template_root( $r, @_ );
}

sub view_object {
    my $self = shift;
    my $r    = shift;
    return $r->parent->view_object if $r->{parent};
    return $self->NEXT::DISTINCT::view_object( $r, @_ );
}

# Instead of making plugin authors use the NEXT::DISTINCT hoopla to ensure other
# plugins also get to call the hook, we can cycle through the application's
# @ISA and call them all here. Doesn't work for setup() though, because it's
# too ingrained in the stack. We could add a run_setup() method, but we'd break
# lots of existing code.
sub __call_hook
{
    my ($self, $hook) = @_;

    my @plugins;
    {
        my $class = ref($self);
        no strict 'refs';
        @plugins = @{"$class\::ISA"};
    }

    # this is either a custom method in the driver, or the method in the 1st
    # plugin, or the 'null' method in the frontend (i.e. inherited from
    # Maypole.pm) - we need to be careful to only call it once
    my $first_hook = $self->can($hook);
    $self->$first_hook;

    my %seen = ( $first_hook => 1 );

    # @plugins includes the frontend
    foreach my $plugin (@plugins)
    {
        next unless my $plugin_hook = $plugin->can($hook);
        next if $seen{$plugin_hook}++;
        $self->$plugin_hook;
    }
}

=item handler_guts

This is the main request handling method and calls various methods to handle the
request/response and defines the workflow within Maypole.

=cut

# The root of all evil
sub handler_guts {
  my ($self) = @_;
  $self->build_form_elements(1) unless (defined ($self->config->build_form_elements) && $self->config->build_form_elements == 0);
  $self->__load_request_model;

  my $applicable = $self->is_model_applicable == OK;

  my $status;

  # handle authentication
  eval { $status = $self->call_authenticate };
  if ( my $error = $@ ) {
    $status = $self->call_exception($error, "authentication");
    if ( $status != OK ) {
      $self->warn("caught authenticate error: $error");
      return $self->debug ?
	$self->view_object->error($self, $error) : ERROR;
    }
  }
  if ( $self->debug and $status != OK and $status != DECLINED ) {
    $self->view_object->error( $self,
			       "Got unexpected status $status from calling authentication" );
  }

  return $status unless $status == OK;

  # We run additional_data for every request
  $self->additional_data;

  # process request with model if applicable and template not set.
  if ($applicable) {
    unless ($self->{template}) {
      eval { $self->model_class->process($self) };
      if ( my $error = $@ ) {
	$status = $self->call_exception($error, "model");
	if ( $status != OK ) {
	  $self->warn("caught model error: $error");
	  return $self->debug ?
	    $self->view_object->error($self, $error) : ERROR;
	}
      }
    }
  } else {
    $self->__setup_plain_template;
  }

  # less frequent path - perhaps output has been set to an error message
  if ($self->output) {
    $self->{content_type}      ||= $self->__get_mime_type();
    $self->{document_encoding} ||= "utf-8";
    return OK;
  }

  # normal path - no output has been generated yet
  my $processed_view_ok = $self->__call_process_view;

  $self->{content_type}      ||= $self->__get_mime_type();
  $self->{document_encoding} ||= "utf-8";

  return $processed_view_ok;
}

my %filetypes = (
		 'js' => 'text/javascript',
		 'css' => 'text/css',
		 'htm' => 'text/html',
		 'html' => 'text/html',
		);

sub __get_mime_type {
  my $self = shift;
  my $type = 'text/html';
  if ($self->path =~ m/.*\.(\w{2,4})$/) {
    $type = $filetypes{$1};
  } else {
    my $output = $self->output;
    if (defined $output) {
      $type = $mmagic->checktype_contents($output);
    }
  }
  return $type;
}

sub __load_request_model
{
    my ($self) = @_;
	# We may get a made up class from class_of
    my $mclass = $self->config->model->class_of($self, $self->table);
    if ( eval {$mclass->isa('Maypole::Model::Base')} ) {
        $self->model_class( $mclass );
    }
    elsif ($self->debug > 1) {
      $self->warn("***Warning:  No $mclass class appropriate for model. @_");
    }
}


# is_applicable() returned false, so set up a plain template. Model processing
# will be skipped, but need to remove the model anyway so the template can't
# access it.
sub __setup_plain_template
{
    my ($self) = @_;

    # It's just a plain template
    $self->build_form_elements(0);
    $self->model_class(undef);

    unless ($self->template) {
      # FIXME: this is likely to be redundant and is definately causing problems.
      my $path = $self->path;
      $path =~ s{/$}{};    # De-absolutify
      $self->path($path);
      $self->template($self->path);
    }
}

# The model has been processed or skipped (if is_applicable returned false),
# any exceptions have been handled, and there's no content in $self->output
sub __call_process_view {
  my ($self) = @_;

  my $status = eval { $self->view_object->process($self) };

  my $error = $@ || $self->{error};

  if ( $error ) {
    $status = $self->call_exception($error, "view");

    if ( $status != OK ) {
      warn "caught view error: $error" if $self->debug;
      return $self->debug ?
	$self->view_object->error($self, $error) : ERROR;
    }
  }

  return $status;
}

=item warn

$r->warn('its all gone pete tong');

Warn must be implemented by the backend, i.e. Apache::MVC
and warn to stderr or appropriate logfile.

You can also over-ride this in your Maypole driver, should you
want to use something like Log::Log4perl instead.

=cut

sub warn { }

=item build_form_elements

$r->build_form_elements(0);

Specify (in an action) whether to build HTML form elements and populate
the cgi element of classmetadata in the view.

You can set this globally using the accessor of the same name in Maypole::Config,
this method allows you to over-ride that setting per action.

=cut

=item get_request

You should only need to define this method if you are writing a new
Maypole backend. It should return something that looks like an Apache
or CGI request object, it defaults to blank.

=cut

sub get_request { }

=item parse_location

Turns the backend request (e.g. Apache::MVC, Maypole, CGI) into a Maypole
request. It does this by setting the C, and invoking C and
C.

You should only need to define this method if you are writing a new Maypole
backend.

=cut

sub parse_location
{
    die "parse_location is a virtual method. Do not use Maypole directly; " .
    		"use Apache::MVC or similar";
}

=item start_request_hook

This is called immediately after setting up the basic request. The default
method does nothing.

The value of C<< $r->status >> is set to C before this hook is run. Your
implementation can change the status code, or leave it alone.

After this hook has run, Maypole will check the value of C. For any
value other than C, Maypole returns the C immediately.

This is useful for filtering out requests for static files, e.g. images, which
should not be processed by Maypole or by the templating engine:

    sub start_request_hook
    {
        my ($r) = @_;

        $r->status(DECLINED) if $r->path =~ /\.jpg$/;
    }

Multiple plugins, and the driver, can define this hook - Maypole will call all
of them. You should check for and probably not change any non-OK C
value:

    package Maypole::Plugin::MyApp::SkipFavicon;

    sub start_request_hook
    {
        my ($r) = @_;

        # check if a previous plugin has already DECLINED this request
        # - probably unnecessary in this example, but you get the idea
        return unless $r->status == OK;

        # then do our stuff
        $r->status(DECLINED) if $r->path =~ /favicon\.ico/;
    }

=cut

sub start_request_hook { }

=item is_applicable

B as of version 2.11. If you have overridden it,
please override C instead, and change the return type
from a Maypole:Constant to a true/false value.

Returns a Maypole::Constant to indicate whether the request is valid.

=cut

sub is_applicable { return shift->is_model_applicable(@_); }

=item is_model_applicable

Returns true or false to indicate whether the request is valid.

The default implementation checks that C<< $r->table >> is publicly
accessible and that the model class is configured to handle the
C<< $r->action >>.

=cut

sub is_model_applicable {
    my ($self) = @_;

    # Establish which tables should be processed by the model
    my $config = $self->config;

    $config->ok_tables || $config->ok_tables( $config->display_tables );

    $config->ok_tables( { map { $_ => 1 } @{ $config->ok_tables } } )
        if ref $config->ok_tables eq "ARRAY";

    my $ok_tables = $config->ok_tables;

    # Does this request concern a table to be processed by the model?
    my $table = $self->table;

    my $ok = 0;

    if (exists $ok_tables->{$table})
    {
        $ok = 1;
    }

    if (not $ok)
    {
        $self->warn ("We don't have that table ($table).\n"
            . "Available tables are: "
            . join( ",", keys %$ok_tables ))
                if $self->debug and not $ok_tables->{$table};

        return DECLINED;
    }

    # Is the action public?
    my $action = $self->action;
    return OK if $self->model_class->is_public($action);

    $self->warn("The action '$action' is not applicable to the table '$table'")
         if $self->debug;

    return DECLINED;
}

=item get_session

Called immediately after C.

This method should return a session, which will be stored in the request's
C attribute.

The default method is empty.

=cut

sub get_session { }

=item get_user

Called immediately after C.

This method should return a user, which will be stored in the request's C
attribute.

The default method is empty.

=cut

sub get_user {}

=item call_authenticate

This method first checks if the relevant model class
can authenticate the user, or falls back to the default
authenticate method of your Maypole application.

=cut

sub call_authenticate
{
    my ($self) = @_;

    # Check if we have a model class with an authenticate() to delegate to
    return $self->model_class->authenticate($self)
        if $self->model_class and $self->model_class->can('authenticate');

    # Interface consistency is a Good Thing -
    # the invocant and the argument may one day be different things
    # (i.e. controller and request), like they are when authenticate()
    # is called on a model class (i.e. model and request)
    return $self->authenticate($self);
}

=item authenticate

Returns a Maypole::Constant to indicate whether the user is authenticated for
the Maypole request.

The default implementation returns C

=cut

sub authenticate { return OK }


=item call_exception

This model is called to catch exceptions, first after authenticate, then after
processing the model class, and finally to check for exceptions from the view
class.

This method first checks if the relevant model class
can handle exceptions the user, or falls back to the default
exception method of your Maypole application.

=cut

sub call_exception
{
    my ($self, $error, $when) = @_;

    # Check if we have a model class with an exception() to delegate to
    if ( $self->model_class && $self->model_class->can('exception') )
    {
        my $status = $self->model_class->exception( $self, $error, $when );
        return $status if $status == OK;
    }

    return $self->exception($error, $when);
}


=item exception

This method is called if any exceptions are raised during the authentication or
model/view processing. It should accept the exception as a parameter and return
a Maypole::Constant to indicate whether the request should continue to be
processed.

=cut

sub exception {
    my ($self, $error, $when) = @_;
    if (ref $self->view_object && $self->view_object->can("report_error") and $self->debug) {
        $self->view_object->report_error($self, $error, $when);
        return OK;
    }
    return ERROR;
}

=item additional_data

Called before the model processes the request, this method gives you a chance to
do some processing for each request, for example, manipulating C.

=cut

sub additional_data { }

=item send_output

Sends the output and additional headers to the user.

=cut

sub send_output {
    die "send_output is a virtual method. Do not use Maypole directly; use Apache::MVC or similar";
}


=back

=head2 Path processing and manipulation

=over 4

=item path

Returns the request path

=item parse_path

Parses the request path and sets the C, C and C 




986




 





 





 





 





 





 



 properties. Calls C before parsing path and setting properties. 




987




 





 





 





 





 





 



   




988




 





 





 





 





 





 



 =cut 




989




 





 





 





 





 





 



   




990




 





 





 





 





 





 



 sub parse_path { 




991




 





 





 





 





 





 



     my ($self) = @_; 




992




 





 





 





 





 





 



   




993




 





 





 





 





 





 



     # Previous versions unconditionally set table, action and args to whatever  




994




 





 





 





 





 





 



     # was in @pi (or else to defaults, if @pi is empty). 




995




 





 





 





 





 





 



     # Adding preprocess_path(), and then setting table, action and args  




996




 





 





 





 





 





 



     # conditionally, broke lots of tests, hence this: 




997




 





 





 





 





 





 



     $self->$_(undef) for qw/action table args/; 




998




 





 





 





 





 





 



     $self->preprocess_path; 




999




 





 





 





 





 





 



   




1000




 





 





 





 





 





 



     # use frontpage template for frontpage 




1001




 





 





 





 





 





 



     unless ($self->path && $self->path ne '/') { 




1002




 





 





 





 





 





 



       $self->path('frontpage'); 




1003




 





 





 





 





 





 



     } 




1004




 





 





 





 





 





 



   




1005




 





 





 





 





 





 



     my @pi = grep {length} split '/', $self->path; 




1006




 





 





 





 





 





 



   




1007




 





 





 





 





 





 



     $self->table  || $self->table(shift @pi); 




1008




 





 





 





 





 





 



     $self->action || $self->action( shift @pi or 'index' ); 




1009




 





 





 





 





 





 



     $self->args   || $self->args(\@pi); 




1010




 





 





 





 





 





 



 } 




1011




 





 





 





 





 





 



   




1012




 





 





 





 





 





 



 =item preprocess_path 




1013




 





 





 





 





 





 



   




1014




 





 





 





 





 





 



 Sometimes when you don't want to rewrite or over-ride parse_path but 




1015




 





 





 





 





 





 



 want to rewrite urls or extract data from them before it is parsed, 




1016




 





 





 





 





 





 



 the preprocess_path/location methods allow you to munge paths and urls 




1017




 





 





 





 





 





 



 before maypole maps them to actions, classes, etc. 




1018




 





 





 





 





 





 



   




1019




 





 





 





 





 





 



 This method is called after parse_location has populated the request 




1020




 





 





 





 





 





 



 information and before parse_path has populated the model and action 




1021




 





 





 





 





 





 



 information, and is passed the request object. 




1022




 





 





 





 





 





 



   




1023




 





 





 





 





 





 



 You can set action, args or table in this method and parse_path will 




1024




 





 





 





 





 





 



 then leave those values in place or populate them based on the current 




1025




 





 





 





 





 





 



 value of the path attribute if they are not present. 




1026




 





 





 





 





 





 



   




1027




 





 





 





 





 





 



 =cut 




1028




 





 





 





 





 





 



   




1029




 





 





 





 





 





 



 sub preprocess_path { }; 




1030




 





 





 





 





 





 



   




1031




 





 





 





 





 





 



 =item preprocess_location 




1032




 





 





 





 





 





 



   




1033




 





 





 





 





 





 



 This method is called at the start of parse_location, after the headers in, and allows you 




1034




 





 





 





 





 





 



 to rewrite the url used by maypole, or dynamically set configuration 




1035




 





 





 





 





 





 



 like the base_uri based on the hostname or path. 




1036




 





 





 





 





 





 



   




1037




 





 





 





 





 





 



 =cut 




1038




 





 





 





 





 





 



   




1039




 





 





 





 





 





 



 sub preprocess_location { }; 




1040




 





 





 





 





 





 



   




1041




 





 





 





 





 





 



 =item make_path( %args or \%args or @args ) 




1042




 





 





 





 





 





 



   




1043




 





 





 





 





 





 



 This is the counterpart to C. It generates a path to use 




1044




 





 





 





 





 





 



 in links, form actions etc. To implement your own path scheme, just override 




1045




 





 





 





 





 





 



 this method and C. 




1046




 





 





 





 





 





 



   




1047




 





 





 





 





 





 



     %args = ( table      => $table, 




1048




 





 





 





 





 





 



               action     => $action,         




1049




 





 





 





 





 





 



               additional => $additional,    # optional - generally an object ID 




1050




 





 





 





 





 





 



               ); 




1051




 





 





 





 





 





 



                




1052




 





 





 





 





 





 



     \%args = as above, but a ref 




1053




 





 





 





 





 





 



      




1054




 





 





 





 





 





 



     @args = ( $table, $action, $additional );   # $additional is optional 




1055




 





 





 





 





 





 



   




1056




 





 





 





 





 





 



 C can be used as an alternative key to C. 




1057




 





 





 





 





 





 



   




1058




 





 





 





 





 





 



 C<$additional> can be a string, an arrayref, or a hashref. An arrayref is 




1059




 





 





 





 





 





 



 expanded into extra path elements, whereas a hashref is translated into a query 




1060




 





 





 





 





 





 



 string.  




1061




 





 





 





 





 





 



   




1062




 





 





 





 





 





 



 =cut 




1063




 





 





 





 





 





 



   




1064




 





 





 





 





 





 



   




1065




 





 





 





 





 





 



 sub make_path 




1066




 





 





 





 





 





 



 { 




1067




 





 





 





 





 





 



     my $r = shift; 




1068




 





 





 





 





 





 



      




1069




 





 





 





 





 





 



     my %args; 




1070




 





 





 





 





 





 



      




1071




 





 





 





 





 





 



     if (@_ == 1 and ref $_[0] and ref $_[0] eq 'HASH') 




1072




 





 





 





 





 





 



     { 




1073




 





 





 





 





 





 



         %args = %{$_[0]}; 




1074




 





 





 





 





 





 



     } 




1075




 





 





 





 





 





 



     elsif ( @_ > 1 and @_ < 4 ) 




1076




 





 





 





 





 





 



     { 




1077




 





 





 





 





 





 



         $args{table}      = shift; 




1078




 





 





 





 





 





 



         $args{action}     = shift; 




1079




 





 





 





 





 





 



         $args{additional} = shift; 




1080




 





 





 





 





 





 



     } 




1081




 





 





 





 





 





 



     else 




1082




 





 





 





 





 





 



     { 




1083




 





 





 





 





 





 



         %args = @_; 




1084




 





 





 





 





 





 



     } 




1085




 





 





 





 





 





 



      




1086




 





 





 





 





 





 



     do { die "no $_" unless $args{$_} } for qw( table action );     




1087




 





 





 





 





 





 



   




1088




 





 





 





 





 





 



     my $additional = $args{additional} || $args{id}; 




1089




 





 





 





 





 





 



      




1090




 





 





 





 





 





 



     my @add = (); 




1091




 





 





 





 





 





 



      




1092




 





 





 





 





 





 



     if ($additional) 




1093




 





 





 





 





 





 



     { 




1094




 





 





 





 





 





 



         # if $additional is a href, make_uri() will transform it into a query 




1095




 





 





 





 





 





 



         @add = (ref $additional eq 'ARRAY') ? @$additional : ($additional); 




1096




 





 





 





 





 





 



     }     




1097




 





 





 





 





 





 



      




1098




 





 





 





 





 





 



     my $uri = $r->make_uri($args{table}, $args{action}, @add); 




1099




 





 





 





 





 





 



      




1100




 





 





 





 





 





 



     return $uri->as_string; 




1101




 





 





 





 





 





 



 } 




1102




 





 





 





 





 





 



   




1103




 





 





 





 





 





 



   




1104




 





 





 





 





 





 



   




1105




 





 





 





 





 





 



 =item make_uri( @segments ) 




1106




 





 





 





 





 





 



   




1107




 





 





 





 





 





 



 Make a L object given table, action etc. Automatically adds 




1108




 





 





 





 





 





 



 the C.  




1109




 





 





 





 





 





 



   




1110




 





 





 





 





 





 



 If the final element in C<@segments> is a hash ref, C will render it 




1111




 





 





 





 





 





 



 as a query string. 




1112




 





 





 





 





 





 



   




1113




 





 





 





 





 





 



 =cut 




1114




 





 





 





 





 





 



   




1115




 





 





 





 





 





 



 sub make_uri 




1116




 





 





 





 





 





 



 { 




1117




 





 





 





 





 





 



     my ($r, @segments) = @_; 




1118




 





 





 





 





 





 



   




1119




 





 





 





 





 





 



     my $query = (ref $segments[-1] eq 'HASH') ? pop(@segments) : undef; 




1120




 





 





 





 





 





 



      




1121




 





 





 





 





 





 



     my $base = $r->config->uri_base;  




1122




 





 





 





 





 





 



     $base =~ s|/$||; 




1123




 





 





 





 





 





 



      




1124




 





 





 





 





 





 



     my $uri = URI->new($base); 




1125




 





 





 





 





 





 



     $uri->path_segments($uri->path_segments, grep {length} @segments); 




1126




 





 





 





 





 





 



      




1127




 





 





 





 





 





 



     my $abs_uri = $uri->abs('/'); 




1128




 





 





 





 





 





 



     $abs_uri->query_form($query) if $query; 




1129




 





 





 





 





 





 



     return $abs_uri; 




1130




 





 





 





 





 





 



 } 




1131




 





 





 





 





 





 



   




1132




 





 





 





 





 





 



 =item parse_args 




1133




 





 





 





 





 





 



   




1134




 





 





 





 





 





 



 Turns post data and query string paramaters into a hash of C. 




1135




 





 





 





 





 





 



   




1136




 





 





 





 





 





 



 You should only need to define this method if you are writing a new Maypole 




1137




 





 





 





 





 





 



 backend. 




1138




 





 





 





 





 





 



   




1139




 





 





 





 





 





 



 =cut  




1140




 





 





 





 





 





 



   




1141




 





 





 





 





 





 



 sub parse_args 




1142




 





 





 





 





 





 



 { 




1143




 





 





 





 





 





 



     die "parse_args() is a virtual method. Do not use Maypole directly; ". 




1144




 





 





 





 





 





 



             "use Apache::MVC or similar"; 




1145




 





 





 





 





 





 



 } 




1146




 





 





 





 





 





 



   




1147




 





 





 





 





 





 



 =item get_template_root 




1148




 





 





 





 





 





 



   




1149




 





 





 





 





 





 



 Implementation-specific path to template root. 




1150




 





 





 





 





 





 



   




1151




 





 





 





 





 





 



 You should only need to define this method if you are writing a new Maypole 




1152




 





 





 





 





 





 



 backend. Otherwise, see L 




1153




 





 





 





 





 





 



   




1154




 





 





 





 





 





 



 =cut 




1155




 





 





 





 





 





 



   




1156




 





 





 





 





 





 



 =back 




1157




 





 





 





 





 





 



   




1158




 





 





 





 





 





 



 =head2 Request properties 




1159




 





 





 





 





 





 



   




1160




 





 





 





 





 





 



 =over 4 




1161




 





 





 





 





 





 



   




1162




 





 





 





 





 





 



 =item model_class 




1163




 





 





 





 





 





 



   




1164




 





 





 





 





 





 



 Returns the perl package name that will serve as the model for the 




1165




 





 





 





 





 





 



 request. It corresponds to the request C attribute. 




1166




 





 





 





 





 





 



   




1167




 





 





 





 





 





 



   




1168




 





 





 





 





 





 



 =item objects 




1169




 





 





 





 





 





 



   




1170




 





 





 





 





 





 



 Get/set a list of model objects. The objects will be accessible in the view 




1171




 





 





 





 





 





 



 templates. 




1172




 





 





 





 





 





 



   




1173




 





 





 





 





 





 



 If the first item in C<$self-Eargs> can be Cd by the model 




1174




 





 





 





 





 





 



 class, it will be removed from C and the retrieved object will be added to 




1175




 





 





 





 





 





 



 the C list. See L for more information. 




1176




 





 





 





 





 





 



   




1177




 





 





 





 





 





 



   




1178




 





 





 





 





 





 



 =item object 




1179




 





 





 





 





 





 



   




1180




 





 





 





 





 





 



 Alias to get/set the first/only model object. The object will be accessible 




1181




 





 





 





 





 





 



 in the view templates. 




1182




 





 





 





 





 





 



   




1183




 





 





 





 





 





 



 When used to set the object, will overwrite the request objects 




1184




 





 





 





 





 





 



 with a single object. 




1185




 





 





 





 





 





 



   




1186




 





 





 





 





 





 



 =cut 




1187




 





 





 





 





 





 



   




1188




 





 





 





 





 





 



 sub object { 




1189




 





 





 





 





 





 



   my ($r,$object) = @_; 




1190




 





 





 





 





 





 



   $r->objects([$object]) if ($object); 




1191




 





 





 





 





 





 



   return undef unless $r->objects(); 




1192




 





 





 





 





 





 



   return $r->objects->[0]; 




1193




 





 





 





 





 





 



 } 




1194




 





 





 





 





 





 



   




1195




 





 





 





 





 





 



 =item template_args 




1196




 





 





 





 





 





 



   




1197




 





 





 





 





 





 



     $self->template_args->{foo} = 'bar'; 




1198




 





 





 





 





 





 



   




1199




 





 





 





 





 





 



 Get/set a hash of template variables. 




1200




 





 





 





 





 





 



   




1201




 





 





 





 





 





 



 Maypole reserved words for template variables will over-ride values in template_variables. 




1202




 





 





 





 





 





 



   




1203




 





 





 





 





 





 



 Reserved words are : r, request, object, objects, base, config and errors, as well as the 




1204




 





 





 





 





 





 



 current class or object name. 




1205




 





 





 





 





 





 



   




1206




 





 





 





 





 





 



 =item stash 




1207




 





 





 





 





 





 



   




1208




 





 





 





 





 





 



 A place to put custom application data. Not used by Maypole itself. 




1209




 





 





 





 





 





 



   




1210




 





 





 





 





 





 



 =item template 




1211




 





 





 





 





 





 



   




1212




 





 





 





 





 





 



 Get/set the template to be used by the view. By default, it returns 




1213




 





 





 





 





 





 



 C<$self-Eaction> 




1214




 





 





 





 





 





 



   




1215




 





 





 





 





 





 



   




1216




 





 





 





 





 





 



 =item error 




1217




 





 





 





 





 





 



   




1218




 





 





 





 





 





 



 Get/set a request error 




1219




 





 





 





 





 





 



   




1220




 





 





 





 





 





 



 =item output 




1221




 





 





 





 





 





 



   




1222




 





 





 





 





 





 



 Get/set the response output. This is usually populated by the view class. You 




1223




 





 





 





 





 





 



 can skip view processing by setting the C. 




1224




 





 





 





 





 





 



   




1225




 





 





 





 





 





 



 =item table 




1226




 





 





 





 





 





 



   




1227




 





 





 





 





 





 



 The table part of the Maypole request path 




1228




 





 





 





 





 





 



   




1229




 





 





 





 





 





 



 =item action 




1230




 





 





 





 





 





 



   




1231




 





 





 





 





 





 



 The action part of the Maypole request path 




1232




 





 





 





 





 





 



   




1233




 





 





 





 





 





 



 =item args 




1234




 





 





 





 





 





 



   




1235




 





 





 





 





 





 



 A list of remaining parts of the request path after table and action 




1236




 





 





 





 





 





 



 have been 




1237




 





 





 





 





 





 



 removed 




1238




 





 





 





 





 





 



   




1239




 





 





 





 





 





 



 =item headers_in 




1240




 





 





 





 





 





 



   




1241




 





 





 





 





 





 



 A L object containing HTTP headers for the request 




1242




 





 





 





 





 





 



   




1243




 





 





 





 





 





 



 =item headers_out 




1244




 





 





 





 





 





 



   




1245




 





 





 





 





 





 



 A L object that contains HTTP headers for the output 




1246




 





 





 





 





 





 



   




1247




 





 





 





 





 





 



 =item document_encoding 




1248




 





 





 





 





 





 



   




1249




 





 





 





 





 





 



 Get/set the output encoding. Default: utf-8. 




1250




 





 





 





 





 





 



   




1251




 





 





 





 





 





 



 =item content_type 




1252




 





 





 





 





 





 



   




1253




 





 





 





 





 





 



 Get/set the output content type. Default: text/html 




1254




 





 





 





 





 





 



   




1255




 





 





 





 





 





 



 =item get_protocol 




1256




 





 





 





 





 





 



   




1257




 





 





 





 





 





 



 Returns the protocol the request was made with, i.e. https 




1258




 





 





 





 





 





 



   




1259




 





 





 





 





 





 



 =cut 




1260




 





 





 





 





 





 



   




1261




 





 





 





 





 





 



 sub get_protocol { 




1262




 





 





 





 





 





 



   die "get_protocol is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; 




1263




 





 





 





 





 





 



 } 




1264




 





 





 





 





 





 



   




1265




 





 





 





 





 





 



 =back 




1266




 





 





 





 





 





 



   




1267




 





 





 





 





 





 



 =head2 Request parameters 




1268




 





 





 





 





 





 



   




1269




 





 





 





 





 





 



 The source of the parameters may vary depending on the Maypole backend, but they 




1270




 





 





 





 





 





 



 are usually populated from request query string and POST data. 




1271




 





 





 





 





 





 



   




1272




 





 





 





 





 





 



 Maypole supplies several approaches for accessing the request parameters. Note 




1273




 





 





 





 





 





 



 that the current implementation (via a hashref) of C and C is 




1274




 





 





 





 





 





 



 likely to change in a future version of Maypole. So avoid direct access to these 




1275




 





 





 





 





 





 



 hashrefs: 




1276




 





 





 





 





 





 



   




1277




 





 





 





 





 





 



     $r->{params}->{foo}      # bad 




1278




 





 





 





 





 





 



     $r->params->{foo}        # better 




1279




 





 





 





 





 





 



   




1280




 





 





 





 





 





 



     $r->{query}->{foo}       # bad 




1281




 





 





 





 





 





 



     $r->query->{foo}         # better 




1282




 





 





 





 





 





 



   




1283




 





 





 





 





 





 



     $r->param('foo')         # best 




1284




 





 





 





 





 





 



   




1285




 





 





 





 





 





 



 =over 4 




1286




 





 





 





 





 





 



   




1287




 





 





 





 





 





 



 =item param 




1288




 





 





 





 





 





 



   




1289




 





 





 





 





 





 



 An accessor (get or set) for request parameters. It behaves similarly to 




1290




 





 





 





 





 





 



 CGI::param() for accessing CGI parameters, i.e. 




1291




 





 





 





 





 





 



   




1292




 





 





 





 





 





 



     $r->param                   # returns list of keys 




1293




 





 





 





 





 





 



     $r->param($key)             # returns value for $key 




1294




 





 





 





 





 





 



     $r->param($key => $value)   # returns old value, sets to new value 




1295




 





 





 





 





 





 



   




1296




 





 





 





 





 





 



 =cut 




1297




 





 





 





 





 





 



   




1298




 





 





 





 





 





 



 sub param  




1299




 





 





 





 





 





 



 {  




1300




 





 





 





 





 





 



     my ($self, $key) = (shift, shift); 




1301




 





 





 





 





 





 



      




1302




 





 





 





 





 





 



     return keys %{$self->params} unless defined $key; 




1303




 





 





 





 





 





 



      




1304




 





 





 





 





 





 



     return unless exists $self->params->{$key}; 




1305




 





 





 





 





 





 



      




1306




 





 





 





 





 





 



     my $val = $self->params->{$key}; 




1307




 





 





 





 





 





 



      




1308




 





 





 





 





 





 



     if (@_) 




1309




 





 





 





 





 





 



     { 




1310




 





 





 





 





 





 



         my $new_val = shift; 




1311




 





 





 





 





 





 



 	$self->params->{$key} = $new_val; 




1312




 





 





 





 





 





 



     } 




1313




 





 





 





 





 





 



      




1314




 





 





 





 





 





 



     return (ref $val eq 'ARRAY') ? @$val : ($val) if wantarray; 




1315




 





 





 





 





 





 



          




1316




 





 





 





 





 





 



     return (ref $val eq 'ARRAY') ? $val->[0] : $val; 




1317




 





 





 





 





 





 



 } 




1318




 





 





 





 





 





 



   




1319




 





 





 





 





 





 



   




1320




 





 





 





 





 





 



 =item params 




1321




 





 





 





 





 





 



   




1322




 





 





 





 





 





 



 Returns a hashref of request parameters.  




1323




 





 





 





 





 





 



   




1324




 





 





 





 





 





 



 B Where muliple values of a parameter were supplied, the C value 




1325




 





 





 





 





 





 



 will be an array reference. 




1326




 





 





 





 





 





 



   




1327




 





 





 





 





 





 



 =item query 




1328




 





 





 





 





 





 



   




1329




 





 





 





 





 





 



 Alias for C. 




1330




 





 





 





 





 





 



   




1331




 





 





 





 





 





 



 =back 




1332




 





 





 





 





 





 



   




1333




 





 





 





 





 





 



 =head3 Utility methods 




1334




 





 





 





 





 





 



   




1335




 





 





 





 





 





 



 =over 4 




1336




 





 





 





 





 





 



   




1337




 





 





 





 





 





 



 =item redirect_request 




1338




 





 





 





 





 





 



   




1339




 





 





 





 





 





 



 Sets output headers to redirect based on the arguments provided 




1340




 





 





 





 





 





 



   




1341




 





 





 





 





 





 



 Accepts either a single argument of the full url to redirect to, or a hash of 




1342




 





 





 





 





 





 



 named parameters : 




1343




 





 





 





 





 





 



   




1344




 





 





 





 





 





 



 $r->redirect_request('http://www.example.com/path'); 




1345




 





 





 





 





 





 



   




1346




 





 





 





 





 





 



 or 




1347




 





 





 





 





 





 



   




1348




 





 





 





 





 





 



 $r->redirect_request(protocol=>'https', domain=>'www.example.com', path=>'/path/file?arguments', status=>'302', url=>'..'); 




1349




 





 





 





 





 





 



   




1350




 





 





 





 





 





 



 The named parameters are protocol, domain, path, status and url 




1351




 





 





 





 





 





 



   




1352




 





 





 





 





 





 



 Only 1 named parameter is required but other than url, they can be combined as 




1353




 





 





 





 





 





 



 required and current values (from the request) will be used in place of any 




1354




 





 





 





 





 





 



 missing arguments. The url argument must be a full url including protocol and 




1355




 





 





 





 





 





 



 can only be combined with status. 




1356




 





 





 





 





 





 



   




1357




 





 





 





 





 





 



 =cut 




1358




 





 





 





 





 





 



   




1359




 





 





 





 





 





 



 sub redirect_request { 




1360




 





 





 





 





 





 



   die "redirect_request is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; 




1361




 





 





 





 





 





 



 } 




1362




 





 





 





 





 





 



   




1363




 





 





 





 





 





 



 # =item redirect_internal_request 




1364




 





 





 





 





 





 



 # 




1365




 





 





 





 





 





 



 # =cut 




1366




 





 





 





 





 





 



 # 




1367




 





 





 





 





 





 



 # sub redirect_internal_request { 




1368




 





 





 





 





 





 



 # 




1369




 





 





 





 





 





 



 # } 




1370




 





 





 





 





 





 



   




1371




 





 





 





 





 





 



   




1372




 





 





 





 





 





 



 =item make_random_id 




1373




 





 





 





 





 





 



   




1374




 





 





 





 





 





 



 returns a unique id for this request can be used to prevent or detect repeat 




1375




 





 





 





 





 





 



 submissions. 




1376




 





 





 





 





 





 



   




1377




 





 





 





 





 





 



 =cut 




1378




 





 





 





 





 





 



   




1379




 





 





 





 





 





 



 # Session and Repeat Submission Handling 




1380




 





 





 





 





 





 



 sub make_random_id { 




1381




 





 





 





 





 





 



     use Maypole::Session; 




1382




 





 





 





 





 





 



     return Maypole::Session::generate_unique_id(); 




1383




 





 





 





 





 





 



 } 




1384




 





 





 





 





 





 



   




1385




 





 





 





 





 





 



 =back 




1386




 





 





 





 





 





 



   




1387




 





 





 





 





 





 



 =head1 SEQUENCE DIAGRAMS 




1388




 





 





 





 





 





 



   




1389




 





 





 





 





 





 



 See L for a detailed discussion of the sequence of  




1390




 





 





 





 





 





 



 calls during processing of a request. This is a brief summary: 




1391




 





 





 





 





 





 



   




1392




 





 





 





 





 





 



     INITIALIZATION 




1393




 





 





 





 





 





 



                                Model e.g. 




1394




 





 





 





 





 





 



          BeerDB           Maypole::Model::CDBI 




1395




 





 





 





 





 





 



            |                        | 




1396




 





 





 





 





 





 



    setup   |                        | 




1397




 





 





 





 





 





 



  o-------->||                       | 




1398




 





 





 





 





 





 



            || setup_model           |     setup_database() creates 




1399




 





 





 





 





 





 



            ||------+                |      a subclass of the Model 




1400




 





 





 





 





 





 



            |||<----+                |        for each table 




1401




 





 





 





 





 





 



            |||                      |                | 




1402




 





 





 





 





 





 



            |||   setup_database     |                | 




1403




 





 





 





 





 





 



            |||--------------------->|| 'create'      * 




1404




 





 





 





 





 





 



            |||                      ||----------> $subclass 




1405




 





 





 





 





 





 



            |||                      |                  | 




1406




 





 





 





 





 





 



            ||| load_model_subclass  |                  | 




1407




 





 





 





 





 





 



  foreach   |||------+  ($subclass)  |                  | 




1408




 





 





 





 





 





 



  $subclass ||||<----+               |    require       | 




1409




 





 





 





 





 





 



            ||||--------------------------------------->| 




1410




 





 





 





 





 





 



            |||                      |                  | 




1411




 





 





 





 





 





 



            |||   adopt($subclass)   |                  | 




1412




 





 





 





 





 





 



            |||--------------------->||                 | 




1413




 





 





 





 





 





 



            |                        |                  | 




1414




 





 





 





 





 





 



            |                        |                  | 




1415




 





 





 





 





 





 



            |-----+ init             |                  | 




1416




 





 





 





 





 





 



            ||<---+                  |                  | 




1417




 





 





 





 





 





 



            ||                       |     new          |     view_object: e.g. 




1418




 





 





 





 





 





 



            ||---------------------------------------------> Maypole::View::TT 




1419




 





 





 





 





 





 



            |                        |                  |          | 




1420




 





 





 





 





 





 



            |                        |                  |          | 




1421




 





 





 





 





 





 



            |                        |                  |          | 




1422




 





 





 





 





 





 



            |                        |                  |          | 




1423




 





 





 





 





 





 



            |                        |                  |          | 




1424




 





 





 





 





 





 



             




1425




 





 





 





 





 





 



   




1426




 





 





 





 





 





 



   




1427




 





 





 





 





 





 



     HANDLING A REQUEST 




1428




 





 





 





 





 





 



   




1429




 





 





 





 





 





 



   




1430




 





 





 





 





 





 



           BeerDB                                Model  $subclass  view_object 




1431




 





 





 





 





 





 



             |                                      |       |         | 




1432




 





 





 





 





 





 



     handler |                                      |       |         | 




1433




 





 





 





 





 





 



   o-------->| new                                  |       |         | 




1434




 





 





 





 





 





 



             |-----> r:BeerDB                       |       |         | 




1435




 





 





 





 





 





 



             |         |                            |       |         | 




1436




 





 





 





 





 





 



             |         |                            |       |         | 




1437




 





 





 





 





 





 



             |         ||                           |       |         | 




1438




 





 





 





 





 





 



             |         ||-----+ parse_location      |       |         | 




1439




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1440




 





 





 





 





 





 



             |         ||                           |       |         | 




1441




 





 





 





 





 





 



             |         ||-----+ start_request_hook  |       |         | 




1442




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1443




 





 





 





 





 





 



             |         ||                           |       |         | 




1444




 





 





 





 





 





 



             |         ||-----+ get_session         |       |         | 




1445




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1446




 





 





 





 





 





 



             |         ||                           |       |         | 




1447




 





 





 





 





 





 



             |         ||-----+ get_user            |       |         | 




1448




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1449




 





 





 





 





 





 



             |         ||                           |       |         | 




1450




 





 





 





 





 





 



             |         ||-----+ handler_guts        |       |         | 




1451




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1452




 





 





 





 





 





 



             |         |||     class_of($table)     |       |         | 




1453




 





 





 





 





 





 



             |         |||------------------------->||      |         | 




1454




 





 





 





 





 





 



             |         |||       $subclass          ||      |         | 




1455




 





 





 





 





 





 



             |         |||<-------------------------||      |         | 




1456




 





 





 





 





 





 



             |         |||                          |       |         | 




1457




 





 





 





 





 





 



             |         |||-----+ is_model_applicable|       |         | 




1458




 





 





 





 





 





 



             |         ||||<---+                    |       |         | 




1459




 





 





 





 





 





 



             |         |||                          |       |         | 




1460




 





 





 





 





 





 



             |         |||-----+ call_authenticate  |       |         | 




1461




 





 





 





 





 





 



             |         ||||<---+                    |       |         | 




1462




 





 





 





 





 





 



             |         |||                          |       |         | 




1463




 





 





 





 





 





 



             |         |||-----+ additional_data    |       |         | 




1464




 





 





 





 





 





 



             |         ||||<---+                    |       |         | 




1465




 





 





 





 





 





 



             |         |||             process      |       |         | 




1466




 





 





 





 





 





 



             |         |||--------------------------------->||  fetch_objects 




1467




 





 





 





 





 





 



             |         |||                          |       ||-----+  | 




1468




 





 





 





 





 





 



             |         |||                          |       |||<---+  | 




1469




 





 





 





 





 





 



             |         |||                          |       ||        | 




1470




 





 





 





 





 





 



             |         |||                          |       ||   $action 




1471




 





 





 





 





 





 



             |         |||                          |       ||-----+  | 




1472




 





 





 





 





 





 



             |         |||                          |       |||<---+  |             




1473




 





 





 





 





 





 



             |         |||         process          |       |         | 




1474




 





 





 





 





 





 



             |         |||------------------------------------------->|| template 




1475




 





 





 





 





 





 



             |         |||                          |       |         ||-----+ 




1476




 





 





 





 





 





 



             |         |||                          |       |         |||<---+ 




1477




 





 





 





 





 





 



             |         |||                          |       |         | 




1478




 





 





 





 





 





 



             |         ||     send_output           |       |         | 




1479




 





 





 





 





 





 



             |         ||-----+                     |       |         | 




1480




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1481




 





 





 





 





 





 



    $status  |         ||                           |       |         | 




1482




 





 





 





 





 





 



    <------------------||                           |       |         | 




1483




 





 





 





 





 





 



             |         |                            |       |         | 




1484




 





 





 





 





 





 



             |         X                            |       |         |            




1485




 





 





 





 





 





 



             |                                      |       |         | 




1486




 





 





 





 





 





 



             |                                      |       |         | 




1487




 





 





 





 





 





 



             |                                      |       |         | 




1488




 





 





 





 





 





 



             




1489




 





 





 





 





 





 



             




1490




 





 





 





 





 





 



   




1491




 





 





 





 





 





 



 =head1 SEE ALSO 




1492




 





 





 





 





 





 



   




1493




 





 





 





 





 





 



 There's more documentation, examples, and information on our mailing lists 




1494




 





 





 





 





 





 



 at the Maypole web site: 




1495




 





 





 





 





 





 



   




1496




 





 





 





 





 





 



 L 




1497




 





 





 





 





 





 



   




1498




 





 





 





 





 





 



 L, L, L. 




1499




 





 





 





 





 





 



   




1500




 





 





 





 





 





 



 =head1 AUTHOR 




1501




 





 





 





 





 





 



   




1502




 





 





 





 





 





 



 Maypole is currently maintained by Aaron Trevena. 




1503




 





 





 





 





 





 



   




1504




 





 





 





 





 





 



 =head1 AUTHOR EMERITUS 




1505




 





 





 





 





 





 



   




1506




 





 





 





 





 





 



 Simon Cozens, C 




1507




 





 





 





 





 





 



   




1508




 





 





 





 





 





 



 Simon Flack maintained Maypole from 2.05 to 2.09 




1509




 





 





 





 





 





 



   




1510




 





 





 





 





 





 



 Sebastian Riedel, C maintained Maypole from 1.99_01 to 2.04 




1511




 





 





 





 





 





 



   




1512




 





 





 





 





 





 



 =head1 THANKS TO 




1513




 





 





 





 





 





 



   




1514




 





 





 





 





 





 



 Sebastian Riedel, Danijel Milicevic, Dave Slack, Jesse Sheidlower, Jody Belka, 




1515




 





 





 





 





 





 



 Marcus Ramberg, Mickael Joanne, Randal Schwartz, Simon Flack, Steve Simms, 




1516




 





 





 





 





 





 



 Veljko Vidovic and all the others who've helped. 




1517




 





 





 





 





 





 



   




1518




 





 





 





 





 





 



 =head1 LICENSE 




1519




 





 





 





 





 





 



   




1520




 





 





 





 





 





 



 You may distribute this code under the same terms as Perl itself. 




1521




 





 





 





 





 





 



   




1522




 





 





 





 





 





 



 =cut 




1523




 





 





 





 





 





 



   




1524




 





 





 





 





 





 



 1; 




1525




 





 





 





 





 





 



   




1526




 





 





 





 





 





 



 __END__
properties. Calls C before parsing path and setting properties.

=cut

sub parse_path {
    my ($self) = @_;

    # Previous versions unconditionally set table, action and args to whatever
    # was in @pi (or else to defaults, if @pi is empty).
    # Adding preprocess_path(), and then setting table, action and args
    # conditionally, broke lots of tests, hence this:
    $self->$_(undef) for qw/action table args/;
    $self->preprocess_path;

    # use frontpage template for frontpage
    unless ($self->path && $self->path ne '/') {
      $self->path('frontpage');
    }

    my @pi = grep {length} split '/', $self->path;

    $self->table  || $self->table(shift @pi);
    $self->action || $self->action( shift @pi or 'index' );
    $self->args   || $self->args(\@pi);
}

=item preprocess_path

Sometimes when you don't want to rewrite or over-ride parse_path but
want to rewrite urls or extract data from them before it is parsed,
the preprocess_path/location methods allow you to munge paths and urls
before maypole maps them to actions, classes, etc.

This method is called after parse_location has populated the request
information and before parse_path has populated the model and action
information, and is passed the request object.

You can set action, args or table in this method and parse_path will
then leave those values in place or populate them based on the current
value of the path attribute if they are not present.

=cut

sub preprocess_path { };

=item preprocess_location

This method is called at the start of parse_location, after the headers in, and allows you
to rewrite the url used by maypole, or dynamically set configuration
like the base_uri based on the hostname or path.

=cut

sub preprocess_location { };

=item make_path( %args or \%args or @args )

This is the counterpart to C. It generates a path to use
in links, form actions etc. To implement your own path scheme, just override
this method and C.

    %args = ( table      => $table,
              action     => $action,
              additional => $additional,    # optional - generally an object ID
              );

    \%args = as above, but a ref

    @args = ( $table, $action, $additional );   # $additional is optional

C can be used as an alternative key to C.

C<$additional> can be a string, an arrayref, or a hashref. An arrayref is
expanded into extra path elements, whereas a hashref is translated into a query
string.

=cut


sub make_path
{
    my $r = shift;

    my %args;

    if (@_ == 1 and ref $_[0] and ref $_[0] eq 'HASH')
    {
        %args = %{$_[0]};
    }
    elsif ( @_ > 1 and @_ < 4 )
    {
        $args{table}      = shift;
        $args{action}     = shift;
        $args{additional} = shift;
    }
    else
    {
        %args = @_;
    }

    do { die "no $_" unless $args{$_} } for qw( table action );

    my $additional = $args{additional} || $args{id};

    my @add = ();

    if ($additional)
    {
        # if $additional is a href, make_uri() will transform it into a query
        @add = (ref $additional eq 'ARRAY') ? @$additional : ($additional);
    }

    my $uri = $r->make_uri($args{table}, $args{action}, @add);

    return $uri->as_string;
}



=item make_uri( @segments )

Make a L object given table, action etc. Automatically adds
the C.

If the final element in C<@segments> is a hash ref, C will render it
as a query string.

=cut

sub make_uri
{
    my ($r, @segments) = @_;

    my $query = (ref $segments[-1] eq 'HASH') ? pop(@segments) : undef;

    my $base = $r->config->uri_base;
    $base =~ s|/$||;

    my $uri = URI->new($base);
    $uri->path_segments($uri->path_segments, grep {length} @segments);

    my $abs_uri = $uri->abs('/');
    $abs_uri->query_form($query) if $query;
    return $abs_uri;
}

=item parse_args

Turns post data and query string paramaters into a hash of C.

You should only need to define this method if you are writing a new Maypole
backend.

=cut

sub parse_args
{
    die "parse_args() is a virtual method. Do not use Maypole directly; ".
            "use Apache::MVC or similar";
}

=item get_template_root

Implementation-specific path to template root.

You should only need to define this method if you are writing a new Maypole
backend. Otherwise, see L

=cut

=back

=head2 Request properties

=over 4

=item model_class

Returns the perl package name that will serve as the model for the
request. It corresponds to the request C attribute. 




1166




 





 





 





 





 





 



   




1167




 





 





 





 





 





 



   




1168




 





 





 





 





 





 



 =item objects 




1169




 





 





 





 





 





 



   




1170




 





 





 





 





 





 



 Get/set a list of model objects. The objects will be accessible in the view 




1171




 





 





 





 





 





 



 templates. 




1172




 





 





 





 





 





 



   




1173




 





 





 





 





 





 



 If the first item in C<$self-Eargs> can be Cd by the model 




1174




 





 





 





 





 





 



 class, it will be removed from C and the retrieved object will be added to 




1175




 





 





 





 





 





 



 the C list. See L for more information. 




1176




 





 





 





 





 





 



   




1177




 





 





 





 





 





 



   




1178




 





 





 





 





 





 



 =item object 




1179




 





 





 





 





 





 



   




1180




 





 





 





 





 





 



 Alias to get/set the first/only model object. The object will be accessible 




1181




 





 





 





 





 





 



 in the view templates. 




1182




 





 





 





 





 





 



   




1183




 





 





 





 





 





 



 When used to set the object, will overwrite the request objects 




1184




 





 





 





 





 





 



 with a single object. 




1185




 





 





 





 





 





 



   




1186




 





 





 





 





 





 



 =cut 




1187




 





 





 





 





 





 



   




1188




 





 





 





 





 





 



 sub object { 




1189




 





 





 





 





 





 



   my ($r,$object) = @_; 




1190




 





 





 





 





 





 



   $r->objects([$object]) if ($object); 




1191




 





 





 





 





 





 



   return undef unless $r->objects(); 




1192




 





 





 





 





 





 



   return $r->objects->[0]; 




1193




 





 





 





 





 





 



 } 




1194




 





 





 





 





 





 



   




1195




 





 





 





 





 





 



 =item template_args 




1196




 





 





 





 





 





 



   




1197




 





 





 





 





 





 



     $self->template_args->{foo} = 'bar'; 




1198




 





 





 





 





 





 



   




1199




 





 





 





 





 





 



 Get/set a hash of template variables. 




1200




 





 





 





 





 





 



   




1201




 





 





 





 





 





 



 Maypole reserved words for template variables will over-ride values in template_variables. 




1202




 





 





 





 





 





 



   




1203




 





 





 





 





 





 



 Reserved words are : r, request, object, objects, base, config and errors, as well as the 




1204




 





 





 





 





 





 



 current class or object name. 




1205




 





 





 





 





 





 



   




1206




 





 





 





 





 





 



 =item stash 




1207




 





 





 





 





 





 



   




1208




 





 





 





 





 





 



 A place to put custom application data. Not used by Maypole itself. 




1209




 





 





 





 





 





 



   




1210




 





 





 





 





 





 



 =item template 




1211




 





 





 





 





 





 



   




1212




 





 





 





 





 





 



 Get/set the template to be used by the view. By default, it returns 




1213




 





 





 





 





 





 



 C<$self-Eaction> 




1214




 





 





 





 





 





 



   




1215




 





 





 





 





 





 



   




1216




 





 





 





 





 





 



 =item error 




1217




 





 





 





 





 





 



   




1218




 





 





 





 





 





 



 Get/set a request error 




1219




 





 





 





 





 





 



   




1220




 





 





 





 





 





 



 =item output 




1221




 





 





 





 





 





 



   




1222




 





 





 





 





 





 



 Get/set the response output. This is usually populated by the view class. You 




1223




 





 





 





 





 





 



 can skip view processing by setting the C. 




1224




 





 





 





 





 





 



   




1225




 





 





 





 





 





 



 =item table 




1226




 





 





 





 





 





 



   




1227




 





 





 





 





 





 



 The table part of the Maypole request path 




1228




 





 





 





 





 





 



   




1229




 





 





 





 





 





 



 =item action 




1230




 





 





 





 





 





 



   




1231




 





 





 





 





 





 



 The action part of the Maypole request path 




1232




 





 





 





 





 





 



   




1233




 





 





 





 





 





 



 =item args 




1234




 





 





 





 





 





 



   




1235




 





 





 





 





 





 



 A list of remaining parts of the request path after table and action 




1236




 





 





 





 





 





 



 have been 




1237




 





 





 





 





 





 



 removed 




1238




 





 





 





 





 





 



   




1239




 





 





 





 





 





 



 =item headers_in 




1240




 





 





 





 





 





 



   




1241




 





 





 





 





 





 



 A L object containing HTTP headers for the request 




1242




 





 





 





 





 





 



   




1243




 





 





 





 





 





 



 =item headers_out 




1244




 





 





 





 





 





 



   




1245




 





 





 





 





 





 



 A L object that contains HTTP headers for the output 




1246




 





 





 





 





 





 



   




1247




 





 





 





 





 





 



 =item document_encoding 




1248




 





 





 





 





 





 



   




1249




 





 





 





 





 





 



 Get/set the output encoding. Default: utf-8. 




1250




 





 





 





 





 





 



   




1251




 





 





 





 





 





 



 =item content_type 




1252




 





 





 





 





 





 



   




1253




 





 





 





 





 





 



 Get/set the output content type. Default: text/html 




1254




 





 





 





 





 





 



   




1255




 





 





 





 





 





 



 =item get_protocol 




1256




 





 





 





 





 





 



   




1257




 





 





 





 





 





 



 Returns the protocol the request was made with, i.e. https 




1258




 





 





 





 





 





 



   




1259




 





 





 





 





 





 



 =cut 




1260




 





 





 





 





 





 



   




1261




 





 





 





 





 





 



 sub get_protocol { 




1262




 





 





 





 





 





 



   die "get_protocol is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; 




1263




 





 





 





 





 





 



 } 




1264




 





 





 





 





 





 



   




1265




 





 





 





 





 





 



 =back 




1266




 





 





 





 





 





 



   




1267




 





 





 





 





 





 



 =head2 Request parameters 




1268




 





 





 





 





 





 



   




1269




 





 





 





 





 





 



 The source of the parameters may vary depending on the Maypole backend, but they 




1270




 





 





 





 





 





 



 are usually populated from request query string and POST data. 




1271




 





 





 





 





 





 



   




1272




 





 





 





 





 





 



 Maypole supplies several approaches for accessing the request parameters. Note 




1273




 





 





 





 





 





 



 that the current implementation (via a hashref) of C and C is 




1274




 





 





 





 





 





 



 likely to change in a future version of Maypole. So avoid direct access to these 




1275




 





 





 





 





 





 



 hashrefs: 




1276




 





 





 





 





 





 



   




1277




 





 





 





 





 





 



     $r->{params}->{foo}      # bad 




1278




 





 





 





 





 





 



     $r->params->{foo}        # better 




1279




 





 





 





 





 





 



   




1280




 





 





 





 





 





 



     $r->{query}->{foo}       # bad 




1281




 





 





 





 





 





 



     $r->query->{foo}         # better 




1282




 





 





 





 





 





 



   




1283




 





 





 





 





 





 



     $r->param('foo')         # best 




1284




 





 





 





 





 





 



   




1285




 





 





 





 





 





 



 =over 4 




1286




 





 





 





 





 





 



   




1287




 





 





 





 





 





 



 =item param 




1288




 





 





 





 





 





 



   




1289




 





 





 





 





 





 



 An accessor (get or set) for request parameters. It behaves similarly to 




1290




 





 





 





 





 





 



 CGI::param() for accessing CGI parameters, i.e. 




1291




 





 





 





 





 





 



   




1292




 





 





 





 





 





 



     $r->param                   # returns list of keys 




1293




 





 





 





 





 





 



     $r->param($key)             # returns value for $key 




1294




 





 





 





 





 





 



     $r->param($key => $value)   # returns old value, sets to new value 




1295




 





 





 





 





 





 



   




1296




 





 





 





 





 





 



 =cut 




1297




 





 





 





 





 





 



   




1298




 





 





 





 





 





 



 sub param  




1299




 





 





 





 





 





 



 {  




1300




 





 





 





 





 





 



     my ($self, $key) = (shift, shift); 




1301




 





 





 





 





 





 



      




1302




 





 





 





 





 





 



     return keys %{$self->params} unless defined $key; 




1303




 





 





 





 





 





 



      




1304




 





 





 





 





 





 



     return unless exists $self->params->{$key}; 




1305




 





 





 





 





 





 



      




1306




 





 





 





 





 





 



     my $val = $self->params->{$key}; 




1307




 





 





 





 





 





 



      




1308




 





 





 





 





 





 



     if (@_) 




1309




 





 





 





 





 





 



     { 




1310




 





 





 





 





 





 



         my $new_val = shift; 




1311




 





 





 





 





 





 



 	$self->params->{$key} = $new_val; 




1312




 





 





 





 





 





 



     } 




1313




 





 





 





 





 





 



      




1314




 





 





 





 





 





 



     return (ref $val eq 'ARRAY') ? @$val : ($val) if wantarray; 




1315




 





 





 





 





 





 



          




1316




 





 





 





 





 





 



     return (ref $val eq 'ARRAY') ? $val->[0] : $val; 




1317




 





 





 





 





 





 



 } 




1318




 





 





 





 





 





 



   




1319




 





 





 





 





 





 



   




1320




 





 





 





 





 





 



 =item params 




1321




 





 





 





 





 





 



   




1322




 





 





 





 





 





 



 Returns a hashref of request parameters.  




1323




 





 





 





 





 





 



   




1324




 





 





 





 





 





 



 B Where muliple values of a parameter were supplied, the C value 




1325




 





 





 





 





 





 



 will be an array reference. 




1326




 





 





 





 





 





 



   




1327




 





 





 





 





 





 



 =item query 




1328




 





 





 





 





 





 



   




1329




 





 





 





 





 





 



 Alias for C. 




1330




 





 





 





 





 





 



   




1331




 





 





 





 





 





 



 =back 




1332




 





 





 





 





 





 



   




1333




 





 





 





 





 





 



 =head3 Utility methods 




1334




 





 





 





 





 





 



   




1335




 





 





 





 





 





 



 =over 4 




1336




 





 





 





 





 





 



   




1337




 





 





 





 





 





 



 =item redirect_request 




1338




 





 





 





 





 





 



   




1339




 





 





 





 





 





 



 Sets output headers to redirect based on the arguments provided 




1340




 





 





 





 





 





 



   




1341




 





 





 





 





 





 



 Accepts either a single argument of the full url to redirect to, or a hash of 




1342




 





 





 





 





 





 



 named parameters : 




1343




 





 





 





 





 





 



   




1344




 





 





 





 





 





 



 $r->redirect_request('http://www.example.com/path'); 




1345




 





 





 





 





 





 



   




1346




 





 





 





 





 





 



 or 




1347




 





 





 





 





 





 



   




1348




 





 





 





 





 





 



 $r->redirect_request(protocol=>'https', domain=>'www.example.com', path=>'/path/file?arguments', status=>'302', url=>'..'); 




1349




 





 





 





 





 





 



   




1350




 





 





 





 





 





 



 The named parameters are protocol, domain, path, status and url 




1351




 





 





 





 





 





 



   




1352




 





 





 





 





 





 



 Only 1 named parameter is required but other than url, they can be combined as 




1353




 





 





 





 





 





 



 required and current values (from the request) will be used in place of any 




1354




 





 





 





 





 





 



 missing arguments. The url argument must be a full url including protocol and 




1355




 





 





 





 





 





 



 can only be combined with status. 




1356




 





 





 





 





 





 



   




1357




 





 





 





 





 





 



 =cut 




1358




 





 





 





 





 





 



   




1359




 





 





 





 





 





 



 sub redirect_request { 




1360




 





 





 





 





 





 



   die "redirect_request is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; 




1361




 





 





 





 





 





 



 } 




1362




 





 





 





 





 





 



   




1363




 





 





 





 





 





 



 # =item redirect_internal_request 




1364




 





 





 





 





 





 



 # 




1365




 





 





 





 





 





 



 # =cut 




1366




 





 





 





 





 





 



 # 




1367




 





 





 





 





 





 



 # sub redirect_internal_request { 




1368




 





 





 





 





 





 



 # 




1369




 





 





 





 





 





 



 # } 




1370




 





 





 





 





 





 



   




1371




 





 





 





 





 





 



   




1372




 





 





 





 





 





 



 =item make_random_id 




1373




 





 





 





 





 





 



   




1374




 





 





 





 





 





 



 returns a unique id for this request can be used to prevent or detect repeat 




1375




 





 





 





 





 





 



 submissions. 




1376




 





 





 





 





 





 



   




1377




 





 





 





 





 





 



 =cut 




1378




 





 





 





 





 





 



   




1379




 





 





 





 





 





 



 # Session and Repeat Submission Handling 




1380




 





 





 





 





 





 



 sub make_random_id { 




1381




 





 





 





 





 





 



     use Maypole::Session; 




1382




 





 





 





 





 





 



     return Maypole::Session::generate_unique_id(); 




1383




 





 





 





 





 





 



 } 




1384




 





 





 





 





 





 



   




1385




 





 





 





 





 





 



 =back 




1386




 





 





 





 





 





 



   




1387




 





 





 





 





 





 



 =head1 SEQUENCE DIAGRAMS 




1388




 





 





 





 





 





 



   




1389




 





 





 





 





 





 



 See L for a detailed discussion of the sequence of  




1390




 





 





 





 





 





 



 calls during processing of a request. This is a brief summary: 




1391




 





 





 





 





 





 



   




1392




 





 





 





 





 





 



     INITIALIZATION 




1393




 





 





 





 





 





 



                                Model e.g. 




1394




 





 





 





 





 





 



          BeerDB           Maypole::Model::CDBI 




1395




 





 





 





 





 





 



            |                        | 




1396




 





 





 





 





 





 



    setup   |                        | 




1397




 





 





 





 





 





 



  o-------->||                       | 




1398




 





 





 





 





 





 



            || setup_model           |     setup_database() creates 




1399




 





 





 





 





 





 



            ||------+                |      a subclass of the Model 




1400




 





 





 





 





 





 



            |||<----+                |        for each table 




1401




 





 





 





 





 





 



            |||                      |                | 




1402




 





 





 





 





 





 



            |||   setup_database     |                | 




1403




 





 





 





 





 





 



            |||--------------------->|| 'create'      * 




1404




 





 





 





 





 





 



            |||                      ||----------> $subclass 




1405




 





 





 





 





 





 



            |||                      |                  | 




1406




 





 





 





 





 





 



            ||| load_model_subclass  |                  | 




1407




 





 





 





 





 





 



  foreach   |||------+  ($subclass)  |                  | 




1408




 





 





 





 





 





 



  $subclass ||||<----+               |    require       | 




1409




 





 





 





 





 





 



            ||||--------------------------------------->| 




1410




 





 





 





 





 





 



            |||                      |                  | 




1411




 





 





 





 





 





 



            |||   adopt($subclass)   |                  | 




1412




 





 





 





 





 





 



            |||--------------------->||                 | 




1413




 





 





 





 





 





 



            |                        |                  | 




1414




 





 





 





 





 





 



            |                        |                  | 




1415




 





 





 





 





 





 



            |-----+ init             |                  | 




1416




 





 





 





 





 





 



            ||<---+                  |                  | 




1417




 





 





 





 





 





 



            ||                       |     new          |     view_object: e.g. 




1418




 





 





 





 





 





 



            ||---------------------------------------------> Maypole::View::TT 




1419




 





 





 





 





 





 



            |                        |                  |          | 




1420




 





 





 





 





 





 



            |                        |                  |          | 




1421




 





 





 





 





 





 



            |                        |                  |          | 




1422




 





 





 





 





 





 



            |                        |                  |          | 




1423




 





 





 





 





 





 



            |                        |                  |          | 




1424




 





 





 





 





 





 



             




1425




 





 





 





 





 





 



   




1426




 





 





 





 





 





 



   




1427




 





 





 





 





 





 



     HANDLING A REQUEST 




1428




 





 





 





 





 





 



   




1429




 





 





 





 





 





 



   




1430




 





 





 





 





 





 



           BeerDB                                Model  $subclass  view_object 




1431




 





 





 





 





 





 



             |                                      |       |         | 




1432




 





 





 





 





 





 



     handler |                                      |       |         | 




1433




 





 





 





 





 





 



   o-------->| new                                  |       |         | 




1434




 





 





 





 





 





 



             |-----> r:BeerDB                       |       |         | 




1435




 





 





 





 





 





 



             |         |                            |       |         | 




1436




 





 





 





 





 





 



             |         |                            |       |         | 




1437




 





 





 





 





 





 



             |         ||                           |       |         | 




1438




 





 





 





 





 





 



             |         ||-----+ parse_location      |       |         | 




1439




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1440




 





 





 





 





 





 



             |         ||                           |       |         | 




1441




 





 





 





 





 





 



             |         ||-----+ start_request_hook  |       |         | 




1442




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1443




 





 





 





 





 





 



             |         ||                           |       |         | 




1444




 





 





 





 





 





 



             |         ||-----+ get_session         |       |         | 




1445




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1446




 





 





 





 





 





 



             |         ||                           |       |         | 




1447




 





 





 





 





 





 



             |         ||-----+ get_user            |       |         | 




1448




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1449




 





 





 





 





 





 



             |         ||                           |       |         | 




1450




 





 





 





 





 





 



             |         ||-----+ handler_guts        |       |         | 




1451




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1452




 





 





 





 





 





 



             |         |||     class_of($table)     |       |         | 




1453




 





 





 





 





 





 



             |         |||------------------------->||      |         | 




1454




 





 





 





 





 





 



             |         |||       $subclass          ||      |         | 




1455




 





 





 





 





 





 



             |         |||<-------------------------||      |         | 




1456




 





 





 





 





 





 



             |         |||                          |       |         | 




1457




 





 





 





 





 





 



             |         |||-----+ is_model_applicable|       |         | 




1458




 





 





 





 





 





 



             |         ||||<---+                    |       |         | 




1459




 





 





 





 





 





 



             |         |||                          |       |         | 




1460




 





 





 





 





 





 



             |         |||-----+ call_authenticate  |       |         | 




1461




 





 





 





 





 





 



             |         ||||<---+                    |       |         | 




1462




 





 





 





 





 





 



             |         |||                          |       |         | 




1463




 





 





 





 





 





 



             |         |||-----+ additional_data    |       |         | 




1464




 





 





 





 





 





 



             |         ||||<---+                    |       |         | 




1465




 





 





 





 





 





 



             |         |||             process      |       |         | 




1466




 





 





 





 





 





 



             |         |||--------------------------------->||  fetch_objects 




1467




 





 





 





 





 





 



             |         |||                          |       ||-----+  | 




1468




 





 





 





 





 





 



             |         |||                          |       |||<---+  | 




1469




 





 





 





 





 





 



             |         |||                          |       ||        | 




1470




 





 





 





 





 





 



             |         |||                          |       ||   $action 




1471




 





 





 





 





 





 



             |         |||                          |       ||-----+  | 




1472




 





 





 





 





 





 



             |         |||                          |       |||<---+  |             




1473




 





 





 





 





 





 



             |         |||         process          |       |         | 




1474




 





 





 





 





 





 



             |         |||------------------------------------------->|| template 




1475




 





 





 





 





 





 



             |         |||                          |       |         ||-----+ 




1476




 





 





 





 





 





 



             |         |||                          |       |         |||<---+ 




1477




 





 





 





 





 





 



             |         |||                          |       |         | 




1478




 





 





 





 





 





 



             |         ||     send_output           |       |         | 




1479




 





 





 





 





 





 



             |         ||-----+                     |       |         | 




1480




 





 





 





 





 





 



             |         |||<---+                     |       |         | 




1481




 





 





 





 





 





 



    $status  |         ||                           |       |         | 




1482




 





 





 





 





 





 



    <------------------||                           |       |         | 




1483




 





 





 





 





 





 



             |         |                            |       |         | 




1484




 





 





 





 





 





 



             |         X                            |       |         |            




1485




 





 





 





 





 





 



             |                                      |       |         | 




1486




 





 





 





 





 





 



             |                                      |       |         | 




1487




 





 





 





 





 





 



             |                                      |       |         | 




1488




 





 





 





 





 





 



             




1489




 





 





 





 





 





 



             




1490




 





 





 





 





 





 



   




1491




 





 





 





 





 





 



 =head1 SEE ALSO 




1492




 





 





 





 





 





 



   




1493




 





 





 





 





 





 



 There's more documentation, examples, and information on our mailing lists 




1494




 





 





 





 





 





 



 at the Maypole web site: 




1495




 





 





 





 





 





 



   




1496




 





 





 





 





 





 



 L 




1497




 





 





 





 





 





 



   




1498




 





 





 





 





 





 



 L, L, L. 




1499




 





 





 





 





 





 



   




1500




 





 





 





 





 





 



 =head1 AUTHOR 




1501




 





 





 





 





 





 



   




1502




 





 





 





 





 





 



 Maypole is currently maintained by Aaron Trevena. 




1503




 





 





 





 





 





 



   




1504




 





 





 





 





 





 



 =head1 AUTHOR EMERITUS 




1505




 





 





 





 





 





 



   




1506




 





 





 





 





 





 



 Simon Cozens, C 




1507




 





 





 





 





 





 



   




1508




 





 





 





 





 





 



 Simon Flack maintained Maypole from 2.05 to 2.09 




1509




 





 





 





 





 





 



   




1510




 





 





 





 





 





 



 Sebastian Riedel, C maintained Maypole from 1.99_01 to 2.04 




1511




 





 





 





 





 





 



   




1512




 





 





 





 





 





 



 =head1 THANKS TO 




1513




 





 





 





 





 





 



   




1514




 





 





 





 





 





 



 Sebastian Riedel, Danijel Milicevic, Dave Slack, Jesse Sheidlower, Jody Belka, 




1515




 





 





 





 





 





 



 Marcus Ramberg, Mickael Joanne, Randal Schwartz, Simon Flack, Steve Simms, 




1516




 





 





 





 





 





 



 Veljko Vidovic and all the others who've helped. 




1517




 





 





 





 





 





 



   




1518




 





 





 





 





 





 



 =head1 LICENSE 




1519




 





 





 





 





 





 



   




1520




 





 





 





 





 





 



 You may distribute this code under the same terms as Perl itself. 




1521




 





 





 





 





 





 



   




1522




 





 





 





 





 





 



 =cut 




1523




 





 





 





 





 





 



   




1524




 





 





 





 





 





 



 1; 




1525




 





 





 





 





 





 



   




1526




 





 





 





 





 





 



 __END__


=item objects

Get/set a list of model objects. The objects will be accessible in the view
templates.

If the first item in C<$self-Eargs> can be Cd by the model
class, it will be removed from C and the retrieved object will be added to
the C list. See L for more information.


=item object

Alias to get/set the first/only model object. The object will be accessible
in the view templates.

When used to set the object, will overwrite the request objects
with a single object.

=cut

sub object {
  my ($r,$object) = @_;
  $r->objects([$object]) if ($object);
  return undef unless $r->objects();
  return $r->objects->[0];
}

=item template_args

    $self->template_args->{foo} = 'bar';

Get/set a hash of template variables.

Maypole reserved words for template variables will over-ride values in template_variables.

Reserved words are : r, request, object, objects, base, config and errors, as well as the
current class or object name.

=item stash

A place to put custom application data. Not used by Maypole itself.

=item template

Get/set the template to be used by the view. By default, it returns
C<$self-Eaction>


=item error

Get/set a request error

=item output

Get/set the response output. This is usually populated by the view class. You
can skip view processing by setting the C.

=item table

The table part of the Maypole request path

=item action

The action part of the Maypole request path

=item args

A list of remaining parts of the request path after table and action
have been
removed

=item headers_in

A L object containing HTTP headers for the request

=item headers_out

A L object that contains HTTP headers for the output

=item document_encoding

Get/set the output encoding. Default: utf-8.

=item content_type

Get/set the output content type. Default: text/html

=item get_protocol

Returns the protocol the request was made with, i.e. https

=cut

sub get_protocol {
  die "get_protocol is a virtual method. Do not use Maypole directly; use Apache::MVC or similar";
}

=back

=head2 Request parameters

The source of the parameters may vary depending on the Maypole backend, but they
are usually populated from request query string and POST data.

Maypole supplies several approaches for accessing the request parameters. Note
that the current implementation (via a hashref) of C and C is
likely to change in a future version of Maypole. So avoid direct access to these
hashrefs:

    $r->{params}->{foo}      # bad
    $r->params->{foo}        # better

    $r->{query}->{foo}       # bad
    $r->query->{foo}         # better

    $r->param('foo')         # best

=over 4

=item param

An accessor (get or set) for request parameters. It behaves similarly to
CGI::param() for accessing CGI parameters, i.e.

    $r->param                   # returns list of keys
    $r->param($key)             # returns value for $key
    $r->param($key => $value)   # returns old value, sets to new value

=cut

sub param
{
    my ($self, $key) = (shift, shift);

    return keys %{$self->params} unless defined $key;

    return unless exists $self->params->{$key};

    my $val = $self->params->{$key};

    if (@_)
    {
        my $new_val = shift;
	$self->params->{$key} = $new_val;
    }

    return (ref $val eq 'ARRAY') ? @$val : ($val) if wantarray;

    return (ref $val eq 'ARRAY') ? $val->[0] : $val;
}


=item params

Returns a hashref of request parameters.

B Where muliple values of a parameter were supplied, the C value
will be an array reference.

=item query

Alias for C.

=back

=head3 Utility methods

=over 4

=item redirect_request

Sets output headers to redirect based on the arguments provided

Accepts either a single argument of the full url to redirect to, or a hash of
named parameters :

$r->redirect_request('http://www.example.com/path');

or

$r->redirect_request(protocol=>'https', domain=>'www.example.com', path=>'/path/file?arguments', status=>'302', url=>'..');

The named parameters are protocol, domain, path, status and url

Only 1 named parameter is required but other than url, they can be combined as
required and current values (from the request) will be used in place of any
missing arguments. The url argument must be a full url including protocol and
can only be combined with status.

=cut

sub redirect_request {
  die "redirect_request is a virtual method. Do not use Maypole directly; use Apache::MVC or similar";
}

# =item redirect_internal_request
#
# =cut
#
# sub redirect_internal_request {
#
# }


=item make_random_id

returns a unique id for this request can be used to prevent or detect repeat
submissions.

=cut

# Session and Repeat Submission Handling
sub make_random_id {
    use Maypole::Session;
    return Maypole::Session::generate_unique_id();
}

=back

=head1 SEQUENCE DIAGRAMS

See L for a detailed discussion of the sequence of
calls during processing of a request. This is a brief summary:

    INITIALIZATION
                               Model e.g.
         BeerDB           Maypole::Model::CDBI
           |                        |
   setup   |                        |
 o-------->||                       |
           || setup_model           |     setup_database() creates
           ||------+                |      a subclass of the Model
           |||<----+                |        for each table
           |||                      |                |
           |||   setup_database     |                |
           |||--------------------->|| 'create'      *
           |||                      ||----------> $subclass
           |||                      |                  |
           ||| load_model_subclass  |                  |
 foreach   |||------+  ($subclass)  |                  |
 $subclass ||||<----+               |    require       |
           ||||--------------------------------------->|
           |||                      |                  |
           |||   adopt($subclass)   |                  |
           |||--------------------->||                 |
           |                        |                  |
           |                        |                  |
           |-----+ init             |                  |
           ||<---+                  |                  |
           ||                       |     new          |     view_object: e.g.
           ||---------------------------------------------> Maypole::View::TT
           |                        |                  |          |
           |                        |                  |          |
           |                        |                  |          |
           |                        |                  |          |
           |                        |                  |          |



    HANDLING A REQUEST


          BeerDB                                Model  $subclass  view_object
            |                                      |       |         |
    handler |                                      |       |         |
  o-------->| new                                  |       |         |
            |-----> r:BeerDB                       |       |         |
            |         |                            |       |         |
            |         |                            |       |         |
            |         ||                           |       |         |
            |         ||-----+ parse_location      |       |         |
            |         |||<---+                     |       |         |
            |         ||                           |       |         |
            |         ||-----+ start_request_hook  |       |         |
            |         |||<---+                     |       |         |
            |         ||                           |       |         |
            |         ||-----+ get_session         |       |         |
            |         |||<---+                     |       |         |
            |         ||                           |       |         |
            |         ||-----+ get_user            |       |         |
            |         |||<---+                     |       |         |
            |         ||                           |       |         |
            |         ||-----+ handler_guts        |       |         |
            |         |||<---+                     |       |         |
            |         |||     class_of($table)     |       |         |
            |         |||------------------------->||      |         |
            |         |||       $subclass          ||      |         |
            |         |||<-------------------------||      |         |
            |         |||                          |       |         |
            |         |||-----+ is_model_applicable|       |         |
            |         ||||<---+                    |       |         |
            |         |||                          |       |         |
            |         |||-----+ call_authenticate  |       |         |
            |         ||||<---+                    |       |         |
            |         |||                          |       |         |
            |         |||-----+ additional_data    |       |         |
            |         ||||<---+                    |       |         |
            |         |||             process      |       |         |
            |         |||--------------------------------->||  fetch_objects
            |         |||                          |       ||-----+  |
            |         |||                          |       |||<---+  |
            |         |||                          |       ||        |
            |         |||                          |       ||   $action
            |         |||                          |       ||-----+  |
            |         |||                          |       |||<---+  |
            |         |||         process          |       |         |
            |         |||------------------------------------------->|| template
            |         |||                          |       |         ||-----+
            |         |||                          |       |         |||<---+
            |         |||                          |       |         |
            |         ||     send_output           |       |         |
            |         ||-----+                     |       |         |
            |         |||<---+                     |       |         |
   $status  |         ||                           |       |         |
   <------------------||                           |       |         |
            |         |                            |       |         |
            |         X                            |       |         |
            |                                      |       |         |
            |                                      |       |         |
            |                                      |       |         |



=head1 SEE ALSO

There's more documentation, examples, and information on our mailing lists
at the Maypole web site:

L

L, L, L.

=head1 AUTHOR

Maypole is currently maintained by Aaron Trevena.

=head1 AUTHOR EMERITUS

Simon Cozens, C

Simon Flack maintained Maypole from 2.05 to 2.09

Sebastian Riedel, C maintained Maypole from 1.99_01 to 2.04

=head1 THANKS TO

Sebastian Riedel, Danijel Milicevic, Dave Slack, Jesse Sheidlower, Jody Belka,
Marcus Ramberg, Mickael Joanne, Randal Schwartz, Simon Flack, Steve Simms,
Veljko Vidovic and all the others who've helped.

=head1 LICENSE

You may distribute this code under the same terms as Perl itself.

=cut

1;

__END__