For information about current developments and future releases, see:
http://maypole.perl.org/?TheRoadmap
-2.05 XXX
+2.05 Fri Dec 24 03:20:00 2004
- Revised and updated documentation. Many thanks to Dave Howorth for his
hard work and 120kb documentation patches.
- Added support for request and response HTTP headers with
+# http://module-build.sourceforge.net/META-spec.html
+#XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
name: Maypole
-version: 2.0
+version: 2.05
version_from: lib/Maypole.pm
installdirs: site
requires:
Class::DBI::Pager: 0
Class::DBI::Plugin::RetrieveAll: 0
Class::DBI::SQLite: 0
+ HTTP::Headers: 1.59
Template: 0
Template::Plugin::Class: 0
+ Test::MockModule: 0
UNIVERSAL::moniker: 0
UNIVERSAL::require: 0
URI::QueryParam: 0
NAME
Maypole - MVC web application framework
-SYNOPSIS
- See Maypole::Application.
-
DESCRIPTION
- This documents the Maypole request object. For user documentation, see
- Maypole::Manual.
-
- CLASS METHODS
- config
- Returns the Maypole::Config object
-
- setup
- My::App->setup($data_source, $user, $password, \%attr);
-
- Initialise the maypole application and model classes. Your application
- should call this after setting configuration via "config"
-
- init
- You should not call this directly, but you may wish to override this to
- add application-specific initialisation.
-
- view_object
- Get/set the Maypole::View object
-
- debug
- sub My::App::debug {1}
-
- Returns the debugging flag. Override this in your application class to
- enable/disable debugging.
-
- INSTANCE METHODS
- parse_location
- Turns the backend request (e.g. Apache::MVC, Maypole, CGI) into a
- Maypole request. It does this by setting the "path", and invoking
- "parse_path" and "parse_args".
-
- You should only need to define this method if you are writing a new
- Maypole backend.
-
- path
- Returns the request path
-
- parse_path
- Parses the request path and sets the "args", "action" and "table"
- properties
-
- table
- The table part of the Maypole request path
-
- action
- The action part of the Maypole request path
-
- args
- A list of remaining parts of the request path after table and action
- have been removed
-
- parse_args
- Turns post data and query string paramaters into a hash of "params".
-
- You should only need to define this method if you are writing a new
- Maypole backend.
-
- params
- Returns a hash of 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.
-
- Note: Where muliple values of a parameter were supplied, the "params"
- value will be an array reference.
-
- get_template_root
- Implimentation-specific path to template root.
-
- You should only need to define this method if you are writing a new
- Maypole backend. Otherwise, see "template_root" in Maypole::Config
+ Maypole is a Perl framework for MVC-oriented web applications, similar
+ to Jakarta's Struts. Maypole is designed to minimize coding requirements
+ for creating simple web interfaces to databases, while remaining flexible
+ enough to support enterprise web applications.
- 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.
+QUICK START
+ Maypole ships with a basic demo application, the Beer Database.
+ Please see the Maypole manual. You can access the manual by executing the
+ following command after installing Maypole:
- is_applicable
- Returns a Maypole::Constant to indicate whether the request is valid.
+ perldoc Maypole::Manual
- The default implimentation checks that "$r->table" is publicly
- accessible and that the model class is configured to handle the
- "$r->action"
+ Or try the following URL:
- authenticate
- Returns a Maypole::Constant to indicate whether the user is
- authenticated for the Maypole request.
+ http://search.cpan.org/perldoc?Maypole::Manual
- The default implimentation returns "OK"
+SUPPORT
+ Maypole is supported by a community of users on the Maypole mailing lists.
- model_class
- Returns the perl package name that will serve as the model for the
- request. It corresponds to the request "table" attribute.
+ Join the mailing list at http://lists.netthink.co.uk/listinfo/maypole
- 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
- "template_args".
-
- objects
- Get/set a list of model objects. The objects will be accessible in the
- view templates.
-
- If the first item in "$r->args" can be "retrieve()"d by the model class,
- it will be removed from "args" and the retrieved object will be added to
- the "objects" list. See Maypole::Model for more information.
-
- template_args
- $r->template_args->{foo} = 'bar';
-
- Get/set a hash of template variables.
-
- template
- Get/set the template to be used by the view. By default, it returns
- "$r->action"
-
- 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.
-
- error
- Get/set a request error
-
- output
- Get/set the response output. This is usually populated by the view
- class. You can skip view processing by setting the "output".
-
- document_encoding
- Get/set the output encoding. Default: utf-8.
-
- content_type
- Get/set the output content type. Default: text/html
-
- send_output
- Sends the output and additional headers to the user.
-
- 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.
-
- 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.
-
- handler
- This method sets up the class if it's not done yet, sets some defaults
- and leaves the dirty work to handler_guts.
-
- handler_guts
- This is the core of maypole. You don't want to know.
-
-SEE ALSO
- There's more documentation, examples, and a wiki at the Maypole web
- site:
-
- http://maypole.perl.org/
-
- Maypole::Application,Apache::MVC, CGI::Maypole.
+LINKS
+ http://maypole.perl.org - Maypole's home. tips & tricks, mailing list
AUTHOR
- Sebastian Riedel, c<sri@oook.de>
+ Maypole is currently maintained by Simon Flack, C<simonflk#cpan.org>
AUTHOR EMERITUS
- Simon Cozens, "simon@cpan.org"
-
-THANKS TO
- Danijel Milicevic, Dave Slack, Jesse Sheidlower, Jody Belka, Marcus
- Ramberg, Mickael Joanne, Simon Flack, Veljko Vidovic and all the others
- who've helped.
+ Simon Cozens, C<simon#cpan.org>
LICENSE
You may distribute this code under the same terms as Perl itself.
+++ /dev/null
---- The Future
-* Tests
-* Better documentation and more complex examples
-* Much more warnings
-* Multiple Models
-* clean logging
=head1 DESCRIPTION
-Maypole is a Perl web application framework to Java's struts. It is
-essentially completely abstracted, and so doesn't know anything about
-how to talk to the outside world. C<Apache::MVC> is a mod_perl based
-subclass of Maypole.
-
-To use it, you need to create a package which represents your entire
-application. In our example above, this is the C<BeerDB> package.
-
-This needs to first inherit from C<Apache::MVC>, and then call setup.
-This will give your package an Apache-compatible C<handler> subroutine,
-and then pass any parameters onto the C<setup_database> method of the
-model class. The default model class for Maypole uses L<Class::DBI> to
-map a database to classes, but this can be changed by messing with the
-configuration. (B<Before> calling setup.)
-
-Next, you should configure your application through the C<config>
-method. Configuration parameters at present are:
-
-=over
-
-=item uri_base
-
-You B<must> specify this; it is the base URI of the application, which
-will be used to construct links.
-
-=item display_tables
-
-If you do not want all of the tables in the database to be accessible,
-then set this to a list of only the ones you want to display
-
-=item rows_per_page
-
-List output is paged if you set this to a positive number of rows.
-
-=back
-
-You should also set up relationships between your classes, such that,
-for instance, calling C<brewery> on a C<BeerDB::Beer> object returns an
-object representing its associated brewery.
-
-For a full example, see the included "beer database" application.
+A mod_perl platform driver for Maypole. Your application can inherit from
+Apache::MVC directly, but it is recommended that you use
+L<Maypole::Application>.
=head1 INSTALLATION
=head1 LICENSE
You may distribute this code under the same terms as Perl itself.
+
+=cut
=head1 DESCRIPTION
-This is a handler for Maypole which will use the CGI instead of Apache's
-C<mod_perl> 1.x. This handler can also be used for Apache 2.0.
+This is a CGI platform driver for Maypole. Your application can inherit from
+CGI::Maypole directly, but it is recommended that you use
+L<Maypole::Application>.
+
=head1 METHODS
=head1 Implementation
-This class overrides a set of methods in the base Maypole class to provide it's
+This class overrides a set of methods in the base Maypole class to provide it's
functionality. See L<Maypole> for these:
=over
Dave Ranney C<dave@sialia.com>
Simon Cozens C<simon@cpan.org>
+
+=cut
# See Maypole::Workflow before trying to understand this.
my ( $class, $req ) = @_;
$class->init unless $class->init_done;
- my $r = bless { template_args => {}, config => $class->config }, $class;
+
+ # Create the request object
+ my $r = bless {
+ template_args => {},
+ config => $class->config
+ }, $class;
$r->headers_out(Maypole::Headers->new);
$r->get_request($req);
$r->parse_location();
$self->{args} = \@pi;
}
+sub param { # like CGI::param(), but read-only
+ my $r = shift;
+ my ($key) = @_;
+ if (defined $key) {
+ unless (exists $r->{params}{$key}) {
+ return wantarray() ? () : undef;
+ }
+ my $val = $r->{params}{$key};
+ if (wantarray()) {
+ return ref $val ? @$val : $val;
+ } else {
+ return ref $val ? $val->[0] : $val;
+ }
+ } else {
+ return keys %{$r->{params}};
+ }
+}
+
sub get_template_root { "." }
sub get_request { }
=head1 DESCRIPTION
-This documents the Maypole request object. For user documentation, see
-L<Maypole::Manual>.
+This documents the Maypole request object. See the L<Maypole::Manual>, for a
+detailed guide to using Maypole.
+
+Maypole is a Perl web application framework 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 package which represents your entire
+application. In our example above, this is the C<BeerDB> package.
+
+This needs to first use L<Maypole::Application> which will make your package
+inherit from the appropriate platform driver such as C<Apache::MVC> or
+C<CGI::Maypole>, and then call setup. This sets up the model classes and
+configures your application. The default model class for Maypole uses
+L<Class::DBI> to map a database to classes, but this can be changed by altering
+configuration. (B<Before> calling setup.)
=head2 CLASS METHODS
=head3 get_template_root
-Implimentation-specific path to template root.
+Implementation-specific path to template root.
You should only need to define this method if you are writing a new
Maypole
Returns a Maypole::Constant to indicate whether the request is valid.
-The default implimentation checks that C<$r-E<gt>table> is publicly
+The default implementation checks that C<$r-E<gt>table> is publicly
accessible
and that the model class is configured to handle the C<$r-E<gt>action>
authenticated for
the Maypole request.
-The default implimentation returns C<OK>
+The default implementation returns C<OK>
=head3 model_class
=head3 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 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
=head1 SEE ALSO
-There's more documentation, examples, and a wiki at the Maypole web
-site:
+There's more documentation, examples, and a information on our mailing lists
+at the Maypole web site:
-http://maypole.perl.org/
+L<http://maypole.perl.org/>
-L<Maypole::Application>,L<Apache::MVC>, L<CGI::Maypole>.
+L<Maypole::Application>,
L<Apache::MVC>, L<CGI::Maypole>.
=head1 AUTHOR
-Sebastian Riedel, c<sri@oook.de>
+Maypole is currently maintained by Simon Flack C<simonflk#cpan.org>
=head1 AUTHOR EMERITUS
-Simon Cozens, C<simon@cpan.org>
+Simon Cozens, C<simon#cpan.org>
=head1 THANKS TO
=head1 NAME
-Maypole::Application - Maypole Universal Frontend
+Maypole::Application - Universal Maypole Frontend
=head1 SYNOPSIS
use Maypole::Application;
MyApp->setup;
+Note that no options are passed to C<setup()>. You must ensure that the
+required model config parameters are set in C<MyApp-E<gt>config>. See
+L<Maypole::Config> for more information.
+
=head2 -Debug
use Maypole::Application qw(-Debug);
=head1 LICENSE
You may distribute this code under the same terms as Perl itself.
+
+=cut
sub call_url {
my $self = shift;
- @ARGV = @_;
+ local @ARGV = @_;
$package->handler() == OK and return $buffer;
}
This should be a string containing your application's name.
+Optional. Is used in the factory templates.
+
=head3 rows_per_page
This is the number of rows your application should display per page.
+Optional.
+
=head3 tables
Contains a list of all tables, if supported by model.
=head3 uri_base
-This is the URI base that should be prepended to your application when
-Maypole
+This is the URI base that should be prepended to your application when Maypole
makes URLs.
=head3 view
Maypole::Constants - Maypole predefined constants
+=head1 SYNOPSIS
+
+ use Maypole::Constants;
+
+ sub authenticate {
+ if (valid_user()) {
+ return OK;
+ } else {
+ return DECLINED
+ }
+ }
+
=head1 DESCRIPTION
This class defines constants for use with Maypole
+=head1 CONSTANTS
+
+=head3 OK
+
+=head3 DECLINED
+
+=head3 ERROR
+
=head1 SEE ALSO
L<Maypole>
A convenience wrapper around C<HTTP::Headers>. Additional methods are provided
to make the mutators less repetitive and wordy. For example:
- $r->headers->header(Content_Base => $r->config->uri_base);
+ $r->headers_out->header(Content_Base => $r->config->uri_base);
can be written as:
- $r->headers->set(Content_Base => $r->config->uri_base);
+ $r->headers_out->set(Content_Base => $r->config->uri_base);
=head1 METHODS
L<HTTP::Headers>
-=head1 AUTHORS
+=head1 AUTHOR
Simon Flack
* indicates incomplete chapters.
+=head1 SEE ALSO
+
+L<http://maypole.perl.org>
=head1 AUTHOR
L<Contents|Maypole::Manual>,
Next L<The Request Cookbook|Maypole::Manual::Request>,
-Previous L<Maypole|Maypole::Manual::Workflow>
+Previous L<Maypole's Request Workflow|Maypole::Manual::Workflow>
"That user already seems to exist on Flox. ".
"Is this the one you meant?";
- $self->redirect_to_user($r,$user);
+ $self->redirect_to_user($r, $user);
}
Where C<redirect_to_user> looks like this:
=head1 DESCRIPTION
This is the base class for Maypole data models. This is an abstract class
-meant to define the interface, and can't be used directly.
+that defines the interface, and can't be used directly.
=head2 process
-This is the engine of this module. It populates all the relevant variables
-and calls the requested action.
+This is the engine of this module. Given the request object, it populates
+all the relevant variables and calls the requested action.
Anyone subclassing this for a different database abstraction mechanism
needs to provide the following methods:
Uses the user-defined data in C<@data> to specify a database- for
example, by passing in a DSN. The model class should open the database,
and create a class for each table in the database. These classes will
-then be C<adopt>ed. It should also populate C<< $config->{tables} >> and
-C<< $config->{classes} >> with the names of the classes and tables
+then be C<adopt>ed. It should also populate C<< $config->tables >> and
+C<< $config->classes >> with the names of the classes and tables
respectively. The classes should be placed under the specified
namespace. For instance, C<beer> should be mapped to the class
C<BeerDB::Beer>.
=head2 fetch_objects
-This method should populate $r->objects from $r->{args}.
+This class method is passed a request object and is expected to return an
+object of the appropriate table class from information stored in the request
+object.
=head2 adopt
-This is called on an model class representing a table and allows the
-master model class to do any set-up required.
+This class method is passed the name of a model class that represensts a table
+and allows the master model class to do any set-up required.
=head2 columns
sub setup_database { die "This is an abstract method" }
sub fetch_objects { die "This is an abstract method" }
-=head2 Commands
+=head2 Actions
=over
=item list
-The C<list> method should fill C<< $r-> objects >> with all of the
+The C<list> method should fill C<$r-E<gt>objects> with all of the
objects in the class. You may want to page this using C<Data::Page> or
similar.
=item edit
-Empty Action
+Empty Action.
=item view
=head2 display_columns
-Returns a list of columns to display in the model. by default returns
+Returns a list of columns to display in the model. By default returns
all columns in alphabetical order. Override this in base classes to
change ordering, or elect not to show columns.
=head2 is_public
should return true if a certain action is supported, or false otherwise.
-Defaults to checking if the sub has the :Exported attribute.
+Defaults to checking if the sub has the C<:Exported> attribute.
=cut
}
1;
+
+
=head1 DESCRIPTION
-This is a master model class which uses C<Class::DBI> to do all the hard
+This is a master model class which uses L<Class::DBI> to do all the hard
work of fetching rows and representing them as objects. It is a good
model to copy if you're replacing it with other database abstraction
modules.
=back
-=head1 Additional Commands
+=head1 Additional Actions
=over
=item delete
-Surprisingly, this command causes a database record to be forever lost.
+Unsuprisingly, this command causes a database record to be forever lost.
=item search
}
sub fetch_objects {
- my ($class,$r)=@_;
+ my ($class, $r)=@_;
my @pcs = $class->primary_columns;
if ( $#pcs ) {
my %pks;
use Foo::SomeTable;
use Foo::Other::Table;
- Foo->config->{model_class} = "Maypole::Model::CDBI::Plain";
+ Foo->config->model("Maypole::Model::CDBI::Plain");
Foo->setup([qw/ Foo::SomeTable Foo::Other::Table /]);
=head1 DESCRIPTION
This module allows you to use Maypole with previously set-up
-C<Class::DBI> classes; simply call C<setup> with a list reference
+L<Class::DBI> classes; simply call C<setup> with a list reference
of the classes you're going to use, and Maypole will work out the
tables and set up the inheritance relationships as normal.
=head1 NAME
-Maypole::View::Base - Base cl
+Maypole::View::Base - Base class for view classes
=head1 DESCRIPTION
This is the base class for Maypole view classes. This is an abstract class
-meant to define the interface, and can't be used directly.
+that defines the interface, and can't be used directly.
=head2 process
-This is the engine of this module. It populates all the relevant variables
-and calls the requested action.
+This is the entry point for the view. It templates the request and returns a
+C<Maypole::Constant> indicate success or failure for the view phase.
-Anyone subclassing this for a different database abstraction mechanism
-needs to provide the following methods:
+Anyone subclassing this for a different rendering mechanism needs to provide
+the following methods:
-=head2 template
+=head2 template
-In this method you do the actual processing of your template. it should use L<paths>
-to search for components, and provide the templates with easy access to the contents
-of L<vars>. It should put the result in $r->{output} and return OK if processing was
-sucessfull, or populate $r->{error} and return ERROR if it fails.
+In this method you do the actual processing of your template. it should use
+L<paths> to search for components, and provide the templates with easy access
+to the contents of L<vars>. It should put the result in C<$r-E<gt>output> and
+return C<OK> if processing was sucessfull, or populate C<$r-E<gt>error> and
+return C<ERROR> if it fails.
=head1 Other overrides
=head2 paths
-Returns search paths for templates. the default method returns factory, custom and
-<tablename> under the configured template root.
+Returns search paths for templates. the default method returns factory, custom
+and E<lt>tablenameE<gt> under the configured template root.
=head2 vars
-returns a hash of data the template should have access to. The default one populates
-classmetadata if there is a class, as well as setting the data objects by name if
-there is one or more objects available.
+returns a hash of data the template should have access to. The default one
+populates classmetadata if there is a table class, as well as setting the data
+objects by name if there is one or more objects available.
=head2 error
This is the default view class for Maypole; it uses the Template Toolkit to
fill in templates with the objects produced by Maypole's model classes. Please
-see the Maypole manual, and in particular, the L<view|Maypole::Manual::View>
-chapter for the template variables available and for a refresher on how
-template components are resolved.
+see the L<Maypole manual|Maypole::Manual>, and in particular, the
+L<view|Maypole::Manual::View> chapter for the template variables available and
+for a refresher on how template components are resolved.
The underlying Template toolkit object is configured through
C<$r-E<gt>config-E<gt>view_options>. See L<Template|Template> for available
projects / maypole.git / commitdiff