Cleanup other references to myapp.yml to myapp.conf
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / CatalystBasics.pod
d442cc9f 1=head1 NAME
3Catalyst::Manual::Tutorial::CatalystBasics - Catalyst Tutorial - Part 2: Catalyst Application Development Basics
6=head1 OVERVIEW
3533daff 8This is B<Part 2 of 10> for the Catalyst tutorial.
d442cc9f 9
10L<Tutorial Overview|Catalyst::Manual::Tutorial>
12=over 4
14=item 1
18=item 2
20B<Catalyst Basics>
22=item 3
3533daff 24L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
d442cc9f 25
26=item 4
3533daff 28L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
d442cc9f 29
30=item 5
3533daff 32L<Authentication|Catalyst::Manual::Tutorial::Authentication>
d442cc9f 33
34=item 6
3533daff 36L<Authorization|Catalyst::Manual::Tutorial::Authorization>
d442cc9f 37
38=item 7
3533daff 40L<Debugging|Catalyst::Manual::Tutorial::Debugging>
d442cc9f 41
42=item 8
3533daff 44L<Testing|Catalyst::Manual::Tutorial::Testing>
d442cc9f 45
46=item 9
3533daff 48L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
50=item 10
d442cc9f 52L<Appendices|Catalyst::Manual::Tutorial::Appendices>
3533daff 59In this part of the tutorial, we will create a very basic Catalyst web
60application, demonstrating a number of powerful capabilities, such as:
d442cc9f 61
62=over 4
64=item * Helper Scripts
66Catalyst helper scripts that can be used to rapidly bootstrap the
67skeletal structure of an application.
69=item * MVC
71Model/View/Controller (MVC) provides an architecture that facilitates a
72clean "separation of control" between the different portions of your
73application. Given that many other documents cover this subject in
74detail, MVC will not be discussed in depth here (for an excellent
75introduction to MVC and general Catalyst concepts, please see
76L<Catalyst::Manual::About>. In short:
78=over 4
80=item * Model
82The model usually represents a data store. In most applications, the
83model equates to the objects that are created from and saved to your SQL
86=item * View
88The view takes model objects and renders them into something for the end
89user to look at. Normally this involves a template-generation tool that
90creates HTML for the user's web browser, but it could easily be code
91that generates other forms such as PDF documents, e-mails, or Excel
94=item * Controller
96As suggested by its name, the controller takes user requests and routes
97them to the necessary model and view.
101=item * ORM
103The use of Object-Relational Mapping (ORM) technology for database
104access. Specifically, ORM provides an automated and standardized means
105to persist and restore objects to/from a relational database.
109You can checkout the source code for this example from the catalyst
110subversion repository as per the instructions in
3533daff 113
d442cc9f 114=head1 CREATE A CATALYST PROJECT
3533daff 116Catalyst provides a number of helper scripts that can be used to
117quickly flesh out the basic structure of your application. All
118Catalyst projects begin with the C<> helper (see
119L<Catalyst::Helper|Catalyst::Helper> for more information on helpers).
120Also note that as of Catalyst 5.7000, you will not have the helper
121scripts unless you install both L<Catalyst::Runtime|Catalyst::Runtime>
122and L<Catalyst::Devel|Catalyst::Devel>.
124In this first part of the tutorial, use the Catalyst
125C<> script to initialize the framework for an
126application called C<Hello>:
128 $ Hello
129 created "Hello"
130 created "Hello/script"
131 created "Hello/lib"
132 created "Hello/root"
d442cc9f 133 ...
3533daff 134 created "Hello/script/"
135 $ cd Hello
d442cc9f 136
137The C<> helper script will display the names of the
3533daff 138directories and files it creates:
140 Changes # Record of application changes
141 lib # Lib directory for Perl modules
142 Hello # Application code directory
143 Controller # Directory for Controller modules
144 Model # Directory for Models
145 View # Directory for Views
146 # Base application module
147 Makefile.PL # Makefile to build application
45d511e0 148 hello.conf # Application configuration file
3533daff 149 README # README file
150 root # Equiv of htdocs, dir for templates, css, javascript
151 favicon.ico
152 static # Directory for static files
153 images # Directory for image files used in welcome screen
154 script # Directory for Perl scripts
155 # To run your app as a cgi (not recommended)
156 # To create models, views, controllers
157 # To run app as a fastcgi program
158 # The normal development server
159 # Test your app from the command line
160 t # Directory for tests
161 01app.t # Test scaffold
162 02pod.t
163 03podcoverage.t
166Catalyst will "auto-discover" modules in the Controller, Model, and
167View directories. When you use the script it will
168create Perl module scaffolds in those directories, plus test files in
169the "t" directory. The default location for templates is in the "root"
170directory. The scripts in the script directory will always start with
171the lowercased version of your application name. If your app is
172MaiTai, then the create script would be "".
174Though it's too early for any significant celebration, we already have
175a functioning application. We can use the Catalyst supplied script to
176start up a development server and view the default Catalyst page in
177your browser. All scripts in the script directory should be run from
178the base directory of your application, so change to the Hello
181Run the following command to start up the built-in development web
d442cc9f 183
3533daff 184 $ script/
d442cc9f 185 [debug] Debug messages enabled
186 [debug] Loaded plugins:
187 .----------------------------------------------------------------------------.
3533daff 188 | Catalyst::Plugin::ConfigLoader 0.17 |
189 | Catalyst::Plugin::Static::Simple 0.20 |
d442cc9f 190 '----------------------------------------------------------------------------'
192 [debug] Loaded dispatcher "Catalyst::Dispatcher"
193 [debug] Loaded engine "Catalyst::Engine::HTTP"
3533daff 194 [debug] Found home "/home/me/Hello"
195 [debug] Loaded Config "/home/me/Hello/hello.yml"
d442cc9f 196 [debug] Loaded components:
197 .-----------------------------------------------------------------+----------.
198 | Class | Type |
199 +-----------------------------------------------------------------+----------+
3533daff 200 | Hello::Controller::Root | instance |
d442cc9f 201 '-----------------------------------------------------------------+----------'
203 [debug] Loaded Private actions:
204 .----------------------+--------------------------------------+--------------.
205 | Private | Class | Method |
206 +----------------------+--------------------------------------+--------------+
3533daff 207 | /default | Hello::Controller::Root | default |
208 | /end | Hello::Controller::Root | end |
d442cc9f 209 '----------------------+--------------------------------------+--------------'
3533daff 211 [info] Hello powered by Catalyst 5.7011
d442cc9f 212 You can connect to your server at http://localhost:3000
3533daff 214Point your web browser to
215L<http://localhost:3000|http://localhost:3000> (substituting a
d442cc9f 216different hostname or IP address as appropriate) and you should be
217greeted by the Catalyst welcome screen. Information similar to the
218following should be appended to the logging output of the development
3533daff 221 [info] *** Request 1 (1.000/s) [10301] [Sun May 18 10:11:36 2008] ***
d442cc9f 222 [debug] "GET" request for "/" from ""
3533daff 223 [info] Request took 0.017964s (55.667/s)
d442cc9f 224 .----------------------------------------------------------------+-----------.
225 | Action | Time |
226 +----------------------------------------------------------------+-----------+
3533daff 227 | /default | 0.000540s |
228 | /end | 0.001246s |
d442cc9f 229 '----------------------------------------------------------------+-----------'
231Press Ctrl-C to break out of the development server.
3533daff 234=head1 HELLO WORLD
d442cc9f 235
3533daff 236=head2 The Simplest Way
d442cc9f 237
3533daff 238The controller is a place to put global actions that usually
239execute on the root URL. Open the C<lib/Hello/Controller/> file in
240your editor. You will see the "default" subroutine, which is
241responsible for displaying the welcome screen that you just saw in
242your browser. Later on you'll want to change that to something more
243reasonable, such as a "404" message but for now just leave it alone.
d442cc9f 244
3533daff 245 sub default : Path : Args {
246 my ( $self, $c ) = @_;
d442cc9f 247
3533daff 248 $c->response->body( $c->welcome_message );
d442cc9f 249 }
3533daff 251The "C<$c>" here refers to the Catalyst context, which is used to
252access the Catalyst application. In addition to many other things,
253the Catalyst context provides access to "response" and "request"
254objects. (See L<Catalyst>, L<Catalyst::Response>, and L<Catalyst::Request>)
d442cc9f 255
3533daff 256C<$c->response->body> sets the HTTP response (see
257L<Catalyst::Response>), while C<$c->welcome_message> is a special method
258that returns the welcome message that you saw in your browser.
d442cc9f 259
3533daff 260The ": Path : Args" after the method name are attributes which determine
261which URLs will be dispatched to this method. (Depending on your version of
262Catalyst, it used to say "Private" but using that with default is
263currently deprecated.)
d442cc9f 264
3533daff 265Some MVC frameworks handle dispatching in a central place. Catalyst,
266by policy, prefers to handle URL dispatching with attributes on
267controller methods. There is a lot of flexibility in specifying which
268URLs to match. This particular method will match all URLs, because it
269doesn't specify the path (nothing comes after "Path"), and will accept
270any number of args (nothing after args).
d442cc9f 271
3533daff 272The default is to map URLs to controller names, and because of
273the way that Perl handles namespaces through package names,
274it is simple to create hierarchical structures in
275Catalyst. This means that you can create controllers with deeply
276nested actions in a clean and logical way.
d442cc9f 277
3533daff 278For example, the URL C<> maps
279to the package C<Hello::Controller::Admin::Articles>, and the C<create>
d442cc9f 281
d442cc9f 282
3533daff 283Add the following subroutine to your file:
d442cc9f 284
3533daff 285 sub hello : Global {
286 my ( $self, $c ) = @_;
287 $c->response->body("Hello, World!");
288 }
d442cc9f 289
3533daff 290Here you're sending your own string to the webpage.
292Save the file, start the server (stop and restart it if it's still
293up), and go to L<http://localhost:3000/hello|http://localhost:3000> to
294see "Hello, World!"
296=head2 Hello, World! Using a View and a Template
298In the Catalyst world a "View" is not a page of XHTML or a template
299designed to present a page to a browser. It is the module that
300determines the type of view--HTML, pdf, XML. For the case of a
301template view (such as the default Toolkit Template) the actual
302templates go under the "root" directory.
304To create a TT view, run:
306 $ script/ view TT TT
308This creates the C<lib/Hello/View/> module, which is a subclass of
309C<Catalyst::View::TT>. The "view" keyword tells the create script that
310you are creating a view, the first "TT" tells it that you are creating
311a Template Toolkit view, and the second "TT" tells the script to name
312the View module "", which is a commonly used name for TT views.
313(You can name it anything you want, such as "".) If you look at, you will find that it only contains a config statement to set
315the TT extension to ".tt".
317Now that the "View" exists, Catalyst will autodiscover it and be
318able to use it to display the view templates, using the "process"
319method that it inherits from the C<Catalyst::View::TT class>.
c010ae0d 321Template Toolkit is a very full featured template facility, with
322excellent documentation at
3533daff 323L<|>,
324but since this is not a TT tutorial, we'll stick to only basic TT
325usage here (and explore some of the more common TT features in later
326parts of the tutorial).
328Create a C<root/> template file (put it in the C<root> under
329the C<Hello> directory that is the base of your application). Here is
330a simple sample:
332 [% META title = 'Hello, World!' %]
333 <p>
334 This is a TT view template, located in the root directory.
335 </p>
337[% and %] are markers for the TT parts of the template. Inside you can
338access Perl variables and classes, and use TT directives. The rest of
339the template is normal HTML. Change the hello method in to the
342 sub hello : Global {
343 my ( $self, $c ) = @_;
344 $c->stash->{template} = '';
345 }
d442cc9f 346
3533daff 347This time, instead of doing C<$c->response->body()>, you are setting
348the value of the "template" hash key in the Catalyst "stash", an area
349for putting information to share with other parts of your application.
350The "template" key determines which template will be displayed at the
351end of the method. Catalyst controllers have a default "end" action
352for all methods which causes the first (or default) view to be
353rendered (unless there's a C<$c->response->body()> statement). So your
354template will be magically displayed at the end of your method.
d442cc9f 355
3533daff 356After saving the file, restart the development server, and look at
357L<http://localhost:3000/hello|http://localhost:3000> again. You should
358see the template that you just made.
d442cc9f 359
d442cc9f 360
d442cc9f 362
3533daff 363Create a controller named "Site" by executing the create script:
d442cc9f 364
3533daff 365 $ script/ controller Site
d442cc9f 366
3533daff 367This will create a C<lib/Hello/Controller/> file (and a test
368file). Bring up in your editor, and you can see that there's
369not much there. Most people probably don't bother to use the create
370script to make controllers after they're used to using Catalyst.
d442cc9f 371
3533daff 372In, add the following method:
d442cc9f 373
3533daff 374 sub test : Local {
375 my ( $self, $c ) = @_;
376 $c->stash->{username} = "John";
377 $c->stash->{template} = 'site/';
d442cc9f 378 }
3533daff 380Notice the "Local" attribute on the method. This will allow the action
381to be executed on the "controller/method" URL, or, in this case,
382"site/test", instead of at the root site URL, like "Global". It's not
383actually necessary to set the template value, since by default TT will
384attempt to render a template that follows the naming pattern
385"controller/", and we're following that pattern here, but in
386other situations you will need to specify the template (such as if
387you've "forwarded" to the method, or if it doesn't follow the default
388naming convention). We've also put the variable "name" into the stash,
389for use in the template.
d442cc9f 390
3533daff 391Make a subdirectory "site" in the "root" directory. Copy the
392file into the directory as root/site/, or create a new template
393file at that location. Include a line like:
d442cc9f 394
3533daff 395 <p>Hello, [% username %]!</p>
d442cc9f 396
3533daff 397Bring up or restart the server. Notice in the server output that
398C</site/test> is listed in the Loaded Path actions. Go to
d442cc9f 400
3533daff 401You should see your file displayed, including the name "John"
402that you set in the controller.
d442cc9f 403
d442cc9f 404
3533daff 405=head1 AUTHORS
d442cc9f 406
3533daff 407Gerda Shank, C<>
d442cc9f 408Kennedy Clark, C<>
410Please report any errors, issues or suggestions to the author. The
411most recent version of the Catalyst Tutorial can be found at
d712b826 412L<>.
d442cc9f 413
3533daff 414Copyright 2006, Kennedy Clark & Gerda Shank, under Creative Commons License
d442cc9f 415(L<>).