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 |
21 | with a web application, for example: |
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 |
29 | application has to do the right thing to make sure that your data works |
30 | with the web server you're using. If you change your web server, you |
31 | don't want to have to rewrite your entire application to work with the |
32 | new one. |
33 | |
34 | =item * Do something based on a URI |
35 | |
95bb1e81 |
36 | So that C<http://www.mysite.com/catalog/display/23> will go to a |
37 | "display" of item 23 in your catalog, and |
38 | C<http://www.mysite.com/order_status/7582> will display the status of |
39 | order 7582, and C<http://www.mysite.com/add_comment/?page=8> will |
40 | display a form to add a comment to page 8. |
aa2b0d97 |
41 | |
42 | =item * Interact with a data store |
43 | |
44 | You probably use a database to keep track of your information. Your |
45 | application needs an easy way to interact with your database, so you can |
46 | create, edit, and retrieve your data. |
47 | |
48 | =item * Handle forms |
49 | |
50 | When a user submits a form, you process it, and make sure it's been |
51 | filled in properly, and then then do something based on the |
52 | result--submitting an order, updating a record, sending e-mail, or going |
53 | back to the form if there's an error. |
54 | |
55 | =item * Display results |
56 | |
57 | You have an application running on the web, people need to see |
58 | things. You usually want to display things on a web browser; you will |
59 | probably be using a template system to help generate HTML code; you |
60 | might need other kinds of display, such as PDF files or RSS feeds. |
61 | |
62 | =item * Manage users |
63 | |
64 | You might need the concept of a "user", someone who's allowed to use |
65 | your system, and is allowed to do certain things only. Perhaps normal |
66 | users can only view or modify their own information; administrative |
67 | users can view or modify anything; normal users can only order items for |
68 | their own account; normal users can view things but not modify them; |
69 | order-processing users can send records to a different part of the |
70 | system; and so forth. You need a way of ensuring that people are who |
71 | they say they are, and that people only do the things they're allowed to |
72 | do. |
73 | |
74 | =item * Develop the application itself |
75 | |
76 | When you're writing or modifying the application, you want to have |
77 | access to detailed logs of what it is doing. You want to be able to |
78 | write tests to ensure that it does what it's supposed to, and that new |
79 | changes don't break the existing code. |
80 | |
81 | =back |
82 | |
83 | Catalyst makes it easy to do all of these tasks, and many more. It is |
84 | extremely flexible in terms of what it allows you to do, and very fast. |
85 | It has a very large number of "plugins" that interact with existing Perl |
86 | modules so that you can easily using them from within your application. |
87 | |
88 | =head3 What B<isn't> Catalyst? |
89 | |
90 | Catalyst is not an out-of-the-box solution that allows you to set up a |
91 | complete working e-commerce application in ten minutes. (There are, |
92 | however, several systems built on top of Catalyst that can get you very |
93 | close to a working app.) It is not designed for end users, but for |
94 | working programmers. |
95 | |
96 | =head2 Some background |
97 | |
98 | =head2 The MVC pattern |
99 | |
95bb1e81 |
100 | MVC, or Model-View-Controller, is a model currently favored for web |
101 | applications. This design pattern is originally from the Smalltalk |
102 | programming language. The basic idea is that the three main areas of an |
103 | application--handling application flow (Controller), processing |
104 | information (Model), and outputting the results (View)--are kept |
105 | separate, so that it is possible to change or replace any one without |
106 | affecting the others. |
107 | |
108 | Discussions of MVC often degenerate into nitpicky arguments about the |
109 | history of the pattern, and exactly what "usually" or "should" go into |
110 | the Controller or the Model. We have no interest in joining such a |
111 | debate. In any case, Catalyst does not enforce any particular setup; you |
112 | are free to put any sort of code in any part of your application, and |
113 | this discussion (and others elsewhere in the Catalyst documentation) is |
114 | only a suggestion based on what we think works well. In most Catalyst |
115 | applications, each branch of MVC will be made of up of several Perl |
116 | modules that can handle different needs in your application. |
117 | |
118 | The purpose of the B<Model> is to access and modify data. Typically |
119 | the Model will interact with a relational database, but it's also |
120 | common to use other data sources, such as the L<Plucene> search |
121 | engine, an LDAP server, etc. |
122 | |
123 | The purpose of the B<View> is to present data to the user. Typical Views |
124 | use a templating module to generate HTML code, using L<Template |
125 | Toolkit|Template>, L<Mason|HTML::Mason>, L<HTML::Template>, or the like, |
126 | but it's also possible to generate PDF output, send email, etc., from a |
127 | View. In Catalyst the View is usually a small module, just gluing some |
128 | other module into Catalyst; the display logic is written within the |
129 | template itself. |
130 | |
131 | The Controller is Catalyst itself. When a request is made to Catalyst, |
132 | it will be received by one of your Controller modules; this module |
133 | will figure out what the user is trying to do, gather the necessary |
134 | data from a Model, and send it to a View for display. |
135 | |
136 | =head3 A simple example |
137 | |
138 | The general idea is that you should be able to change things around |
139 | without affecting the rest of your application. Let's look at a very |
140 | simple example (keeping in mind that there are many ways of doing this, |
141 | and what we're discussing is one possible way, not the only |
142 | way). Suppose you have a record to display. It doesn't matter if it's a |
143 | catalog entry, a library book, a music CD, a personnel record, or |
144 | anything else, but let's pretend it's a catalog entry. A user is given a |
145 | URL such as C<http://www.mysite.com/catalog/display/2782>. Now what? |
146 | |
147 | First, Catalyst figures out that you're using the "catalog" Controller |
148 | (how Catalyst figures this out is entirely up to you; URL dispatching is |
149 | I<extremely> flexible in Catalyst). Then Catalyst sees that you want to |
150 | use a "display" method in your Controller. Somewhere in this process, |
151 | it's possible that you'll have authentication and authorization routines |
152 | to make sure that the user is registered and is allowed to display a |
153 | record. The Controller's display method will then extract "2782" as the |
154 | record you want to retrieve, and make a request to a Model for that |
155 | record. The Controller will then look at what the Model returns: if |
156 | there's no record, the Controller will ask the View to display an error |
157 | message, otherwise it will hand the View the record and ask the View to |
158 | display it. In either case, the View will then generate an HTML page, |
159 | which Catalyst will display to the user's browser, using whatever web |
160 | server you've configured. |
161 | |
162 | How does this help you? |
163 | |
164 | In many ways. Suppose you have a small catalog now, and you're using a |
165 | lightweight database such as SQLite, or even a text file. But eventually |
166 | your site grows, and you need to upgrade to something more |
167 | powerful--MySQL or Postgres, or even Oracle or DB2. If your Model is |
168 | separate, you only have to change one thing, the Model; your Controller |
169 | can expect that if it issues a query to the Model, it will get the right |
170 | kind of result back. |
171 | |
172 | What about the View? The idea is that your template is concerned almost |
173 | entirely with display, so that you can hand it off to a designer who |
174 | doesn't have to worry about how to write code. If you get all the data |
175 | in the Controller and then pass it to the View, the template isn't |
176 | responsible for any kind of data processing. And if you want to change |
177 | your output, it's simple: just write a new View. If your Controller is |
178 | already getting the data you need, you pass it in the same way, and |
179 | whether you display the results to a web browser, generate a PDF, or |
180 | e-mail the results back to the user, the Controller hardly changes at |
181 | all. |
182 | |
183 | And throughout the whole process, most of the tools you need are either |
184 | part of Catalyst (the parameter-processing routines that extract "2782" |
185 | from the URL, for example) or are easily plugged into it (the |
186 | authentication routines, the plugins for using Template Toolkit as your |
187 | View). |
188 | |
189 | Now, Catalyst doesn't enforce very much at all. You can connect to a |
190 | database, issue queries, and act on them from within your View, if you |
191 | want. You can handle paging (i.e. retrieving only a portion of the total |
192 | records possible) in your Controller or your Model. It's up to you. In |
193 | some cases there might be very good reasons to do things a certain way |
194 | (issuing database queries from a template seems to defeat the whole |
195 | purpose of separation-of-concerns, and will drive your designer crazy), |
196 | while in others it's just a matter of personal preference (perhaps your |
197 | template, rather than your Controller, is the better place to decide |
198 | what to display if you get an empty result). Catalyst just gives you the |
199 | tools. |
200 | |
aa2b0d97 |
201 | =head1 AUTHOR |
202 | |
203 | Jesse Sheidlower, C<jester@panix.com> |
204 | |
205 | =head1 SEE ALSO |
206 | |
207 | L<Catalyst>, L<Catalyst::Manual::Intro> |
208 | |
209 | =head1 COPYRIGHT |
210 | |
211 | This program is free software, you can redistribute it and/or modify it |
212 | under the same terms as Perl itself. |