Commit | Line | Data |
4d583dd8 |
1 | =head1 NAME |
2 | |
64ccd8a8 |
3 | Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction |
4d583dd8 |
4 | |
5 | |
4d583dd8 |
6 | =head1 OVERVIEW |
7 | |
653f4595 |
8 | This is B<Part 1 of 9> of the Catalyst Tutorial. |
4d583dd8 |
9 | |
64ccd8a8 |
10 | L<Tutorial Overview|Catalyst::Manual::Tutorial> |
4d583dd8 |
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 | |
653f4595 |
24 | L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD> |
4d583dd8 |
25 | |
26 | =item 4 |
27 | |
28 | L<Authentication|Catalyst::Manual::Tutorial::Authentication> |
29 | |
30 | =item 5 |
31 | |
32 | L<Authorization|Catalyst::Manual::Tutorial::Authorization> |
33 | |
34 | =item 6 |
35 | |
36 | L<Debugging|Catalyst::Manual::Tutorial::Debugging> |
37 | |
38 | =item 7 |
39 | |
40 | L<Testing|Catalyst::Manual::Tutorial::Testing> |
41 | |
42 | =item 8 |
43 | |
653f4595 |
44 | L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD> |
4d583dd8 |
45 | |
46 | =item 9 |
47 | |
653f4595 |
48 | L<Appendices|Catalyst::Manual::Tutorial::Appendices> |
4d583dd8 |
49 | |
50 | =back |
51 | |
4d583dd8 |
52 | =head1 DESCRIPTION |
53 | |
653f4595 |
54 | This tutorial provides a multipart introduction to the Catalyst web |
55 | framework. It seeks to provide a rapid overview of many of its most |
56 | commonly used features. The focus is on the real-world best practices |
64ccd8a8 |
57 | required in the construction of nearly all Catalyst applications. |
4d583dd8 |
58 | |
64ccd8a8 |
59 | Although the primary target of the tutorial is users new to the Catalyst |
60 | framework, experienced users may wish to review specific sections (for |
61 | example, how to use DBIC for their model classes or how to add |
62 | authentication and authorization to an existing application). |
4d583dd8 |
63 | |
936a5dd5 |
64 | You can obtain the code for all the tutorial examples from the |
65 | catalyst subversion repository by issuing the command: |
66 | |
67 | svn co http://dev.catalyst.perl.org/repos/Catalyst/tags/examples/Tutorial/MyApp/5.7/ CatalystTutorial |
68 | |
69 | This will download the current code for each tutorial chapter in the |
70 | CatalystTutorial directory. Each example application directory has |
71 | the same name as the tutorial chapter. |
72 | |
4d583dd8 |
73 | Subjects covered include: |
74 | |
75 | =over 4 |
76 | |
77 | =item * |
78 | |
79 | A simple application that lists and adds books. |
80 | |
81 | =item * |
82 | |
14e6feb0 |
83 | The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model. |
4d583dd8 |
84 | |
85 | =item * |
86 | |
653f4595 |
87 | How to write CRUD (Create, Read, Update, and Delete) operations in |
88 | Catalyst. |
4d583dd8 |
89 | |
90 | =item * |
91 | |
92 | Authentication ("auth"). |
93 | |
94 | =item * |
95 | |
96 | Role-based authorization ("authz"). |
97 | |
98 | =item * |
99 | |
8e956464 |
100 | Attempts to provide an example showing current (5.7XXX) Catalyst |
14e6feb0 |
101 | practices. For example, the use of |
33aee7ed |
102 | L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>, |
14e6feb0 |
103 | DBIC, L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader> |
104 | with C<myapp.yml>, the use of C<lib/MyApp/Controller/Root.pm> |
105 | vs. C<lib/MyApp.pm>, etc. |
4d583dd8 |
106 | |
107 | =item * |
108 | |
653f4595 |
109 | The use of Template Toolkit (TT) and the |
14e6feb0 |
110 | L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite> |
111 | view helper. |
4d583dd8 |
112 | |
113 | =item * |
114 | |
653f4595 |
115 | Useful techniques for troubleshooting and debugging Catalyst |
116 | applications. |
4d583dd8 |
117 | |
118 | =item * |
119 | |
653f4595 |
120 | The use of SQLite as a database (with code also provided for MySQL and |
121 | PostgreSQL). |
4d583dd8 |
122 | |
123 | =item * |
124 | |
cc548726 |
125 | The use of L<HTML::Widget|HTML::Widget> for automated form processing |
126 | and validation. |
4d583dd8 |
127 | |
128 | =back |
129 | |
653f4595 |
130 | This tutorial makes the learning process its main priority. For |
8112f931 |
131 | example, the level of comments in the code found here would likely be |
653f4595 |
132 | considered excessive in a "normal project". Because of their contextual |
133 | value, this tutorial will generally favor inline comments over a |
134 | separate discussion in the text. It also deliberately tries to |
135 | demonstrate multiple approaches to various features (in general, you |
136 | should try to be as consistent as possible with your own production |
137 | code). |
4d583dd8 |
138 | |
64ccd8a8 |
139 | Furthermore, this tutorial tries to minimize the number of controllers, |
140 | models, TT templates, and database tables. Although this does result in |
141 | things being a bit contrived at times, the concepts should be applicable |
142 | to more complex environments. More complete and complicated example |
143 | applications can be found in the C<examples> area of the Catalyst |
144 | Subversion repository at |
145 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>. |
4d583dd8 |
146 | |
64ccd8a8 |
147 | B<Note:> There are a variety of other introductory materials available |
148 | through the Catalyst web site and at |
149 | L<http://dev.catalyst.perl.org/wiki/UserIntroductions> and |
150 | L<http://dev.catalyst.perl.org/>. |
4d583dd8 |
151 | |
4d583dd8 |
152 | =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL |
153 | |
653f4595 |
154 | This tutorial was built using the following resources. Please note that |
155 | you may need to make adjustments for different environments and |
64ccd8a8 |
156 | versions: |
4d583dd8 |
157 | |
158 | =over 4 |
159 | |
160 | =item * |
161 | |
162 | OS = CentOS 4 Linux (RHEL 4) |
163 | |
164 | =item * |
165 | |
14e6feb0 |
166 | Catalyst v5.6902 |
4d583dd8 |
167 | |
168 | =item * |
169 | |
14e6feb0 |
170 | DBIx::Class v0.06003 |
4d583dd8 |
171 | |
172 | =item * |
173 | |
174 | Catalyst Plugins |
175 | |
653f4595 |
176 | The plugins used in this tutorial all have sufficiently stable APIs that |
177 | you shouldn't need to worry about versions. However, there could be |
178 | cases where the tutorial is affected by what version of plugins you |
f16ea55d |
179 | use. This tutorial has been tested against the following set of plugins: |
4d583dd8 |
180 | |
181 | =over 4 |
182 | |
183 | =item * |
184 | |
f16ea55d |
185 | Catalyst::Plugin::Authentication -- 0.09 |
4d583dd8 |
186 | |
187 | =item * |
188 | |
f16ea55d |
189 | Catalyst::Plugin::Authentication::Store::DBIC -- 0.07 |
4d583dd8 |
190 | |
191 | =item * |
192 | |
f16ea55d |
193 | Catalyst::Plugin::Authorization::ACL -- 0.08 |
4d583dd8 |
194 | |
195 | =item * |
196 | |
197 | Catalyst::Plugin::Authorization::Roles -- 0.04 |
198 | |
199 | =item * |
200 | |
f16ea55d |
201 | Catalyst::Plugin::ConfigLoader -- 0.13 |
4d583dd8 |
202 | |
203 | =item * |
204 | |
4d583dd8 |
205 | Catalyst::Plugin::HTML::Widget -- 1.1 |
206 | |
207 | =item * |
208 | |
f16ea55d |
209 | Catalyst::Plugin::Session -- 0.12 |
4d583dd8 |
210 | |
211 | =item * |
212 | |
f16ea55d |
213 | Catalyst::Plugin::Session::State::Cookie -- 0.05 |
4d583dd8 |
214 | |
215 | =item * |
216 | |
14e6feb0 |
217 | Catalyst::Plugin::Session::Store::FastMmap -- 0.02 |
4d583dd8 |
218 | |
219 | =item * |
220 | |
f16ea55d |
221 | Catalyst::Plugin::StackTrace -- 0.06 |
4d583dd8 |
222 | |
223 | =item * |
224 | |
225 | Catalyst::Plugin::Static::Simple -- 0.14 |
226 | |
227 | =back |
228 | |
229 | =item * |
230 | |
64ccd8a8 |
231 | Since the web browser is being used on the same box where Perl and the |
232 | Catalyst development server is running, the URL of |
233 | C<http://localhost:3000> will be used (the Catalyst development server |
234 | defaults to port 3000). If you are running Perl on a different box than |
235 | where your web browser is located (or using a different port number via |
236 | the C<-p> I<port_number> option to the development server), then you |
237 | will need to update the URL you use accordingly. |
4d583dd8 |
238 | |
239 | =item * |
240 | |
64ccd8a8 |
241 | Depending on the web browser you are using, you might need to hit |
242 | C<Shift+Reload> to pull a fresh page when testing your application at |
243 | various points. Also, the C<-k> keepalive option to the development |
244 | server can be necessary with some browsers (especially Internet |
245 | Explorer). |
4d583dd8 |
246 | |
247 | =back |
248 | |
4d583dd8 |
249 | =head1 CATALYST INSTALLATION |
250 | |
64ccd8a8 |
251 | Unfortunately, one of the most daunting tasks faced by newcomers to |
252 | Catalyst is getting it installed. Although a compelling strength of |
653f4595 |
253 | Catalyst is that it can easily make use of many of the modules in the |
254 | vast repository that is CPAN, this can result in initial installations |
255 | that are both time consuming and frustrating. However, there are a |
256 | growing number of methods that can dramatically ease this undertaking. |
257 | Of these, the following are likely to be applicable to the largest |
258 | number of potential new users: |
4d583dd8 |
259 | |
260 | =over 4 |
261 | |
262 | =item * |
263 | |
64ccd8a8 |
264 | Matt Trout's C<cat-install> |
4d583dd8 |
265 | |
64ccd8a8 |
266 | Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>, |
267 | C<cat-install> can be a quick and painless way to get Catalyst up and |
268 | running. Just download the script from the link above and type C<perl |
269 | cat-install>. |
4d583dd8 |
270 | |
271 | =item * |
272 | |
273 | Chris Laco's CatInABox |
274 | |
64ccd8a8 |
275 | Download the tarball from |
276 | L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it |
277 | on your machine. Depending on your OS platform, either run C<start.bat> |
278 | or C<start.sh>. |
4d583dd8 |
279 | |
280 | =item * |
281 | |
282 | Pre-Built VMWare Images |
283 | |
64ccd8a8 |
284 | Under the VMWare community program, work is ongoing to develop a number |
285 | of VMWare images where an entire Catalyst development environment has |
286 | already been installed, complete with database engines and a full |
287 | complement of Catalyst plugins. |
4d583dd8 |
288 | |
289 | =back |
290 | |
653f4595 |
291 | For additional information and recommendations on Catalyst installation, |
14e6feb0 |
292 | please refer to |
293 | L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>. |
4d583dd8 |
294 | |
14e6feb0 |
295 | B<NOTE:> Step-by-step instructions to replicate the environment on |
64ccd8a8 |
296 | which this tutorial was developed can be found at |
14e6feb0 |
297 | L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>. |
64ccd8a8 |
298 | Using these instructions, you should be able to build a complete CentOS |
299 | 4.X server with Catalyst and all the plugins required to run this |
300 | tutorial. |
4d583dd8 |
301 | |
4d583dd8 |
302 | =head1 DATABASES |
303 | |
653f4595 |
304 | This tutorial will primarily focus on SQLite because of its simplicity |
305 | of installation and use; however, modifications in the script required |
306 | to support MySQL and PostgreSQL will be presented in Appendix 2. |
4d583dd8 |
307 | |
64ccd8a8 |
308 | B<Note:> One of the advantages of the MVC design patterns is that |
309 | applications become much more database independent. As such, you will |
310 | notice that only the C<.sql> files used to initialize the database |
653f4595 |
311 | change between database systems: the Catalyst code generally remains the |
312 | same. |
4d583dd8 |
313 | |
314 | =head1 WHERE TO GET WORKING CODE |
315 | |
64ccd8a8 |
316 | Each part of the tutorial has complete code available in the main |
317 | Catalyst Subversion repository (see the note at the beginning of each |
318 | part for the appropriate svn command to use). Additionally, the final |
319 | code is available as a ready-to-run tarball at |
13852f97 |
320 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz>. |
4d583dd8 |
321 | |
a63e6e67 |
322 | |
4d583dd8 |
323 | =head1 AUTHOR |
324 | |
325 | Kennedy Clark, C<hkclark@gmail.com> |
326 | |
eed93301 |
327 | Please report any errors, issues or suggestions to the author. The |
7d310f12 |
328 | most recent version of the Catalyst Tutorial can be found at |
eed93301 |
329 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>. |
4d583dd8 |
330 | |
64ccd8a8 |
331 | Copyright 2006, Kennedy Clark, under Creative Commons License |
332 | (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>). |
4d583dd8 |
333 | |
4d583dd8 |
334 | |