Commit | Line | Data |
d442cc9f |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction |
4 | |
5 | |
6 | =head1 OVERVIEW |
7 | |
1def4a20 |
8 | This is B<Part 2 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 | |
59 | This tutorial provides a multipart introduction to the Catalyst web |
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 | |
73 | svn co http://dev.catalyst.perl.org/repos/Catalyst/tags/examples/Tutorial/MyApp/5.7/ CatalystTutorial |
74 | |
75 | This will download the current code for each tutorial chapter in the |
76 | CatalystTutorial directory. Each example application directory has |
77 | the same name as the tutorial chapter. |
78 | |
3d9ae335 |
79 | B<These reference implementations are provided so that when you follow |
80 | the tutorial, you can use the code from the subversion repository to |
81 | ensure that your system is set up correctly, and that you have not |
82 | inadvertently made any typographic errors, or accidentally skipped |
83 | part of the tutorial.> |
84 | |
d442cc9f |
85 | Additionally, if you're reading this manual online, you can download |
3dcf2e2c |
86 | the example program and all the necessary dependencies to |
d442cc9f |
87 | your local machine by installing the C<Task::Catalyst::Tutorial> |
88 | distribution from CPAN: |
89 | |
90 | cpan Task::Catalyst::Tutorial |
91 | |
92 | This will also test to make sure the dependencies are working. If you |
93 | have trouble installing these, please ask for help on the #catalyst |
94 | IRC channel, or the Catalyst mailing list. |
95 | |
96 | Subjects covered include: |
97 | |
98 | =over 4 |
99 | |
100 | =item * |
101 | |
102 | A simple application that lists and adds books. |
103 | |
104 | =item * |
105 | |
106 | The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model. |
107 | |
108 | =item * |
109 | |
110 | How to write CRUD (Create, Read, Update, and Delete) operations in |
111 | Catalyst. |
112 | |
113 | =item * |
114 | |
115 | Authentication ("auth"). |
116 | |
117 | =item * |
118 | |
119 | Role-based authorization ("authz"). |
120 | |
121 | =item * |
122 | |
123 | Attempts to provide an example showing current (5.7XXX) Catalyst |
124 | practices. For example, the use of |
125 | L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>, |
126 | DBIC, L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> |
127 | with C<myapp.yml>, the use of C<lib/MyApp/Controller/Root.pm> |
128 | vs. C<lib/MyApp.pm>, etc. |
129 | |
130 | =item * |
131 | |
132 | The use of Template Toolkit (TT) and the |
133 | L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite> |
134 | view helper. |
135 | |
136 | =item * |
137 | |
138 | Useful techniques for troubleshooting and debugging Catalyst |
139 | applications. |
140 | |
141 | =item * |
142 | |
143 | The use of SQLite as a database (with code also provided for MySQL and |
144 | PostgreSQL). |
145 | |
146 | =item * |
147 | |
1def4a20 |
148 | The use of L<HTML::FormFu|HTML::FormFu> for automated form processing |
d442cc9f |
149 | and validation. |
150 | |
151 | =back |
152 | |
153 | This tutorial makes the learning process its main priority. For |
154 | example, the level of comments in the code found here would likely be |
1def4a20 |
155 | considered excessive in a "normal project." Because of their contextual |
d442cc9f |
156 | value, this tutorial will generally favor inline comments over a |
157 | separate discussion in the text. It also deliberately tries to |
158 | demonstrate multiple approaches to various features (in general, you |
159 | should try to be as consistent as possible with your own production |
160 | code). |
161 | |
162 | Furthermore, this tutorial tries to minimize the number of controllers, |
163 | models, TT templates, and database tables. Although this does result in |
164 | things being a bit contrived at times, the concepts should be applicable |
165 | to more complex environments. More complete and complicated example |
166 | applications can be found in the C<examples> area of the Catalyst |
167 | Subversion repository at |
168 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>. |
169 | |
170 | B<Note:> There are a variety of other introductory materials available |
171 | through the Catalyst web site and at |
172 | L<http://dev.catalyst.perl.org/wiki/UserIntroductions> and |
173 | L<http://dev.catalyst.perl.org/>. |
174 | |
175 | =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL |
176 | |
177 | This tutorial was built using the following resources. Please note that |
178 | you may need to make adjustments for different environments and |
179 | versions: |
180 | |
181 | =over 4 |
182 | |
183 | =item * |
184 | |
1def4a20 |
185 | Ubuntu 8.04 Hardy Heron |
d442cc9f |
186 | |
187 | =item * |
188 | |
1def4a20 |
189 | Catalyst v5.7011 |
dd88c3b6 |
190 | |
22a67212 |
191 | =item * |
dd88c3b6 |
192 | |
1def4a20 |
193 | Catalyst::Devel v1.03 |
d442cc9f |
194 | |
195 | =item * |
196 | |
1def4a20 |
197 | DBIx::Class v0.08008 |
d442cc9f |
198 | |
199 | =item * |
200 | |
201 | Catalyst Plugins |
202 | |
203 | The plugins used in this tutorial all have sufficiently stable APIs that |
204 | you shouldn't need to worry about versions. However, there could be |
205 | cases where the tutorial is affected by what version of plugins you |
206 | use. This tutorial has been tested against the following set of plugins: |
207 | |
208 | =over 4 |
209 | |
210 | =item * |
211 | |
1def4a20 |
212 | Catalyst::Plugin::Authentication -- v0.10002 |
d442cc9f |
213 | |
214 | =item * |
215 | |
1def4a20 |
216 | Catalyst::Plugin::Authentication::Store::DBIC -- v0.09 |
d442cc9f |
217 | |
218 | =item * |
219 | |
1def4a20 |
220 | Catalyst::Plugin::Authorization::ACL -- v0.08 |
d442cc9f |
221 | |
222 | =item * |
223 | |
1def4a20 |
224 | Catalyst::Plugin::Authorization::Roles -- v0.05 |
d442cc9f |
225 | |
226 | =item * |
227 | |
1def4a20 |
228 | Catalyst::Plugin::ConfigLoader -- v0.17 |
d442cc9f |
229 | |
230 | =item * |
231 | |
1def4a20 |
232 | Catalyst::Plugin::Session -- v0.18 |
d442cc9f |
233 | |
234 | =item * |
235 | |
1def4a20 |
236 | Catalyst::Plugin::Session::State::Cookie -- v0.08 |
d442cc9f |
237 | |
238 | =item * |
239 | |
1def4a20 |
240 | Catalyst::Plugin::Session::Store::FastMmap -- v0.03 |
d442cc9f |
241 | |
242 | =item * |
243 | |
1def4a20 |
244 | Catalyst::Plugin::StackTrace -- v0.06 |
d442cc9f |
245 | |
246 | =item * |
247 | |
1def4a20 |
248 | Catalyst::Plugin::Static::Simple -- v0.20 |
d442cc9f |
249 | |
250 | =back |
251 | |
252 | =item * |
253 | |
254 | Since the web browser is being used on the same box where Perl and the |
255 | Catalyst development server is running, the URL of |
256 | C<http://localhost:3000> will be used (the Catalyst development server |
257 | defaults to port 3000). If you are running Perl on a different box than |
258 | where your web browser is located (or using a different port number via |
259 | the C<-p> I<port_number> option to the development server), then you |
260 | will need to update the URL you use accordingly. |
261 | |
262 | =item * |
263 | |
264 | Depending on the web browser you are using, you might need to hit |
265 | C<Shift+Reload> to pull a fresh page when testing your application at |
266 | various points. Also, the C<-k> keepalive option to the development |
267 | server can be necessary with some browsers (especially Internet |
268 | Explorer). |
269 | |
270 | =back |
271 | |
272 | =head1 CATALYST INSTALLATION |
273 | |
1def4a20 |
274 | If approach in the wrong manner, it can be a daunting tasks to get |
275 | Catalyst initally installed. Although a compelling strength of |
276 | Catalyst is that it makes use of many of the modules in the |
277 | vast repository that is CPAN, this can complicate the installation |
278 | process. However, there are a growing number of methods |
279 | that can dramatically ease this undertaking. Of these, the following |
280 | are likely to be applicable to the largest number of potential new |
281 | users: |
282 | |
283 | =over 4 |
284 | |
285 | =item * |
286 | |
287 | Ubuntu |
288 | |
289 | Given the popularity of Ubuntu and it's ease of use, Ubuntu can be |
290 | a great way for newcomers to experiment with Catalyst. Because it |
291 | is a "live CD," you can simply boot from the CD, run a few commands, |
292 | and you should have a fully functional environment in which to do |
293 | this tutorial in a matter of minutes. |
d442cc9f |
294 | |
295 | =over 4 |
296 | |
297 | =item * |
298 | |
1def4a20 |
299 | Download Ubuntu 8.04 (aka, Hardy Heron) and boot from the CD and/or |
300 | image file, select your language, and then "Try Ubuntu without any |
301 | changes to your computer." |
302 | |
303 | =item * |
304 | |
305 | Open a terminal session. |
306 | |
307 | =item * |
308 | |
309 | Add the 'universe' repositories: |
310 | |
311 | sudo vi /etc/apt/sources.list |
312 | |
313 | And remove the comments from the lines under the comments about the |
314 | 'universe' repositories. |
315 | |
316 | =item * |
317 | |
318 | Install Catalyst: |
319 | |
320 | sudo apt-get update |
321 | sudo apt-get upgrade |
322 | sudo apt-get install sqlite3 libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl |
323 | |
324 | Accept all of the dependencies. Done. |
325 | |
326 | =back |
327 | |
328 | =item * |
329 | |
d442cc9f |
330 | Matt Trout's C<cat-install> |
331 | |
332 | Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>, |
333 | C<cat-install> can be a quick and painless way to get Catalyst up and |
334 | running. Just download the script from the link above and type C<perl |
335 | cat-install>. |
336 | |
337 | =item * |
338 | |
339 | Chris Laco's CatInABox |
340 | |
341 | Download the tarball from |
342 | L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it |
343 | on your machine. Depending on your OS platform, either run C<start.bat> |
344 | or C<start.sh>. |
345 | |
346 | =item * |
347 | |
348 | Pre-Built VMWare Images |
349 | |
350 | Under the VMWare community program, work is ongoing to develop a number |
351 | of VMWare images where an entire Catalyst development environment has |
352 | already been installed, complete with database engines and a full |
353 | complement of Catalyst plugins. |
354 | |
355 | =back |
356 | |
357 | For additional information and recommendations on Catalyst installation, |
358 | please refer to |
359 | L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>. |
360 | |
361 | B<NOTE:> Step-by-step instructions to replicate the environment on |
362 | which this tutorial was developed can be found at |
363 | L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>. |
364 | Using these instructions, you should be able to build a complete CentOS |
365 | 4.X server with Catalyst and all the plugins required to run this |
366 | tutorial. |
367 | |
368 | =head1 DATABASES |
369 | |
370 | This tutorial will primarily focus on SQLite because of its simplicity |
371 | of installation and use; however, modifications in the script required |
372 | to support MySQL and PostgreSQL will be presented in Appendix 2. |
373 | |
374 | B<Note:> One of the advantages of the MVC design patterns is that |
375 | applications become much more database independent. As such, you will |
376 | notice that only the C<.sql> files used to initialize the database |
377 | change between database systems: the Catalyst code generally remains the |
378 | same. |
379 | |
380 | =head1 WHERE TO GET WORKING CODE |
381 | |
382 | Each part of the tutorial has complete code available in the main |
383 | Catalyst Subversion repository (see the note at the beginning of each |
384 | part for the appropriate svn command to use). Additionally, the final |
385 | code is available as a ready-to-run tarball at |
386 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz>. |
387 | |
388 | B<NOTE:> You can run the test cases for the final code with the following |
389 | commands: |
390 | |
391 | wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz |
392 | tar zxvf MyApp.tgz |
393 | cd MyApp |
394 | CATALYST_DEBUG=0 prove --lib lib t |
395 | |
396 | |
397 | =head1 AUTHOR |
398 | |
399 | Kennedy Clark, C<hkclark@gmail.com> |
400 | |
401 | Please report any errors, issues or suggestions to the author. The |
402 | most recent version of the Catalyst Tutorial can be found at |
d712b826 |
403 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>. |
d442cc9f |
404 | |
405 | Copyright 2006, Kennedy Clark, under Creative Commons License |
406 | (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>). |
407 | |
408 | |