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