Commit | Line | Data |
d442cc9f |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction |
4 | |
5 | |
6 | =head1 OVERVIEW |
7 | |
2b6c29a2 |
8 | This is B<Part 1 of 10> for the Catalyst tutorial. |
d442cc9f |
9 | |
10 | L<Tutorial Overview|Catalyst::Manual::Tutorial> |
11 | |
12 | =over 4 |
13 | |
14 | =item 1 |
15 | |
16 | B<Introduction> |
17 | |
18 | =item 2 |
19 | |
20 | L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics> |
21 | |
22 | =item 3 |
23 | |
1def4a20 |
24 | L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics> |
d442cc9f |
25 | |
26 | =item 4 |
27 | |
1def4a20 |
28 | L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD> |
d442cc9f |
29 | |
30 | =item 5 |
31 | |
1def4a20 |
32 | L<Authentication|Catalyst::Manual::Tutorial::Authentication> |
d442cc9f |
33 | |
34 | =item 6 |
35 | |
1def4a20 |
36 | L<Authorization|Catalyst::Manual::Tutorial::Authorization> |
d442cc9f |
37 | |
38 | =item 7 |
39 | |
1def4a20 |
40 | L<Debugging|Catalyst::Manual::Tutorial::Debugging> |
d442cc9f |
41 | |
42 | =item 8 |
43 | |
1def4a20 |
44 | L<Testing|Catalyst::Manual::Tutorial::Testing> |
d442cc9f |
45 | |
46 | =item 9 |
47 | |
1def4a20 |
48 | L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD> |
49 | |
50 | =item 10 |
51 | |
d442cc9f |
52 | L<Appendices|Catalyst::Manual::Tutorial::Appendices> |
53 | |
54 | =back |
55 | |
1def4a20 |
56 | |
d442cc9f |
57 | =head1 DESCRIPTION |
58 | |
ffeb7448 |
59 | This tutorial provides a multi-part introduction to the Catalyst web |
d442cc9f |
60 | framework. It seeks to provide a rapid overview of many of its most |
61 | commonly used features. The focus is on the real-world best practices |
62 | required in the construction of nearly all Catalyst applications. |
63 | |
64 | Although the primary target of the tutorial is users new to the Catalyst |
65 | framework, experienced users may wish to review specific sections (for |
1def4a20 |
66 | example, how to use DBIC for their model classes, how to add |
67 | authentication and authorization to an existing application, or form |
68 | management). |
d442cc9f |
69 | |
70 | You can obtain the code for all the tutorial examples from the |
71 | catalyst subversion repository by issuing the command: |
72 | |
028b4e1a |
73 | svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial |
d442cc9f |
74 | |
028b4e1a |
75 | This will download the most recent tarball for each part of the |
76 | tutorial into the CatalystTutorial directory on your machine. |
d442cc9f |
77 | |
3d9ae335 |
78 | B<These reference implementations are provided so that when you follow |
79 | the tutorial, you can use the code from the subversion repository to |
80 | ensure that your system is set up correctly, and that you have not |
81 | inadvertently made any typographic errors, or accidentally skipped |
82 | part of the tutorial.> |
83 | |
ffeb7448 |
84 | B<NOTE: You can use any Perl-supported OS and environment to run |
3533daff |
85 | Catalyst.> It should make little or no difference to Catalyst's |
ffeb7448 |
86 | operation, B<but this tutorial has been written using Ubuntu 8.10> |
3533daff |
87 | because that represents a quick and easy for most people to try out |
ffeb7448 |
88 | Catalyst with virtually zero setup time and hassles. Also, the tutorial |
89 | has been tested to work correctly with the versions of Catalyst and all |
90 | the supporting modules in Ubuntu 8.10 (see "VERSIONS AND CONVENTIONS |
91 | USED IN THIS TUTORIAL" below for the specific versions for some of the |
92 | key modules), so B<if you think you might be running into an issue |
93 | related to versions> (for example, a module changed its behavior in a |
94 | newer version or a bug was introduced), B<it might be worth giving |
95 | Ubuntu 8.10 a try>. See the "CATALYST INSTALLATION" section below for |
96 | more information. |
3533daff |
97 | |
98 | If you're reading this manual online, you can download the example |
99 | program and all the necessary dependencies to your local machine by |
100 | installing the C<Task::Catalyst::Tutorial> distribution from CPAN: |
d442cc9f |
101 | |
102 | cpan Task::Catalyst::Tutorial |
103 | |
104 | This will also test to make sure the dependencies are working. If you |
105 | have trouble installing these, please ask for help on the #catalyst |
106 | IRC channel, or the Catalyst mailing list. |
107 | |
3533daff |
108 | Subjects covered by the tutorial include: |
d442cc9f |
109 | |
110 | =over 4 |
111 | |
112 | =item * |
113 | |
114 | A simple application that lists and adds books. |
115 | |
116 | =item * |
117 | |
118 | The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model. |
119 | |
120 | =item * |
121 | |
122 | How to write CRUD (Create, Read, Update, and Delete) operations in |
123 | Catalyst. |
124 | |
125 | =item * |
126 | |
127 | Authentication ("auth"). |
128 | |
129 | =item * |
130 | |
131 | Role-based authorization ("authz"). |
132 | |
133 | =item * |
134 | |
135 | Attempts to provide an example showing current (5.7XXX) Catalyst |
136 | practices. For example, the use of |
137 | L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>, |
138 | DBIC, L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> |
45d511e0 |
139 | with C<myapp.conf>, the use of C<lib/MyApp/Controller/Root.pm> |
d442cc9f |
140 | vs. C<lib/MyApp.pm>, etc. |
141 | |
142 | =item * |
143 | |
1390ef0e |
144 | The use of Template Toolkit (TT). |
d442cc9f |
145 | |
146 | =item * |
147 | |
148 | Useful techniques for troubleshooting and debugging Catalyst |
149 | applications. |
150 | |
151 | =item * |
152 | |
153 | The use of SQLite as a database (with code also provided for MySQL and |
154 | PostgreSQL). |
155 | |
156 | =item * |
157 | |
1def4a20 |
158 | The use of L<HTML::FormFu|HTML::FormFu> for automated form processing |
d442cc9f |
159 | and validation. |
160 | |
161 | =back |
162 | |
163 | This tutorial makes the learning process its main priority. For |
164 | example, the level of comments in the code found here would likely be |
1def4a20 |
165 | considered excessive in a "normal project." Because of their contextual |
d442cc9f |
166 | value, this tutorial will generally favor inline comments over a |
167 | separate discussion in the text. It also deliberately tries to |
168 | demonstrate multiple approaches to various features (in general, you |
169 | should try to be as consistent as possible with your own production |
170 | code). |
171 | |
172 | Furthermore, this tutorial tries to minimize the number of controllers, |
173 | models, TT templates, and database tables. Although this does result in |
174 | things being a bit contrived at times, the concepts should be applicable |
175 | to more complex environments. More complete and complicated example |
176 | applications can be found in the C<examples> area of the Catalyst |
177 | Subversion repository at |
178 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>. |
179 | |
1390ef0e |
180 | |
d442cc9f |
181 | =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL |
182 | |
183 | This tutorial was built using the following resources. Please note that |
184 | you may need to make adjustments for different environments and |
185 | versions: |
186 | |
187 | =over 4 |
188 | |
189 | =item * |
190 | |
865d3efb |
191 | Ubuntu 8.10 (Intrepid Ibex) |
d442cc9f |
192 | |
193 | =item * |
194 | |
865d3efb |
195 | Catalyst v5.7014 |
dd88c3b6 |
196 | |
22a67212 |
197 | =item * |
dd88c3b6 |
198 | |
865d3efb |
199 | Catalyst::Devel v1.07 |
d442cc9f |
200 | |
201 | =item * |
202 | |
865d3efb |
203 | DBIx::Class v0.08010 |
d442cc9f |
204 | |
205 | =item * |
206 | |
207 | Catalyst Plugins |
208 | |
209 | The plugins used in this tutorial all have sufficiently stable APIs that |
210 | you shouldn't need to worry about versions. However, there could be |
211 | cases where the tutorial is affected by what version of plugins you |
212 | use. This tutorial has been tested against the following set of plugins: |
213 | |
214 | =over 4 |
215 | |
216 | =item * |
217 | |
865d3efb |
218 | Catalyst::Plugin::Authentication -- v0.10006 |
d442cc9f |
219 | |
220 | =item * |
221 | |
1def4a20 |
222 | Catalyst::Plugin::Authorization::ACL -- v0.08 |
d442cc9f |
223 | |
224 | =item * |
225 | |
1def4a20 |
226 | Catalyst::Plugin::Authorization::Roles -- v0.05 |
d442cc9f |
227 | |
228 | =item * |
229 | |
865d3efb |
230 | Catalyst::Plugin::ConfigLoader -- v0.20 |
d442cc9f |
231 | |
232 | =item * |
233 | |
865d3efb |
234 | Catalyst::Plugin::Session -- v0.19 |
d442cc9f |
235 | |
236 | =item * |
237 | |
865d3efb |
238 | Catalyst::Plugin::Session::State::Cookie -- v0.09 |
d442cc9f |
239 | |
240 | =item * |
241 | |
865d3efb |
242 | Catalyst::Plugin::Session::Store::FastMmap -- v0.05 |
d442cc9f |
243 | |
244 | =item * |
245 | |
865d3efb |
246 | Catalyst::Plugin::StackTrace -- v0.08 |
d442cc9f |
247 | |
248 | =item * |
249 | |
1def4a20 |
250 | Catalyst::Plugin::Static::Simple -- v0.20 |
d442cc9f |
251 | |
252 | =back |
253 | |
254 | =item * |
255 | |
865d3efb |
256 | B<NOTE:> You can check the versions you have installed with the |
257 | following command: |
258 | |
259 | perl -ME<lt>mod_nameE<gt> -e '"print $E<lt>mod_nameE<gt>::VERSION\n"' |
260 | |
261 | For example: |
262 | perl -MCatalyst::Plugin::StackTrace -e 'print "$Catalyst::Plugin::StackTrace::VERSION\n"' |
263 | |
d442cc9f |
264 | Since the web browser is being used on the same box where Perl and the |
265 | Catalyst development server is running, the URL of |
266 | C<http://localhost:3000> will be used (the Catalyst development server |
267 | defaults to port 3000). If you are running Perl on a different box than |
268 | where your web browser is located (or using a different port number via |
269 | the C<-p> I<port_number> option to the development server), then you |
270 | will need to update the URL you use accordingly. |
271 | |
272 | =item * |
273 | |
1390ef0e |
274 | Depending on the web browser you are using, you might need to hit |
275 | C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when testing |
276 | your application at various points (see |
277 | L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive |
278 | list of options for each browser). Also, the C<-k> keepalive option |
279 | to the development server can be necessary with some browsers |
280 | (especially Internet Explorer). |
d442cc9f |
281 | |
282 | =back |
283 | |
1390ef0e |
284 | |
d442cc9f |
285 | =head1 CATALYST INSTALLATION |
286 | |
6c3e46a6 |
287 | While the rough edges of Catalyst installation have been a problem in |
0c51850e |
288 | the past, this is now mostly solved. Nonetheless, installing Catalyst |
289 | can be a little time consuming. Although a compelling strength of |
290 | Catalyst is that it makes use of many of the modules in the vast |
291 | repository that is CPAN, this can complicate the installation process. |
292 | However, there are a growing number of methods that can dramatically |
293 | ease this undertaking. Of these, the following are likely to be |
294 | applicable to the largest number of potential new users: |
1def4a20 |
295 | |
296 | =over 4 |
297 | |
298 | =item * |
299 | |
300 | Ubuntu |
301 | |
ffeb7448 |
302 | Given the popularity of Ubuntu and its ease of use, Ubuntu can be a |
303 | great way for newcomers to experiment with Catalyst. Because it is a |
304 | "live CD," you can simply boot from the CD, run a few commands, and you |
305 | should have a fully functional environment in which to do this tutorial |
306 | in a matter of minutes. B<The tutorial was fully tested to work under |
307 | Ubuntu 8.10. Although it SHOULD work under any Catalyst installation |
308 | method you might choose, it can be hard to guarantee this.> |
d442cc9f |
309 | |
310 | =over 4 |
311 | |
312 | =item * |
313 | |
865d3efb |
314 | Download Ubuntu 8.10 (aka, Intrepid Ibex) Desktop edition and boot from |
3533daff |
315 | the CD and/or image file, select your language, and then "Try Ubuntu |
316 | without any changes to your computer." |
1def4a20 |
317 | |
318 | =item * |
319 | |
3533daff |
320 | Open a terminal session (click "Applications" in the upper-left |
321 | corner, then "Accessories," then "Terminal"). |
1def4a20 |
322 | |
323 | =item * |
324 | |
325 | Add the 'universe' repositories: |
326 | |
3533daff |
327 | sudo gedit /etc/apt/sources.list |
1def4a20 |
328 | |
329 | And remove the comments from the lines under the comments about the |
330 | 'universe' repositories. |
331 | |
332 | =item * |
333 | |
334 | Install Catalyst: |
335 | |
336 | sudo apt-get update |
15e1d0b2 |
337 | sudo apt-get install libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl libconfig-general-perl |
1def4a20 |
338 | |
2b75577c |
339 | Accept all of the dependencies. Done. |
340 | |
341 | If you are running from the Live CD, you probably also want to free up |
342 | some disk space with the following: |
343 | |
344 | sudo apt-get clean |
345 | |
346 | NOTE: While the instructions above mention the Live CD because that |
347 | makes it easy for people new to Linux, you can obviously also use one |
348 | of the options to install Ubuntu on your drive. |
3533daff |
349 | |
1def4a20 |
350 | =back |
351 | |
352 | =item * |
353 | |
d442cc9f |
354 | Matt Trout's C<cat-install> |
355 | |
ffeb7448 |
356 | Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>, |
357 | C<cat-install> can be a fairly painless way to get Catalyst up and |
358 | running. Just download the script from the link above and type C<perl |
359 | cat-install>. Depending on the speed of your Internet connection and |
360 | your computer, it will probably take 30 to 60 minutes to install because |
361 | it downloads, makes, compiles, and tests every module. But this is an |
362 | excellent way to automate the installation of all the latest modules |
363 | used by Catalyst from CPAN. |
364 | |
d442cc9f |
365 | |
366 | =item * |
367 | |
ffeb7448 |
368 | Other Possibilities |
369 | |
370 | =over 4 |
371 | |
372 | =item * |
373 | |
374 | OpenBSD Packages |
375 | |
376 | The 2008 Advent Day 4 entry has more information on using OpenBSD |
377 | packages to quickly build a system: |
378 | L<http://www.catalystframework.org/calendar/2008/4>. |
379 | |
380 | =item * |
d442cc9f |
381 | |
ffeb7448 |
382 | NetBSD Package Collection on Solaris |
383 | |
384 | The 2008 Advent Day 15 entry has more information on using C<pkgsrc> and |
385 | NetBSD packages on Solaris: |
386 | L<http://www.catalystframework.org/calendar/2008/15|>. |
d442cc9f |
387 | |
388 | =item * |
389 | |
ffeb7448 |
390 | CatInABox |
391 | |
392 | You can get more information at |
393 | L<http://www.catalystframework.org/calendar/2008/7> |
394 | or L<Perl::Dist::CatInABox|Perl::Dist::CatInABox>. |
395 | |
396 | |
397 | =item * |
398 | |
d442cc9f |
399 | Pre-Built VMWare Images |
400 | |
401 | Under the VMWare community program, work is ongoing to develop a number |
402 | of VMWare images where an entire Catalyst development environment has |
403 | already been installed, complete with database engines and a full |
404 | complement of Catalyst plugins. |
405 | |
0c51850e |
406 | =item * |
407 | |
408 | Frank Speiser's Amazon EC2 Catalyst SDK |
409 | |
410 | There are currently two flavors of publicly available Amazon Machine |
411 | Images (AMI) that include all the elements you'd need to begin |
412 | developing in a fully functional Catalyst environment within minutes. |
413 | See L<Catalyst::Manual::Installation|Catalyst::Manual::Installation> |
414 | for more details. |
415 | |
d442cc9f |
416 | =back |
417 | |
ffeb7448 |
418 | =back |
419 | |
d442cc9f |
420 | For additional information and recommendations on Catalyst installation, |
421 | please refer to |
422 | L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>. |
423 | |
424 | B<NOTE:> Step-by-step instructions to replicate the environment on |
425 | which this tutorial was developed can be found at |
426 | L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>. |
427 | Using these instructions, you should be able to build a complete CentOS |
428 | 4.X server with Catalyst and all the plugins required to run this |
429 | tutorial. |
430 | |
1390ef0e |
431 | |
d442cc9f |
432 | =head1 DATABASES |
433 | |
434 | This tutorial will primarily focus on SQLite because of its simplicity |
435 | of installation and use; however, modifications in the script required |
436 | to support MySQL and PostgreSQL will be presented in Appendix 2. |
437 | |
438 | B<Note:> One of the advantages of the MVC design patterns is that |
439 | applications become much more database independent. As such, you will |
440 | notice that only the C<.sql> files used to initialize the database |
441 | change between database systems: the Catalyst code generally remains the |
442 | same. |
443 | |
1390ef0e |
444 | |
d442cc9f |
445 | =head1 WHERE TO GET WORKING CODE |
446 | |
028b4e1a |
447 | Each part of the tutorial has complete code available as a tarball in |
448 | the main Catalyst Subversion repository (see the note at the beginning |
449 | of each part for the appropriate svn command to use). |
d442cc9f |
450 | |
028b4e1a |
451 | B<NOTE:> You can run the test cases for the final code through Part 8 |
452 | with the following commands: |
d442cc9f |
453 | |
028b4e1a |
454 | wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Part8.tgz |
cf582e91 |
455 | tar zxvf MyApp_Part8.tgz |
d442cc9f |
456 | cd MyApp |
457 | CATALYST_DEBUG=0 prove --lib lib t |
458 | |
459 | |
460 | =head1 AUTHOR |
461 | |
462 | Kennedy Clark, C<hkclark@gmail.com> |
463 | |
464 | Please report any errors, issues or suggestions to the author. The |
465 | most recent version of the Catalyst Tutorial can be found at |
82ab4bbf |
466 | L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/>. |
d442cc9f |
467 | |
45c7830f |
468 | Copyright 2006-2008, Kennedy Clark, under Creative Commons License |
865d3efb |
469 | (L<http://creativecommons.org/licenses/by-sa/3.0/us/>). |