If the others are bolded, why not this one?
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / About.pod
cb93c9d7 1=head1 NAME
3Catalyst::Manual::About - The philosophy of Catalyst
7This document is a basic introduction to the I<why> of Catalyst. It does
8not teach you how to write Catalyst applications; for an introduction to
9that please see L<Catalyst::Manual::Intro>. Rather, it explains the
10basics of what Catalyst is typically used for, and why you might want
11to use Catalyst to build your applications.
13=head2 What is Catalyst? The short summary
15Catalyst is a web application framework. This means that you use it to
16help build applications that run on the web, or that run using protocols
17used for the web. Catalyst is designed to make it easy to manage the
18various tasks you need to do to run an application on the web, either by
19doing them itself, or by letting you "plug in" existing Perl modules
20that do what you need. There are a number of things you typically do
21with a web application. For example:
23=over 4
25=item * Interact with a web server
27If you're on the web, you're relying on a web server, a program that
28sends files over the web. There are a number of these, and your
29application has to do the right thing to make sure that your program
30works with the web server you're using. If you change your web server,
31you don't want to have to rewrite your entire application to work with
32the new one.
34=item * Do something based on a URI
36It's typical for web applications to use URIs as a main way for users to
37interact with the rest of the application; various elements of the URI
38will indicate what the application needs to do. Thus,
39C<http://www.mysite.com/add_record.cgi?name=John&title=President> will
40add a person named "John" whose title is "President" to your database,
41and C<http://www.mysite.com/catalog/display/23> will go to a "display"
42of item 23 in your catalog, and
43C<http://www.mysite.com/order_status/7582> will display the status of
44order 7582, and C<http://www.mysite.com/add_comment/?page=8> will
45display a form to add a comment to page 8. Your application needs to
46have a regular way of processing these URIs so it knows what to do
47when such a request comes in.
49=item * Interact with a data store
51You probably use a database to keep track of your information. Your
52application needs to interact with your database, so you can create,
53edit, and retrieve your data.
55=item * Handle forms
57When a user submits a form, you receive it, process it to make sure it's
58been filled in properly, and then do something based on the
59result--submit an order, update a record, send e-mail, or return to the
60form if there's an error.
62=item * Display results
64If you have an application running on the web, people need to see
65things. You usually want your application displayed on a web browser, in
66which case you will probably be using a template system to help generate
67HTML code. But you might need other kinds of display, such as PDF files,
68or other forms of output, such as RSS feeds or e-mail.
70=item * Manage users
72You might need the concept of a "user", someone who's allowed to use
73your system, and is allowed to do certain things only. Perhaps normal
74users can only view or modify their own information; administrative
75users can view or modify anything; normal users can only order items for
76their own account; normal users can view things but not modify them;
77order-processing users can send records to a different part of the
78system; and so forth. You need a way of ensuring that people are who
79they say they are, and that people only do the things they're allowed to
82=item * Develop the application itself
84When you're writing or modifying the application, you want to have
85access to detailed logs of what it is doing. You want to be able to
86write tests to ensure that it does what it's supposed to, and that new
87changes don't break the existing code.
91Catalyst makes it easy to do all of these tasks, and many more. It is
92extremely flexible in terms of what it allows you to do, and very fast.
b1a08fe1 93It has a large number of "components" and "plugins" that interact with existing Perl
cb93c9d7 94modules so that you can easily use them from within your
b1a08fe1 95application.
cb93c9d7 96
97=over 4
b1a08fe1 99=item * Interact with a web server?
cb93c9d7 100
101Catalyst lets you use a number of different ones, and even comes with a
102built-in server for testing or local deployment.
b1a08fe1 104=item * Do something based on a URI?
cb93c9d7 105
106Catalyst has extremely flexible systems for figuring out what to do
107based on a URI.
109=item * Interact with a data store?
111Catalyst has many plugins for different databases and database
112frameworks, and for other non-database storage systems.
b1a08fe1 114=item * Handle forms?
cb93c9d7 115
116Catalyst has plugins available for several form creation and validation
117systems that make it easy for the programmer to manage.
119=item * Display results?
121Catalyst has plugins available for a number of template modules and
122other output packages.
b1a08fe1 124=item * Manage users?
cb93c9d7 125
126Catalyst has plugins that handle sessions, authentication, and
127authorization, in any way you need.
b1a08fe1 129=item * Developing the application?
cb93c9d7 130
131Catalyst has detailed logging built-in, which you can configure as
132necessary, and supports the easy creation of new tests--some of which
133are automatically created when you begin writing a new application.
137=head3 What B<isn't> Catalyst?
139Catalyst is not an out-of-the-box solution that allows you to set up a
140complete working e-commerce application in ten minutes. (There are,
141however, several systems built on top of Catalyst that can get you very
142close to a working app.)
144Catalyst is designed for flexibility and power; to an extent, this comes
145at the expense of simplicity. Programmers have many options for almost
146everything they need to do, which means that any given need can be done
147in many ways, and finding the one that's right for you, and learning the
148right way to do it, can take time. TIMTOWDI works both ways.
150Catalyst is not designed for end users, but for working programmers.
152=head2 Web programming: The Olden Days
154Perl has long been favored for web applications. There are a wide
155variety of ways to use Perl on the web, and things have changed over
156time. It's possible to handle everything with very raw Perl code:
158 print "Content-type: text/html\n\n<center><h1>Hello
159 World!</h1></center>";
161for example, or
163 my @query_elements = split(/&/, $ENV{'QUERY_STRING'});
164 foreach my $element (@query_elements) {
165 my ($name, $value) = split(/=/, $element);
166 # do something with your parameters, or kill yourself
167 # in frustration for having to program like this
168 }
170Much better than this is to use Lincoln Stein's great L<CGI> module,
171which smoothly handles a wide variety of common tasks--parameter
172parsing, generating form elements from Perl data structures, printing
173http headers, escaping text, and very many more, all with your choice of
174functional or object-oriented style. While L<CGI> was revolutionary and
175is still widely used, it has various drawbacks that make it unsuitable
176for larger applications: it is slow; your code with it generally
177combines application logic and display code; and it makes it very
178difficult to handle larger applications with complicated control flow.
180A variety of frameworks followed, of which the most widely used is
181probably L<CGI::Application>, which encourages the development of
182modular code, with easy-to-understand control-flow handling, the use of
183plugins and templating systems, and the like. Other systems include
184L<AxKit>, which is designed for use with XML running under mod_perl;
185L<Maypole>--upon which Catalyst was originally based--designed for the
186easy development of powerful web databases; L<Jifty>, which does a great
187deal of automation in helping to set up web sites with many complex
188features; and Ruby on Rails (see L<http://www.rubyonrails.org>), written
09a96512 189of course in Ruby and among the most popular web development systems. It
190is not the purpose of this document to criticize or even briefly
cb93c9d7 191evaluate these other frameworks; they may be useful for you and if so we
192encourage you to give them a try.
194=head2 The MVC pattern
196MVC, or Model-View-Controller, is a model currently favored for web
197applications. This design pattern is originally from the Smalltalk
198programming language. The basic idea is that the three main areas of an
199application--handling application flow (Controller), processing
200information (Model), and outputting the results (View)--are kept
201separate, so that it is possible to change or replace any one without
202affecting the others, and so that if you're interested in one particular
203aspect, you know where to find it.
205Discussions of MVC often degenerate into nitpicky arguments about the
206history of the pattern, and exactly what "usually" or "should" go into
207the Controller or the Model. We have no interest in joining such a
208debate. In any case, Catalyst does not enforce any particular setup; you
209are free to put any sort of code in any part of your application, and
210this discussion, along with others elsewhere in the Catalyst
211documentation, are only suggestions based on what we think works
212well. In most Catalyst applications, each branch of MVC will be made of
213up of several Perl modules that can handle different needs in your
216The purpose of the B<Model> is to access and modify data. Typically the
217Model will interact with a relational database, but it's also common to
218use other data sources, such as the L<Xapian|Catalyst::Model::Xapian>
219search engine or an LDAP server.
221The purpose of the B<View> is to present data to the user. Typical Views
222use a templating module to generate HTML code, using L<Template
223Toolkit|Template>, L<Mason|HTML::Mason>, L<HTML::Template>, or the like,
224but it's also possible to generate PDF output, send e-mail, etc., from a
225View. In Catalyst applications the View is usually a small module, just
226gluing some other module into Catalyst; the display logic is written
227within the template itself.
8b75173d 229The B<Controller> is Catalyst itself. When a request is made to Catalyst,
cb93c9d7 230it will be received by one of your Controller modules; this module
231will figure out what the user is trying to do, gather the necessary
232data from a Model, and send it to a View for display.
234=head3 A simple example
236The general idea is that you should be able to change things around
237without affecting the rest of your application. Let's look at a very
238simple example (keeping in mind that there are many ways of doing this,
239and what we're discussing is one possible way, not the only
240way). Suppose you have a record to display. It doesn't matter if it's a
241catalog entry, a library book, a music CD, a personnel record, or
242anything else, but let's pretend it's a catalog entry. A user is given a
243URL such as C<http://www.mysite.com/catalog/display/2782>. Now what?
245First, Catalyst figures out that you're using the "catalog" Controller
246(how Catalyst figures this out is entirely up to you; URL dispatching is
247I<extremely> flexible in Catalyst). Then Catalyst determines that you
248want to use a C<display> method in your "catalog" Controller. (There
249could be other C<display> methods in other Controllers, too.) Somewhere
250in this process, it's possible that you'll have authentication and
251authorization routines to make sure that the user is registered and is
252allowed to display a record. The Controller's C<display> method will
253then extract "2782" as the record you want to retrieve, and make a
254request to a Model for that record. The Controller will then look at
255what the Model returns: if there's no record, the Controller will ask
256the View to display an error message, otherwise it will hand the View
257the record and ask the View to display it. In either case, the View will
258then generate an HTML page, which Catalyst will send to the user's
259browser, using whatever web server you've configured.
e91e320b 261=head3 How does this help you?
cb93c9d7 262
263In many ways. Suppose you have a small catalog now, and you're using a
264lightweight database such as SQLite, or maybe just a text file. But
265eventually your site grows, and you need to upgrade to something more
266powerful--MySQL or Postgres, or even Oracle or DB2. If your Model is
267separate, you only have to change one thing, the Model; your Controller
268can expect that if it issues a query to the Model, it will get the right
269kind of result back.
271What about the View? The idea is that your template is concerned almost
272entirely with display, so that you can hand it off to a designer who
273doesn't have to worry about how to write code. If you get all the data
274in the Controller and then pass it to the View, the template isn't
275responsible for any kind of data processing. And if you want to change
276your output, it's simple: just write a new View. If your Controller is
277already getting the data you need, you can pass it in the same way, and
278whether you display the results to a web browser, generate a PDF, or
279e-mail the results back to the user, the Controller hardly changes at
280all--it's up to the View.
282And throughout the whole process, most of the tools you need are either
283part of Catalyst (the parameter-processing routines that extract "2782"
284from the URL, for example) or are easily plugged into it (the
285authentication routines, or the plugins for using Template Toolkit as
286your View).
288Now, Catalyst doesn't enforce very much at all. Template Toolkit is a
289very powerful templating system, and you can connect to a database,
290issue queries, and act on them from within a TT-based View, if you
291want. You can handle paging (i.e. retrieving only a portion of the total
292records possible) in your Controller or your Model. In the above
293example, your Controller looked at the query result, determining whether
294to ask the View for a no-result error message, or for a result display;
295but it's perfectly possible to hand your query result directly to the
296View, and let your template decide what to do. It's up to you; Catalyst
297doesn't enforce anything.
299In some cases there might be very good reasons to do things a certain
300way (issuing database queries from a template defeats the whole purpose
301of separation-of-concerns, and will drive your designer crazy), while in
302others it's just a matter of personal preference (perhaps your template,
303rather than your Controller, is the better place to decide what to
304display if you get an empty result). Catalyst just gives you the tools.
cb93c9d7 306=head1 SEE ALSO
308L<Catalyst>, L<Catalyst::Manual::Intro>
bbddff00 310=head1 AUTHORS
312Catalyst Contributors, see Catalyst.pm
cb93c9d7 314=head1 COPYRIGHT
bbddff00 316This library is free software. You can redistribute it and/or modify it under
317the same terms as Perl itself.