POD updates: fleshed out some weak areas, reorganised a little and fixed some typogra...

git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@325 48953598-375a-da11-a14b-00016c27c3ee

diff --git a/Changes b/Changes
index d7b75285cbe39ef334fd24258fc0076cf89d86c4..21a9053ddb25a491452d797976495b0efaba3463 100644 (file)
--- a/Changes
+++ b/Changes
@@ -2,7 +2,7 @@ This file documents the revision history for Perl extension Maypole.
 For information about current developments and future releases, see:
     http://maypole.perl.org/?TheRoadmap
 
 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
     - 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

diff --git a/META.yml b/META.yml
index 5e08b6fa96410fe4d33678403cccfe7f8c0d07e0..3d80d753a4ab00a0bfeaaddbddd15f99aac21365 100644 (file)
--- a/META.yml
+++ b/META.yml
@@ -1,5 +1,7 @@
+# http://module-build.sourceforge.net/META-spec.html
+#XXXXXXX This is a prototype!!!  It will change in the future!!! XXXXX#

 name:         Maypole
 name:         Maypole

-version:      2.0
+version:      2.05

 version_from: lib/Maypole.pm
 installdirs:  site
 requires:
 version_from: lib/Maypole.pm
 installdirs:  site
 requires:


@@ -14,8 +16,10 @@ requires:
     Class::DBI::Pager:             0
     Class::DBI::Plugin::RetrieveAll: 0
     Class::DBI::SQLite:            0
     Class::DBI::Pager:             0
     Class::DBI::Plugin::RetrieveAll: 0
     Class::DBI::SQLite:            0

+    HTTP::Headers:                 1.59

     Template:                      0
     Template::Plugin::Class:       0
     Template:                      0
     Template::Plugin::Class:       0

+    Test::MockModule:              0

     UNIVERSAL::moniker:            0
     UNIVERSAL::require:            0
     URI::QueryParam:               0
     UNIVERSAL::moniker:            0
     UNIVERSAL::require:            0
     URI::QueryParam:               0

diff --git a/README b/README
index 91906c4c62ee42d76c4ac030eb5f9e7a2420c278..76af4dab373812040a418967c30d35ac7d6340f1 100644 (file)
--- a/README
+++ b/README
@@ -1,187 +1,36 @@
 NAME
     Maypole - MVC web application framework
 
 NAME
     Maypole - MVC web application framework
 

-SYNOPSIS
-    See Maypole::Application.
-

 DESCRIPTION
 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
 
 AUTHOR

-    Sebastian Riedel, c<sri@oook.de>
+    Maypole is currently maintained by Simon Flack, C<simonflk#cpan.org>

 
 AUTHOR EMERITUS
 
 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.
 
 LICENSE
     You may distribute this code under the same terms as Perl itself.

diff --git a/TODO b/TODO
deleted file mode 100644 (file)
index e9c8f83..0000000
--- a/TODO
+++ /dev/null
@@ -1,6 +0,0 @@
---- The Future
-* Tests
-* Better documentation and more complex examples
-* Much more warnings
-* Multiple Models
-* clean logging

diff --git a/lib/Apache/MVC.pm b/lib/Apache/MVC.pm
index 0ee09fac0c01e31c5d80ecb1f5f6b20b49bc0949..4539c9dbdb5cf26593920f3be2466f0cfbe0d6e2 100644 (file)
--- a/lib/Apache/MVC.pm
+++ b/lib/Apache/MVC.pm
@@ -109,47 +109,9 @@ Apache::MVC - Apache front-end to Maypole
 
 =head1 DESCRIPTION
 
 
 =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 INSTALLATION
 


@@ -205,3 +167,5 @@ Screwed up by Sebastian Riedel, C<sri@oook.de>
 =head1 LICENSE
 
 You may distribute this code under the same terms as Perl itself.
 =head1 LICENSE
 
 You may distribute this code under the same terms as Perl itself.

+
+=cut

diff --git a/lib/CGI/Maypole.pm b/lib/CGI/Maypole.pm
index 99cf27f92b2a1b295fe9872057db093523430bb2..7b19023fbff86417ed528f867fd1b138cc95ea43 100644 (file)
--- a/lib/CGI/Maypole.pm
+++ b/lib/CGI/Maypole.pm
@@ -103,8 +103,10 @@ http://your.site/cgi-bin/beer.cgi/frontpage
 
 =head1 DESCRIPTION
 
 
 =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 METHODS
 


@@ -118,7 +120,7 @@ Call this from your CGI script to start the Maypole application.
 
 =head1 Implementation
 
 
 =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
 functionality. See L<Maypole> for these:
 
 =over


@@ -140,3 +142,5 @@ functionality. See L<Maypole> for these:
 Dave Ranney C<dave@sialia.com>
 
 Simon Cozens C<simon@cpan.org>
 Dave Ranney C<dave@sialia.com>
 
 Simon Cozens C<simon@cpan.org>

+
+=cut

diff --git a/lib/Maypole.pm b/lib/Maypole.pm
index b14720dd7cd262b96b327255881fc7ea51dcfe3d..e71c31f27f155b3fe9f3a41d178345fae071d069 100644 (file)
--- a/lib/Maypole.pm
+++ b/lib/Maypole.pm
@@ -62,7 +62,12 @@ sub handler {
     # See Maypole::Workflow before trying to understand this.
     my ( $class, $req ) = @_;
     $class->init unless $class->init_done;
     # 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();
     $r->headers_out(Maypole::Headers->new);
     $r->get_request($req);
     $r->parse_location();


@@ -189,6 +194,24 @@ sub parse_path {
     $self->{args}   = \@pi;
 }
 
     $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       { }
 
 sub get_template_root { "." }
 sub get_request       { }
 


@@ -210,8 +233,22 @@ See L<Maypole::Application>.
 
 =head1 DESCRIPTION
 
 
 =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
 
 
 =head2 CLASS METHODS
 


@@ -311,7 +348,7 @@ will be an array reference.
 
 =head3 get_template_root
 
 
 =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
 
 You should only need to define this method if you are writing a new
 Maypole


@@ -328,7 +365,7 @@ or CGI request object, it defaults to blank.
 
 Returns a Maypole::Constant to indicate whether the request is valid.
 
 
 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>
 
 accessible
 and that the model class is configured to handle the C<$r-E<gt>action>
 


@@ -338,7 +375,7 @@ Returns a Maypole::Constant to indicate whether the user is
 authenticated for
 the Maypole request.
 
 authenticated for
 the Maypole request.
 

-The default implimentation returns C<OK>
+The default implementation returns C<OK>

 
 =head3 model_class
 
 
 =head3 model_class
 


@@ -417,9 +454,9 @@ authenticate method of your Maypole application.
 
 =head3 call_exception
 
 
 =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
 
 This method first checks if the relevant model class
 can handle exceptions the user, or falls back to the default


@@ -437,20 +474,20 @@ This is the core of maypole. You don't want to know.
 
 =head1 SEE ALSO
 
 
 =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
 
 
 =head1 AUTHOR
 

-Sebastian Riedel, c<sri@oook.de>
+Maypole is currently maintained by Simon Flack C<simonflk#cpan.org>

 
 =head1 AUTHOR EMERITUS
 
 
 =head1 AUTHOR EMERITUS
 

-Simon Cozens, C<simon@cpan.org>
+Simon Cozens, C<simon#cpan.org>

 
 =head1 THANKS TO
 
 
 =head1 THANKS TO
 

diff --git a/lib/Maypole/Application.pm b/lib/Maypole/Application.pm
index c10221a8784bbf36be6cae136b523cd1f81ec23f..d7af65d4b06c7ec0587159a978e1acbd509ceeed 100644 (file)
--- a/lib/Maypole/Application.pm
+++ b/lib/Maypole/Application.pm
@@ -50,7 +50,7 @@ else {
 
 =head1 NAME
 
 
 =head1 NAME
 

-Maypole::Application - Maypole Universal Frontend
+Maypole::Application - Universal Maypole Frontend

 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 


@@ -87,6 +87,10 @@ is equivalent to
     use Maypole::Application;
     MyApp->setup;
 
     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);
 =head2 -Debug
 
     use Maypole::Application qw(-Debug);


@@ -104,3 +108,5 @@ Idea by Marcus Ramberg, C<marcus@thefeed.no>
 =head1 LICENSE
 
 You may distribute this code under the same terms as Perl itself.
 =head1 LICENSE
 
 You may distribute this code under the same terms as Perl itself.

+
+=cut

diff --git a/lib/Maypole/CLI.pm b/lib/Maypole/CLI.pm
index 3839521e2d8112e03bb8eb9971551a28f691843c..de8fab65118cfe04c3f51b2cb7e9831a2f2af362 100644 (file)
--- a/lib/Maypole/CLI.pm
+++ b/lib/Maypole/CLI.pm
@@ -47,7 +47,7 @@ sub send_output { $buffer = shift->{output} }
 
 sub call_url {
     my $self = shift;
 
 sub call_url {
     my $self = shift;

-    @ARGV = @_;
+    local @ARGV = @_;

     $package->handler() == OK and return $buffer;
 }
 
     $package->handler() == OK and return $buffer;
 }
 

diff --git a/lib/Maypole/Config.pm b/lib/Maypole/Config.pm
index 024b78cf727899949d05dc1d5f7ee8beede96bd9..cc9a9f59250b9a9faa74f4689b3629e7991c3b65 100644 (file)
--- a/lib/Maypole/Config.pm
+++ b/lib/Maypole/Config.pm
@@ -34,10 +34,14 @@ This class stores all configuration data for your Maypole application.
 
 This should be a string containing your application's name.
 
 
 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.
 
 =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 tables
 
 Contains a list of all tables, if supported by model.


@@ -48,8 +52,7 @@ This is where your application can find its templates.
 
 =head3 uri_base
 
 
 =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
 makes URLs.
 
 =head3 view

diff --git a/lib/Maypole/Constants.pm b/lib/Maypole/Constants.pm
index 69178502bbdccf7a824d103805a2cb3c0aee7275..7e0b8ea3fad6789717b21cc7da77394c09d6c3b4 100644 (file)
--- a/lib/Maypole/Constants.pm
+++ b/lib/Maypole/Constants.pm
@@ -10,10 +10,30 @@ our $VERSION = "1." . sprintf "%04d", q$Rev$ =~ /: (\d+)/;
 
 Maypole::Constants - Maypole predefined constants
 
 
 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 DESCRIPTION
 
 This class defines constants for use with Maypole
 

+=head1 CONSTANTS
+
+=head3 OK
+
+=head3 DECLINED
+
+=head3 ERROR
+

 =head1 SEE ALSO
 
 L<Maypole>
 =head1 SEE ALSO
 
 L<Maypole>

diff --git a/lib/Maypole/Headers.pm b/lib/Maypole/Headers.pm
index 16646faad9fcd88d58c897b0eb5eb40381b90cd3..33edc1bbedb70dd90fc1be22c8ebf5992080a0b3 100644 (file)
--- a/lib/Maypole/Headers.pm
+++ b/lib/Maypole/Headers.pm
@@ -54,11 +54,11 @@ Maypole::Headers - Convenience wrapper around HTTP::Headers
 A convenience wrapper around C<HTTP::Headers>. Additional methods are provided
 to make the mutators less repetitive and wordy. For example:
 
 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:
 
 
 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
 
 
 =head1 METHODS
 


@@ -109,7 +109,7 @@ An alias to C<HTTP::Headers-E<gt>header_field_names>
 
 L<HTTP::Headers>
 
 
 L<HTTP::Headers>
 

-=head1 AUTHORS
+=head1 AUTHOR

 
 Simon Flack
 
 
 Simon Flack
 

diff --git a/lib/Maypole/Manual.pod b/lib/Maypole/Manual.pod
index c8998547d8fb81d4a27218ecb8185e8683a97311..9c5dd0c97077d7b937eb14faa4e70cb2988b9b4b 100644 (file)
--- a/lib/Maypole/Manual.pod
+++ b/lib/Maypole/Manual.pod
@@ -105,6 +105,9 @@ better as a Maypole application.
 
   * indicates incomplete chapters.
 
 
   * indicates incomplete chapters.
 

+=head1 SEE ALSO
+
+L<http://maypole.perl.org>

 
 =head1 AUTHOR
 
 
 =head1 AUTHOR
 

diff --git a/lib/Maypole/Manual/Beer.pod b/lib/Maypole/Manual/Beer.pod
index 39c8462d73c62df54e208576eee27ef42a6c182e..b6bd66975f4055c7e3dfa0d4dce1b578f9739ae7 100644 (file)
--- a/lib/Maypole/Manual/Beer.pod
+++ b/lib/Maypole/Manual/Beer.pod
@@ -253,5 +253,5 @@ Now when we view a beer, we'll have a list of the pubs that it's on at.
 
 L<Contents|Maypole::Manual>,
 Next L<The Request Cookbook|Maypole::Manual::Request>,
 
 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>

 
 

diff --git a/lib/Maypole/Manual/Flox.pod b/lib/Maypole/Manual/Flox.pod
index e2c47d2c8f0a38c721005fff42434645b3088d6b..3a1e92eca79dc61e63431b55a9d0805d7c1baecb 100644 (file)
--- a/lib/Maypole/Manual/Flox.pod
+++ b/lib/Maypole/Manual/Flox.pod
@@ -389,7 +389,7 @@ profile.
                     "That user already seems to exist on Flox. ".
                     "Is this the one you meant?";
 
                     "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:
             } 
 
 Where C<redirect_to_user> looks like this:

diff --git a/lib/Maypole/Model/Base.pm b/lib/Maypole/Model/Base.pm
index 580e6e1c942cb7cbfd3be63dae9f1cd4c6a74590..6fc70e6a4d6bc64377ce5c41627cf183b445103a 100644 (file)
--- a/lib/Maypole/Model/Base.pm
+++ b/lib/Maypole/Model/Base.pm
@@ -34,12 +34,12 @@ Maypole::Model::Base - Base class for model classes
 =head1 DESCRIPTION
 
 This is the base class for Maypole data models. This is an abstract class
 =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
 
 
 =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:
 
 Anyone subclassing this for a different database abstraction mechanism
 needs to provide the following methods:


@@ -51,8 +51,8 @@ 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
 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>.
 respectively. The classes should be placed under the specified
 namespace. For instance, C<beer> should be mapped to the class
 C<BeerDB::Beer>.


@@ -65,12 +65,14 @@ This maps between a table name and its associated class.
 
 =head2 fetch_objects
 
 
 =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
 
 
 =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
 
 
 =head2 columns
 


@@ -87,7 +89,7 @@ sub class_of       { die "This is an abstract method" }
 sub setup_database { die "This is an abstract method" }
 sub fetch_objects { die "This is an abstract method" }
 
 sub setup_database { die "This is an abstract method" }
 sub fetch_objects { die "This is an abstract method" }
 

-=head2 Commands
+=head2 Actions

 
 =over
 
 
 =over
 


@@ -105,13 +107,13 @@ sub do_edit { die "This is an abstract method" }
 
 =item list
 
 
 =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
 
 objects in the class. You may want to page this using C<Data::Page> or
 similar.
 
 =item edit
 

-Empty Action
+Empty Action.

 
 =item view
 
 
 =item view
 


@@ -143,7 +145,7 @@ following methods:
 
 =head2 display_columns
 
 
 =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.
 
 all columns in alphabetical order. Override this in base classes to
 change ordering, or elect not to show columns.
 


@@ -177,7 +179,7 @@ sub description { "A poorly defined class" }
 =head2 is_public
 
 should return true if a certain action is supported, or false otherwise. 
 =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
 
 
 =cut
 


@@ -205,3 +207,5 @@ sub related {
 }
 
 1;
 }
 
 1;

+
+

diff --git a/lib/Maypole/Model/CDBI.pm b/lib/Maypole/Model/CDBI.pm
index 37b133549ab316dfee9b246ab8124f2eea35e9d0..ac89318827f01c41b2b3f8d2702a2fa89204e14b 100644 (file)
--- a/lib/Maypole/Model/CDBI.pm
+++ b/lib/Maypole/Model/CDBI.pm
@@ -17,7 +17,7 @@ Maypole::Model::CDBI - Model class based on Class::DBI
 
 =head1 DESCRIPTION
 
 
 =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.
 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.


@@ -43,13 +43,13 @@ See L<Maypole::Model::Base> for these:
 
 =back 
 
 
 =back 
 

-=head1 Additional Commands
+=head1 Additional Actions

 
 =over 
 
 =item delete
 
 
 =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
 
 
 =item search
 


@@ -247,7 +247,7 @@ sub class_of {
 }
 
 sub fetch_objects {
 }
 
 sub fetch_objects {

-    my ($class,$r)=@_;
+    my ($class, $r)=@_;

     my @pcs = $class->primary_columns;
     if ( $#pcs ) {
     my %pks;
     my @pcs = $class->primary_columns;
     if ( $#pcs ) {
     my %pks;

diff --git a/lib/Maypole/Model/CDBI/Plain.pm b/lib/Maypole/Model/CDBI/Plain.pm
index e4f6cfc5dc419af8d99d6961c5469483cf2e860a..43a10b105a8c2da22f57198383dd6c6601131210 100644 (file)
--- a/lib/Maypole/Model/CDBI/Plain.pm
+++ b/lib/Maypole/Model/CDBI/Plain.pm
@@ -28,13 +28,13 @@ Maypole::Model::CDBI::Plain - Class::DBI model without ::Loader
     use Foo::SomeTable;
     use Foo::Other::Table;
 
     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
     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.
 
 of the classes you're going to use, and Maypole will work out the
 tables and set up the inheritance relationships as normal.
 

diff --git a/lib/Maypole/View/Base.pm b/lib/Maypole/View/Base.pm
index 6c6b63c5a8886dc47e85e0452e8ca79c1d5a44c2..f687309d5057f4e66e8b3e2608c17be904bc3417 100644 (file)
--- a/lib/Maypole/View/Base.pm
+++ b/lib/Maypole/View/Base.pm
@@ -117,27 +117,28 @@ sub template { die shift() . " didn't define a decent template method!" }
 
 =head1 NAME
 
 
 =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
 
 =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
 
 
 =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
 
 
 =head1 Other overrides
 


@@ -150,14 +151,14 @@ during view initialization.
 
 =head2 paths
 
 
 =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
 
 
 =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
 
 
 =head2 error
 

diff --git a/lib/Maypole/View/TT.pm b/lib/Maypole/View/TT.pm
index c79c027633f23ae55623b10eda75cd0c1dbb32ca..59c3f8fe888388b26dbf969e14fadd6288c43ec6 100644 (file)
--- a/lib/Maypole/View/TT.pm
+++ b/lib/Maypole/View/TT.pm
@@ -52,9 +52,9 @@ Maypole::View::TT - A Template Toolkit view class for Maypole
 
 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
 
 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
 
 The underlying Template toolkit object is configured through
 C<$r-E<gt>config-E<gt>view_options>. See L<Template|Template> for available