From 616082000cbe7305fbfc84d33bb2f9d53cc86f3c Mon Sep 17 00:00:00 2001 From: Sebastian Riedel Date: Sun, 26 Sep 2004 20:58:52 +0000 Subject: [PATCH] Moved doc/*.pod to lib/Maypole/Manual/ and added new Maypole.pm documentation git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@206 48953598-375a-da11-a14b-00016c27c3ee --- Changes | 14 +- doc/makedoc.pl | 21 -- lib/Maypole.pm | 283 +++++++++++------- {doc => lib/Maypole/Manual}/About.pod | 0 {doc => lib/Maypole/Manual}/Beer.pod | 0 {doc => lib/Maypole/Manual}/BuySpy.pod | 0 {doc => lib/Maypole/Manual}/Flox.pod | 0 {doc => lib/Maypole/Manual}/Model.pod | 0 {doc => lib/Maypole/Manual}/Overview.pod | 0 {doc => lib/Maypole/Manual}/Request.pod | 0 .../Maypole/Manual}/StandardTemplates.pod | 0 {doc => lib/Maypole/Manual}/View.pod | 0 12 files changed, 185 insertions(+), 133 deletions(-) delete mode 100644 doc/makedoc.pl rename {doc => lib/Maypole/Manual}/About.pod (100%) rename {doc => lib/Maypole/Manual}/Beer.pod (100%) rename {doc => lib/Maypole/Manual}/BuySpy.pod (100%) rename {doc => lib/Maypole/Manual}/Flox.pod (100%) rename {doc => lib/Maypole/Manual}/Model.pod (100%) rename {doc => lib/Maypole/Manual}/Overview.pod (100%) rename {doc => lib/Maypole/Manual}/Request.pod (100%) rename {doc => lib/Maypole/Manual}/StandardTemplates.pod (100%) rename {doc => lib/Maypole/Manual}/View.pod (100%) diff --git a/Changes b/Changes index 4575ddc..f017a09 100644 --- a/Changes +++ b/Changes @@ -1,7 +1,7 @@ Revision history for Perl extension Maypole 2.0 XXX XXX XX XX:XX:XX XXX XXXX - - Added parse_args() (Simon Flack) + - added parse_args() (Simon Flack) - call additional_data() and authenticate() for plain templates - merged Apache2::MVC (mod_perl2 support) into Apache::MVC - added Maypole::Application universal front-end @@ -9,14 +9,16 @@ Revision history for Perl extension Maypole - $r->{query} is now deprecated, use $r->{params} for GET and POST - fixed multiple value handling (Simon Flack) - added exception handling (Simon Flack) - - Fixed documentation bugs - - Changed default documentencoding to utf8. Change with + - fixed documentation bugs + - changed default documentencoding to utf8. Change with $r->config->{document_encoding} - - Removed Maypole::View::Mason as it's distributed separately on CPAN. - - Factory templates are now XHTML 1.1 compliant. + - removed Maypole::View::Mason as it's distributed separately on CPAN. + - factory templates are now XHTML 1.1 compliant. - made the config hash into -> Maypole::Config - accessors for everything - - Win32 support + - win32 support + - new documentation for Maypole.pm (Simon Flack) + - moved doc/*.pod to lib/Maypole/Manual 1.7 Sat Jul 17 20:15:26 BST 2004 - Emergency release - we lost the "use Maypole::Constants" from diff --git a/doc/makedoc.pl b/doc/makedoc.pl deleted file mode 100644 index b6dec2f..0000000 --- a/doc/makedoc.pl +++ /dev/null @@ -1,21 +0,0 @@ -my @templates = <../templates/factory/*>; - -my %doc; - -for my $template (@templates) { - open TEMP, $template or die $!; - $template =~ s/.*factory\///g; - while () { - next unless /^#?=for doc/... /^#?=cut/ - and not /(%#?\]|\[%#?)$/ - and not /=cut|=for doc/; # Much magic. - s/^\s*#//g; - $doc{$template} .= $_; - } -} - -while (<>) { - if (!/^=template (\w+)/) { print; next; } - die "Can't find doc for template $1" unless $doc{$1}; - print $doc{$1}; -} diff --git a/lib/Maypole.pm b/lib/Maypole.pm index dd9ff77..6ab5bc0 100644 --- a/lib/Maypole.pm +++ b/lib/Maypole.pm @@ -189,148 +189,218 @@ sub parse_path { $self->{args} = \@pi; } +sub get_template_root { "." } +sub get_request { } + +sub parse_location { + die "Do not use Maypole directly; use Apache::MVC or similar"; +} + +sub send_output { + die "Do not use Maypole directly; use Apache::MVC or similar"; +} + =head1 NAME Maypole - MVC web application framework =head1 SYNOPSIS -See L. +See L. =head1 DESCRIPTION -A large number of web programming tasks follow the same sort of pattern: -we have some data in a datasource, typically a relational database. We -have a bunch of templates provided by web designers. We have a number of -things we want to be able to do with the database - create, add, edit, -delete records, view records, run searches, and so on. We have a web -server which provides input from the user about what to do. Something in -the middle takes the input, grabs the relevant rows from the database, -performs the action, constructs a page, and spits it out. - -Maypole aims to be the most generic and extensible "something in the -middle" - an MVC-based web application framework. - -An example would help explain this best. You need to add a product -catalogue to a company's web site. Users need to list the products in -various categories, view a page on each product with its photo and -pricing information and so on, and there needs to be a back-end where -sales staff can add new lines, change prices, and delete out of date -records. So, you set up the database, provide some default templates -for the designers to customize, and then write an Apache handler like -this: - - package ProductDatabase; - use base 'Maypole::Application'; - __PACKAGE__->set_database("dbi:mysql:products"); - ProductDatabase->config->uri_base = "http://your.site/catalogue/"; - ProductDatabase::Product->has_a("category" => ProductDatabase::Category); - # ... - - sub authenticate { - my ($self, $request) = @_; - return OK if $request->{ar}->get_remote_host() eq "sales.yourcorp.com"; - return OK if $request->{action} =~ /^(view|list)$/; - return DECLINED; - } - 1; +This documents the Maypole request object. For user documentation, see +L. -You then put the following in your Apache config: +=head2 CLASS METHODS - - SetHandler perl-script - PerlHandler ProductDatabase - +=head3 config -And copy the templates found in F into the -F directory off the web root. When the designers get -back to you with custom templates, they are to go in -F. If you need to do override templates on a -database-table-by-table basis, put the new template in -F>. +Returns the L object -This will automatically give you C, C, C, C and -C commands; for instance, a product list, go to +=head3 setup - http://your.site/catalogue/product/list + My::App->setup(); -For a full example, see the included "beer database" application. + Initialise the maypole application and model classes. Your + application should + call this after setting configuration via L<"config"> -=head1 HOW IT WORKS +=head3 init -There's some documentation for the workflow in L, -but the basic idea is that a URL part like C gets -translated into a call to Clist>. This -propagates the request with a set of objects from the database, and then -calls the C template; first, a C template if it -exists, then the C and finally C. +You should not call this directly, but you may wish to override this to +add +application-specific initialisation. -If there's another action you want the system to do, you need to either -subclass the model class, and configure your class slightly differently: +=head3 view_object - package ProductDatabase::Model; - use base 'Maypole::Model::CDBI'; +Get/set the Maypole::View object - sub supersearch :Exported { - my ($self, $request) = @_; - # Do stuff, get a bunch of objects back - $r->objects(\@objects); - $r->template("template_name"); - } +=head3 debug -Then your top-level application package should change the model class: -(Before calling C) + sub My::App::debug {1} - ProductDatabase->config->model("ProductDatabase::Model"); + Returns the debugging flag. Override this in your application class + to + enable/disable debugging. -(The C<:Exported> attribute means that the method can be called via the -URL C/supersearch/...>.) +=head2 INSTANCE METHODS -Alternatively, you can put the method directly into the specific model -class for the table: +=head3 parse_location - sub ProductDatabase::Product::supersearch :Exported { ... } +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. -By default, the view class uses Template Toolkit as the template -processor, and the model class uses C; it may help you to be -familiar with these modules before going much further with this, -although I expect there to be other subclasses for other templating -systems and database abstraction layers as time goes on. The article at -C is a great -introduction to the process we're trying to automate. +You should only need to define this method if you are writing a new +Maypole +backend. -=head1 USING MAYPOLE +=head3 path -You should probably not use Maypole directly. Maypole is an abstract -class which does not specify how to communicate with the outside world. -The most popular subclass of Maypole is L, which interfaces -the Maypole framework to Apache mod_perl; another important one is -L. However, if you just don't care, use Maypole::Application, -and it will choose the right one for you. +Returns the request path -If you are implementing Maypole subclasses, you need to provide at least -the C and C methods. You may also want to -provide C and C. See the -L documentation for what these are expected to do. +=head3 parse_path -=cut +Parses the request path and sets the C, C and C +properties -sub get_template_root { "." } -sub get_request { } +=head3 table -sub parse_location { - die "Do not use Maypole directly; use Apache::MVC or similar"; -} +The table part of the Maypole request path -sub send_output { - die "Do not use Maypole directly; use Apache::MVC or similar"; -} +=head3 action + +The action part of the Maypole request path + +=head3 args + +A list of remaining parts of the request path after table and action +have been +removed + +=head3 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. + +=head3 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. + +B Where muliple values of a parameter were supplied, the +C +value +will be an array reference. + +=head3 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 L + +=head3 is_applicable + +Returns a Maypole::Constant to indicate whether the request is valid. + +The default implimentation checks that C<$r-Etable> is publicly +accessible +and that the model class is configured to handle the C<$r-Eaction> + +=head3 authenticate + +Returns a Maypole::Constant to indicate whether the user is +authenticated for +the Maypole request. + +The default implimentation returns C + +=head3 model_class + +Returns the perl package name that will serve as the model for the +request. It corresponds to the request C
attribute. + +=head3 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. + +=head3 objects + +Get/set a list of model objects. The objects will be accessible in the +view +templates. + +If the first item in C<$r-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. + +=head3 template_args + + $r->template_args->{foo} = 'bar'; + + Get/set a hash of template variables. + +=head3 template + +Get/set the template to be used by the view. By default, it returns +C<$r-Eaction> + +=head3 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. + +=head3 error + +Get/set a request error + +=head3 output + +Get/set the response output. This is usually populated by the view +class. You +can skip view processing by setting the C. + +=head3 document_encoding + +Get/set the output encoding. Default: utf-8. + +=head3 content_type + +Get/set the output content type. Default: text/html + +=head3 send_output + +Sends the output and additional headers to the user. =head1 SEE ALSO -There's more documentation, examples, and a wiki at the Maypole web site: +There's more documentation, examples, and a wiki at the Maypole web +site: -http://maypole.simon-cozens.org/ +http://maypole.perl.org/ L,L, L. @@ -345,7 +415,8 @@ Simon Cozens, C =head1 THANK YOU Danijel Milicevic, Jesse Scheidlower, Jody Belka, Marcus Ramberg, -Mickael Joanne, Simon Flack, Veljko Vidovic and all the others who've helped. +Mickael Joanne, Simon Flack, Veljko Vidovic and all the others who've +helped. =head1 LICENSE diff --git a/doc/About.pod b/lib/Maypole/Manual/About.pod similarity index 100% rename from doc/About.pod rename to lib/Maypole/Manual/About.pod diff --git a/doc/Beer.pod b/lib/Maypole/Manual/Beer.pod similarity index 100% rename from doc/Beer.pod rename to lib/Maypole/Manual/Beer.pod diff --git a/doc/BuySpy.pod b/lib/Maypole/Manual/BuySpy.pod similarity index 100% rename from doc/BuySpy.pod rename to lib/Maypole/Manual/BuySpy.pod diff --git a/doc/Flox.pod b/lib/Maypole/Manual/Flox.pod similarity index 100% rename from doc/Flox.pod rename to lib/Maypole/Manual/Flox.pod diff --git a/doc/Model.pod b/lib/Maypole/Manual/Model.pod similarity index 100% rename from doc/Model.pod rename to lib/Maypole/Manual/Model.pod diff --git a/doc/Overview.pod b/lib/Maypole/Manual/Overview.pod similarity index 100% rename from doc/Overview.pod rename to lib/Maypole/Manual/Overview.pod diff --git a/doc/Request.pod b/lib/Maypole/Manual/Request.pod similarity index 100% rename from doc/Request.pod rename to lib/Maypole/Manual/Request.pod diff --git a/doc/StandardTemplates.pod b/lib/Maypole/Manual/StandardTemplates.pod similarity index 100% rename from doc/StandardTemplates.pod rename to lib/Maypole/Manual/StandardTemplates.pod diff --git a/doc/View.pod b/lib/Maypole/Manual/View.pod similarity index 100% rename from doc/View.pod rename to lib/Maypole/Manual/View.pod -- 2.39.2