lib/Catalyst/Manual/About.pod

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