]> git.decadent.org.uk Git - maypole.git/blob - lib/Maypole/Manual.pod
added preprocess_location method
[maypole.git] / lib / Maypole / Manual.pod
1 =head1 NAME
2
3 Maypole::Manual - The Maypole Manual
4
5 =head1 DESCRIPTION
6
7 The Maypole documentation is arranged over several files; this is 
8 the right one to start with, as it provides an overview of the
9 entire set of Maypole manuals, with a brief description of each.
10 Some of these manuals are not yet finished, but they should still
11 be useful.
12
13 =over 4
14
15 =item L<Maypole::Manual::About> - Overview of the Project
16
17 This document is a general introduction to Maypole: what it is, what it
18 does and how it works.
19
20 Maypole is a framework for Web development. At the basic level, it
21 converts a URL like C<http://www.mysite.com/product/display/12> into a
22 method call such as "perform the C<display> method on item C<12> in the
23 C<product> table" and then shows the result: here, presumably, a
24 description of item C<12> in your product database,
25
26 It is based on Model-View-Controller (MVC), a design paradigm in
27 which each major aspect of an application's operation is
28 handled by a different and totally separate system).
29
30 Basic installation instructions are given. A sample Web
31 application--the Beer database--is introduced, set up, and
32 discussed. Finally, the path a Maypole request takes as it
33 moves through the system is described.
34
35 =item L<Maypole::Manual::Model> - Model Classes *
36
37 This document introduces the I<model class>, which controls
38 the interaction between Maypole and your database. The use of
39 "actions"--method calls that operate on your database--is
40 discussed. Maypole's default model class is L<Class::DBI>,
41 which basically creates a class for each table in your
42 database and provides a variety of convenient methods for
43 manipulating each table and its relations. It integrates very
44 smoothly with Maypole's default L<view class|Maypole::Manual::View>,
45 the L<Template|Template> Toolkit.
46
47 =item L<Maypole::Manual::View> - View Classes *
48
49 This document is an extensive discussion of Maypole's I<view class>,
50 which takes the data produced by the model (see
51 above) and sends it through a templating
52 system in order to produce output. It focusses chiefly on
53 the L<Template> Toolkit, which is Maypole's default templating
54 system, but discusses other possibilities.
55
56 =item L<Maypole::Manual::StandardTemplates> - Standard actions and templates *
57
58 This document discusses the standard actions and templates
59 that Maypole uses. The standard actions (method calls that
60 operate on your database) include C<list>, which generates a
61 paged list of a table suitable for browsing, and C<search>, which
62 handles a search query and generates search results.
63
64 The standard templates, which generate output for display on
65 the Web, also include C<list>, which displays the entries in a
66 table, and C<search>, which displays the result of a search.
67
68 You'll note that most actions are associated with templates.
69
70 This document also introduces the theory behind Maypole's
71 actions and templates, showing you how to write your own
72 so that you can have a highly customized application.
73
74 =item L<Maypole::Manual::Plugins> - writing Maypole plugins
75
76 Useful information for plugin authors. 
77
78 =item L<Maypole::Manual::Terminology> - pinning down usage
79
80 As well as defining common terms used in Maypole discussions, this document 
81 briefly discusses the MVC-ness of Maypole. 
82
83 =item L<Maypole::Manual::Workflow> - Description of the Request Workflow 
84
85 This is a technical document that describes the progress of a
86 request through the entire Maypole system. It should be of
87 interest chiefly to those people hacking on Maypole itself,
88 and not to most of those who are using it.
89
90 =item L<Maypole::Manual::Beer> - The Beer Database Revisited *
91
92 This document gives a close look at the Beer database that
93 was introduced in L<Maypole::Manual::About>.
94
95 =item L<Maypole::Manual::Cookbook> - The Maypole Cookbook 
96
97 This extensive document is Maypole's main "How do I do X?" FAQ.
98 It provides a wide variety of cookbook-like techniques that
99 are useful both for themselves, and as examples of what sort
100 of things can be done with Maypole processes.
101
102 =item L<Maypole::Manual::Flox> - Case Study: Flox social network *
103
104 This is an example of how to construct a large Web application
105 in Maypole: a "social network", similar to Friendster and
106 Orkut. It shows, specifically, the database structure and the
107 variety of customized techniques that make such a system
108 work.
109
110 =item L<Maypole::Manual::BuySpy> - Case Study: iBuySpy *
111
112 This is an example of the C<ASP.NET> sample portal application
113 ported to Maypole. L<http://www.ibuyspy.com> is a fictional
114 e-commerce site that is relatively sophisticated. It is much
115 better as a Maypole application.
116
117 =back
118
119   * indicates incomplete chapters.
120
121 =head1 SEE ALSO
122
123 L<http://maypole.perl.org>
124
125 =head1 AUTHOR
126
127 The Maypole Manual was written by Simon Cozens. A generous grant from the Perl
128 Foundation in the first quarter of 2004 funded some of the chapters of this
129 manual.
130
131 This overview was rewritten by Jesse Sheidlower, C<jester#panix.com>,
132 based on Simon Cozens' original I<Overview> document.
133
134 In December 2004, Dave Howorth, C<dave.howorth#acm.org> kindly donated some
135 of his spare time to improve the structure of the manual and bring it up to
136 date.
137
138 =head1 AUTHOR EMERITUS
139
140 Simon Cozens, C<simon#cpan.org>
141
142 =cut