Commit | Line | Data |
aa2b0d97 |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::About - Basic explanation of Catalyst |
4 | |
5 | =head1 DESCRIPTION |
6 | |
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. |
12 | |
13 | =head2 What is Catalyst? The short summary |
14 | |
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 |
56d8daeb |
21 | with a web application. For example: |
aa2b0d97 |
22 | |
23 | =over 4 |
24 | |
25 | =item * Interact with a web server |
26 | |
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 |
56d8daeb |
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 |
32 | the new one. |
aa2b0d97 |
33 | |
34 | =item * Do something based on a URI |
35 | |
4100e391 |
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 |
95bb1e81 |
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 |
4100e391 |
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. |
aa2b0d97 |
48 | |
49 | =item * Interact with a data store |
50 | |
51 | You probably use a database to keep track of your information. Your |
4100e391 |
52 | application needs to interact with your database, so you can create, |
53 | edit, and retrieve your data. |
aa2b0d97 |
54 | |
55 | =item * Handle forms |
56 | |
56d8daeb |
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. |
aa2b0d97 |
61 | |
62 | =item * Display results |
63 | |
56d8daeb |
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. |
aa2b0d97 |
69 | |
70 | =item * Manage users |
71 | |
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 |
80 | do. |
81 | |
82 | =item * Develop the application itself |
83 | |
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. |
88 | |
89 | =back |
90 | |
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 |
4100e391 |
94 | modules so that you can easily use them from within your |
56d8daeb |
95 | application. |
96 | |
76ddf86b |
97 | =over 4 |
98 | |
56d8daeb |
99 | =item * Interact with a web server? |
100 | |
101 | Catalyst lets you use a number of different ones, and even comes with a |
102 | built-in server for testing or local deployment. |
103 | |
104 | =item * Do something based on a URI? |
105 | |
106 | Catalyst has extremely flexible systems for figuring out what to do |
107 | based on a URI. |
108 | |
109 | =item * Interact with a data store? |
110 | |
111 | Catalyst has many plugins for different databases and database |
112 | frameworks, and for other non-database storage systems. |
113 | |
114 | =item * Handle forms? |
115 | |
116 | Catalyst has plugins available for several form creation and validation |
117 | systems that make it easy for the programmer to manage. |
118 | |
119 | =item * Display results? |
120 | |
121 | Catalyst has plugins available for a number of template modules and |
122 | other output packages. |
123 | |
124 | =item * Manage users? |
125 | |
126 | Catalyst has plugins that handle sessions, authentication, and |
127 | authorization, in any way you need. |
128 | |
129 | =item * Developing the application? |
130 | |
131 | Catalyst has detailed logging built-in, which you can configure as |
132 | necessary, and supports the easy creation of new tests--some of which |
133 | are automatically created when you begin writing a new application. |
aa2b0d97 |
134 | |
76ddf86b |
135 | =back |
136 | |
aa2b0d97 |
137 | =head3 What B<isn't> Catalyst? |
138 | |
139 | Catalyst is not an out-of-the-box solution that allows you to set up a |
140 | complete working e-commerce application in ten minutes. (There are, |
141 | however, several systems built on top of Catalyst that can get you very |
56d8daeb |
142 | close to a working app.) |
143 | |
144 | Catalyst is not designed for end users, but for working programmers. |
aa2b0d97 |
145 | |
4100e391 |
146 | =head2 Web programming: The Olden Days |
147 | |
148 | Perl has long been favored for web applications. There are a wide |
149 | variety of ways to use Perl on the web, and things have changed over |
150 | time. It's possible to handle everything with very raw Perl code: |
56d8daeb |
151 | |
152 | print "Content-type: text/html\n\n<center><h1>Hello |
153 | World!</h1></center>"; |
154 | |
155 | for example, or |
4100e391 |
156 | |
157 | my @query_elements = split(/&/, $ENV{'QUERY_STRING'}); |
158 | foreach my $element (@query_elements) { |
159 | my ($name, $value) = split(/=/, $element); |
160 | # do something with your parameters, or kill yourself |
161 | # in frustration for having to program like this |
162 | } |
163 | |
164 | Much better than this is to use Lincoln Stein's great L<CGI> module, |
165 | which smoothly handles a wide variety of common tasks--parameter |
166 | parsing, generating form elements from Perl data structures, printing |
167 | http headers, escaping text, and very many more, all with your choice of |
168 | functional or object-oriented style. While L<CGI> was revolutionary and |
169 | is still widely used, it has various drawbacks that make it unsuitable |
56d8daeb |
170 | for larger applications: it is slow; your code with it generally |
171 | combines application logic and display code; and it makes it very |
4100e391 |
172 | difficult to handle larger applications with complicated control flow. |
173 | |
174 | A variety of frameworks followed, of which the most widely used is |
175 | probably L<CGI::Application>, which encourages the development of |
176 | modular code, with easy-to-understand control-flow handling, the use of |
177 | plugins and templating systems, and the like. Other systems include |
178 | L<AxKit>, which is designed for use with XML running under mod_perl, and |
179 | L<Maypole>--upon which Catalyst was originally based--designed for the |
180 | easy development of powerful web databases. Is it not the purpose of |
56d8daeb |
181 | this document to criticize or even briefly evaluate these other |
182 | frameworks; they may be useful for you and if so we encourage you to |
183 | give them a try. |
4100e391 |
184 | |
aa2b0d97 |
185 | =head2 The MVC pattern |
186 | |
95bb1e81 |
187 | MVC, or Model-View-Controller, is a model currently favored for web |
188 | applications. This design pattern is originally from the Smalltalk |
189 | programming language. The basic idea is that the three main areas of an |
190 | application--handling application flow (Controller), processing |
191 | information (Model), and outputting the results (View)--are kept |
192 | separate, so that it is possible to change or replace any one without |
4100e391 |
193 | affecting the others, and so that if you're interested in one particular |
194 | aspect, you know where to find it. |
95bb1e81 |
195 | |
196 | Discussions of MVC often degenerate into nitpicky arguments about the |
197 | history of the pattern, and exactly what "usually" or "should" go into |
198 | the Controller or the Model. We have no interest in joining such a |
199 | debate. In any case, Catalyst does not enforce any particular setup; you |
200 | are free to put any sort of code in any part of your application, and |
56d8daeb |
201 | this discussion, along with others elsewhere in the Catalyst |
202 | documentation, are only suggestions based on what we think works |
203 | well. In most Catalyst applications, each branch of MVC will be made of |
204 | up of several Perl modules that can handle different needs in your |
205 | application. |
95bb1e81 |
206 | |
207 | The purpose of the B<Model> is to access and modify data. Typically |
208 | the Model will interact with a relational database, but it's also |
209 | common to use other data sources, such as the L<Plucene> search |
56d8daeb |
210 | engine or an LDAP server. |
95bb1e81 |
211 | |
212 | The purpose of the B<View> is to present data to the user. Typical Views |
213 | use a templating module to generate HTML code, using L<Template |
214 | Toolkit|Template>, L<Mason|HTML::Mason>, L<HTML::Template>, or the like, |
56d8daeb |
215 | but it's also possible to generate PDF output, send e-mail, etc., from a |
216 | View. In Catalyst applications the View is usually a small module, just |
217 | gluing some other module into Catalyst; the display logic is written |
218 | within the template itself. |
95bb1e81 |
219 | |
220 | The Controller is Catalyst itself. When a request is made to Catalyst, |
221 | it will be received by one of your Controller modules; this module |
222 | will figure out what the user is trying to do, gather the necessary |
223 | data from a Model, and send it to a View for display. |
224 | |
225 | =head3 A simple example |
226 | |
227 | The general idea is that you should be able to change things around |
228 | without affecting the rest of your application. Let's look at a very |
229 | simple example (keeping in mind that there are many ways of doing this, |
230 | and what we're discussing is one possible way, not the only |
231 | way). Suppose you have a record to display. It doesn't matter if it's a |
232 | catalog entry, a library book, a music CD, a personnel record, or |
233 | anything else, but let's pretend it's a catalog entry. A user is given a |
234 | URL such as C<http://www.mysite.com/catalog/display/2782>. Now what? |
235 | |
236 | First, Catalyst figures out that you're using the "catalog" Controller |
237 | (how Catalyst figures this out is entirely up to you; URL dispatching is |
56d8daeb |
238 | I<extremely> flexible in Catalyst). Then Catalyst determines that you |
239 | want to use a C<display> method in your "catalog" Controller. (There |
240 | could be other C<display> methods in other Controllers, too.) Somewhere |
241 | in this process, it's possible that you'll have authentication and |
242 | authorization routines to make sure that the user is registered and is |
243 | allowed to display a record. The Controller's C<display> method will |
244 | then extract "2782" as the record you want to retrieve, and make a |
245 | request to a Model for that record. The Controller will then look at |
246 | what the Model returns: if there's no record, the Controller will ask |
247 | the View to display an error message, otherwise it will hand the View |
248 | the record and ask the View to display it. In either case, the View will |
249 | then generate an HTML page, which Catalyst will send to the user's |
250 | browser, using whatever web server you've configured. |
95bb1e81 |
251 | |
252 | How does this help you? |
253 | |
254 | In many ways. Suppose you have a small catalog now, and you're using a |
56d8daeb |
255 | lightweight database such as SQLite, or maybe just a text file. But |
256 | eventually your site grows, and you need to upgrade to something more |
95bb1e81 |
257 | powerful--MySQL or Postgres, or even Oracle or DB2. If your Model is |
258 | separate, you only have to change one thing, the Model; your Controller |
259 | can expect that if it issues a query to the Model, it will get the right |
56d8daeb |
260 | kind of result back. |
95bb1e81 |
261 | |
262 | What about the View? The idea is that your template is concerned almost |
263 | entirely with display, so that you can hand it off to a designer who |
264 | doesn't have to worry about how to write code. If you get all the data |
265 | in the Controller and then pass it to the View, the template isn't |
266 | responsible for any kind of data processing. And if you want to change |
267 | your output, it's simple: just write a new View. If your Controller is |
56d8daeb |
268 | already getting the data you need, you can pass it in the same way, and |
95bb1e81 |
269 | whether you display the results to a web browser, generate a PDF, or |
270 | e-mail the results back to the user, the Controller hardly changes at |
56d8daeb |
271 | all--it's up to the View. |
95bb1e81 |
272 | |
273 | And throughout the whole process, most of the tools you need are either |
274 | part of Catalyst (the parameter-processing routines that extract "2782" |
275 | from the URL, for example) or are easily plugged into it (the |
56d8daeb |
276 | authentication routines, or the plugins for using Template Toolkit as |
277 | your View). |
95bb1e81 |
278 | |
56d8daeb |
279 | Now, Catalyst doesn't enforce very much at all. Template Toolkit is a |
280 | very powerful templating system, and you can connect to a database, |
281 | issue queries, and act on them from within a TT-based View, if you |
95bb1e81 |
282 | want. You can handle paging (i.e. retrieving only a portion of the total |
56d8daeb |
283 | records possible) in your Controller or your Model. In the above |
284 | example, your Controller looked at the query result, determining whether |
285 | to ask the View for a no-result error message, or for a result display; |
286 | but it's perfectly possible to hand your query result directly to the |
287 | View, and let your template decide what to do. It's up to you; Catalyst |
288 | doesn't enforce anything. |
289 | |
290 | In some cases there might be very good reasons to do things a certain |
291 | way (issuing database queries from a template defeats the whole purpose |
292 | of separation-of-concerns, and will drive your designer crazy), while in |
293 | others it's just a matter of personal preference (perhaps your template, |
294 | rather than your Controller, is the better place to decide what to |
295 | display if you get an empty result). Catalyst just gives you the tools. |
95bb1e81 |
296 | |
aa2b0d97 |
297 | =head1 AUTHOR |
298 | |
299 | Jesse Sheidlower, C<jester@panix.com> |
300 | |
301 | =head1 SEE ALSO |
302 | |
303 | L<Catalyst>, L<Catalyst::Manual::Intro> |
304 | |
305 | =head1 COPYRIGHT |
306 | |
307 | This program is free software, you can redistribute it and/or modify it |
308 | under the same terms as Perl itself. |