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 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.
  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
 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
 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.